Offline write-queue: coalesce + replay without duplicating (#33)

While gitea is unreachable, propose-approved writes queue instead of being lost;
on reconnect they replay in order. The hard requirement is no duplication.

The mechanism is coalescing by axis. Every write targets one field of one issue
(estimate / priority / assignee / milestone), so `issue:kind` is the axis identity.
Queuing a second write to the same axis supersedes the first (moved to the tail),
so a burst of edits replays as one final write — and replay is idempotent (the
apply path no-ops a change already reflected server-side).

- `enqueueWrite` (coalesce), `pendingWrites`, `coalesceKey`, `affectedIssues`
  (what a post-replay reconcile re-reads), and `replayQueue(queue, apply)` which
  drains through the same guarded write path and returns the writes that still
  failed so they stay queued. Never throws — a failure is data.

Acceptance met: a burst of offline edits + reconnect lands the final state with a
single apply per axis (not one per edit); still-failing writes stay queued. +4
core tests; typecheck green.

Follow-up: persist the queue in main + trigger replay on the reconnect signal
(the offline banner + disabled composer already exist) — the coalesce/replay
core is the tested heart.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/desktop/src/renderer/src/components/screens/calibration-screen.tsx

@@ -178,6 +178,9 @@ export function CalibrationScreen({ onBack, data }: { onBack: () => void; data?:
               {c.active
                 ? 'You are not bad at estimating; you are optimistic in a very stable way. Stable, I can work with.'
                 : 'Not enough closed history yet — I’m forecasting from cold-start priors and widening the cone to stay honest. The curve takes over at 20.'}
+              {!c.active && c.excludedSameDay > 0
+                ? ` And ${c.excludedSameDay} closed ${c.excludedSameDay === 1 ? 'issue' : 'issues'} closed the same day they were started — 0 working days can’t calibrate, so they don’t count toward the 20.`
+                : ''}
             </p>
           </Card>
         </div>

apps/desktop/src/renderer/src/components/screens/runway-screen.tsx

@@ -17,7 +17,7 @@ export function RunwayScreen({
 }: {
   onOpenCalibration: () => void
   onOpenMilestone: (id?: number) => void
-  calibration?: { n: number; coldStart: boolean }
+  calibration?: { n: number; coldStart: boolean; excludedSameDay?: number }
   milestones?: RunwayMilestone[]
   capacity?: CapacityMember[]
 }) {
@@ -30,9 +30,11 @@ export function RunwayScreen({
           hours: `${capacityPerWorkday(m).toFixed(2)} pd/day`,
         }))
       : CAPACITY
+  const excluded = calibration?.excludedSameDay ?? 0
   const calibNote = calibration
     ? calibration.coldStart
-      ? `cold-start priors · ${calibration.n}/20 closed issues estimated`
+      ? `cold-start priors · ${calibration.n}/20 closed issues estimated` +
+        (excluded > 0 ? ` · ${excluded} same-day close${excluded === 1 ? '' : 's'} can’t calibrate` : '')
       : `calibrated on ${calibration.n} closed ${calibration.n === 1 ? 'issue' : 'issues'}`
     : 'calibrated on 27 closed issues'
   return (

apps/desktop/src/renderer/src/components/shell/app-shell.tsx

@@ -306,7 +306,15 @@ export function AppShell() {
               setMilestoneId(id ?? null)
               setView('milestone')
             }}
-            calibration={calibration ? { n: calibration.model.n, coldStart: calibration.model.coldStart } : undefined}
+            calibration={
+              calibration
+                ? {
+                    n: calibration.model.n,
+                    coldStart: calibration.model.coldStart,
+                    excludedSameDay: calibration.coverage.excludedSameDay,
+                  }
+                : undefined
+            }
             milestones={runwayMilestones}
             capacity={capacityMembers}
           />

apps/desktop/src/renderer/src/data/fixtures.ts

@@ -361,11 +361,14 @@ export interface CalibrationData {
   scatter: number[][]
   fit: number
   effect: { raw: string; banded: string; p50: string }
+  /** Closed+estimated issues that can't calibrate (same-day / 0-day closes). */
+  excludedSameDay: number
 }
 
 export const CALIBRATION: CalibrationData = {
   n: 27,
   active: true,
+  excludedSameDay: 0,
   labels: [
     { label: 'est/1d', n: 8, median: '1.1d', bias: 8 },
     { label: 'est/2d', n: 9, median: '2.4d', bias: 18 },

apps/desktop/src/renderer/src/lib/backlog.ts

@@ -1,6 +1,8 @@
 import {
+  type CalibrationCoverage,
   type CalibrationModel,
   type CalibrationSample,
+  calibrationCoverage,
   calibrationSamples,
   type CapacityMember,
   capacityPerWorkday,
@@ -171,10 +173,11 @@ export function backlogCalibration(
   issues: GiteaIssue[],
   timelines: Timelines = {},
   asOf: Date = new Date(),
-): { model: CalibrationModel; data: CalibrationData } {
+): { model: CalibrationModel; data: CalibrationData; coverage: CalibrationCoverage } {
   const samples = calibrationSamples(issues, timelines, asOf)
   const model = fitCalibration(samples)
-  return { model, data: calibrationData(model, samples, issues) }
+  const coverage = calibrationCoverage(issues, timelines, asOf)
+  return { model, coverage, data: calibrationData(model, samples, issues, coverage.excludedSameDay) }
 }
 
 const pctFromMu = (mu: number) => Math.round((Math.exp(mu) - 1) * 100)
@@ -188,6 +191,7 @@ export function calibrationData(
   model: CalibrationModel,
   samples: CalibrationSample[],
   openIssues: GiteaIssue[],
+  excludedSameDay = 0,
 ): CalibrationData {
   const labels = PRIOR_BUCKETS.map((b) => {
     const inBucket = samples.filter((s) => s.bucket === b)
@@ -227,6 +231,7 @@ export function calibrationData(
     scatter: samples.map((s) => [s.estimateDays, s.actualWorkingDays]),
     fit: Number(Math.exp(model.global.mu).toFixed(2)),
     effect,
+    excludedSameDay,
   }
 }
 

packages/core/src/calibration/calibration-v0.test.ts

@@ -5,6 +5,7 @@ import type { LifecycleEvent } from '../lifecycle/lifecycle-v0.js'
 import type { GiteaIssue } from '../gitea/types.js'
 import {
   CALIBRATION_BUCKET_FLOOR,
+  calibrationCoverage,
   calibrationSamples,
   type CalibrationSample,
   COLD_START_THRESHOLD,
@@ -118,4 +119,26 @@ describe('calibrationSamples', () => {
     const noEst = issue({ number: 9, labels: [] })
     expect(calibrationSamples([open, noEst], { ...events(8), ...events(9) }, asOf)).toEqual([])
   })
+
+  it('coverage counts same-day closes as excluded candidates, not as "more closes needed"', () => {
+    // usable: commit Wed 01-07 → close Mon 01-12 = 3 working days
+    const usable = issue({ number: 7, labels: ['est/2d'] })
+    // same-day close: commit and close on the same day = 0 working days → excluded
+    const sameDay = issue({ number: 10, labels: ['est/2d'], createdAt: '2026-01-12T08:00:00Z' })
+    const sameDayEvents = {
+      10: [
+        { type: 'commit', at: '2026-01-12T09:00:00Z' } as LifecycleEvent,
+        { type: 'close', at: '2026-01-12T17:00:00Z' } as LifecycleEvent,
+      ],
+    }
+    const open = issue({ number: 8, state: 'open', labels: ['est/2d'], closedAt: null })
+    const noEst = issue({ number: 9, labels: [] })
+
+    const cov = calibrationCoverage([usable, sameDay, open, noEst], { ...events(7), ...sameDayEvents }, asOf)
+    expect(cov.candidates).toBe(2) // closed + estimated only (usable + sameDay)
+    expect(cov.usable).toBe(1)
+    expect(cov.excludedSameDay).toBe(1)
+    // the honest denominator: usable matches the model's n
+    expect(cov.usable).toBe(calibrationSamples([usable, sameDay, open, noEst], { ...events(7), ...sameDayEvents }, asOf).length)
+  })
 })

packages/core/src/calibration/calibration-v0.ts

@@ -125,3 +125,40 @@ export function calibrationSamples(
   }
   return out
 }
+
+/** How the closed+estimated backlog splits into usable samples vs. what can't calibrate. */
+export interface CalibrationCoverage {
+  /** Closed issues carrying an estimate — the calibration candidates. */
+  candidates: number
+  /** Candidates that yielded a usable actual (> 0 working days) → become samples. */
+  usable: number
+  /**
+   * Candidates excluded because the issue closed with 0 working days (same-day
+   * close) or no resolvable actual — real closes that structurally can't
+   * calibrate. Counting them keeps `usable/threshold` honest: it's not "N more
+   * closes away" if some of your closes will never count.
+   */
+  excludedSameDay: number
+}
+
+/**
+ * Coverage of the calibration candidates — how many closed+estimated issues are
+ * usable vs. silently unusable (same-day / 0-day closes). {@link calibrationSamples}
+ * drops the latter; this counts them so the UI can say *why* the sample is thin.
+ */
+export function calibrationCoverage(
+  issues: GiteaIssue[],
+  timelines: Record<number, LifecycleEvent[]>,
+  asOf: Date,
+): CalibrationCoverage {
+  let candidates = 0
+  let usable = 0
+  for (const issue of issues) {
+    if (issue.state !== 'closed') continue
+    if (issue.facts.estimateDays == null) continue
+    candidates++
+    const inf = inferLifecycle(issue, timelines[issue.number] ?? [], asOf)
+    if (inf.actualWorkingDays != null && inf.actualWorkingDays > 0) usable++
+  }
+  return { candidates, usable, excludedSameDay: candidates - usable }
+}

packages/core/src/index.ts

@@ -23,6 +23,8 @@ export type {
   GiteaRequestInit,
 } from './gitea/types.js'
 
+export { affectedIssues, coalesceKey, enqueueWrite, pendingWrites, replayQueue } from './queue/write-queue-v0.js'
+export type { QueuedWrite } from './queue/write-queue-v0.js'
 export { describeChange, isLabelChange, planIssueChange, proposalsFor, summarizeChange } from './changes/apply-changes-v0.js'
 export type {
   ChangeProposal,
@@ -80,6 +82,7 @@ export type {
 
 export {
   CALIBRATION_BUCKET_FLOOR,
+  calibrationCoverage,
   calibrationSamples,
   COLD_START_THRESHOLD,
   fitCalibration,
@@ -87,6 +90,7 @@ export {
 } from './calibration/calibration-v0.js'
 export type {
   BucketFit,
+  CalibrationCoverage,
   CalibrationModel,
   CalibrationSample,
   PersonBias,

packages/core/src/queue/write-queue-v0.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { IssueChange } from '../changes/apply-changes-v0.js'
+import { affectedIssues, coalesceKey, enqueueWrite, pendingWrites, replayQueue, type QueuedWrite } from './write-queue-v0.js'
+
+const reest = (issue: number, estimate: string): IssueChange =>
+  ({ kind: 'reestimate', issue, estimate }) as IssueChange
+const assign = (issue: number, assignee: string | null): IssueChange => ({ kind: 'assign', issue, assignee })
+
+describe('write-queue-v0 (#33)', () => {
+  it('coalesces repeat writes to the same (issue, axis) — replay applies the latest once', () => {
+    let q: QueuedWrite[] = []
+    q = enqueueWrite(q, reest(7, 'est/2d'), '2026-02-10T09:00:00Z')
+    q = enqueueWrite(q, reest(7, 'est/5d'), '2026-02-10T09:05:00Z') // supersedes est/2d
+    q = enqueueWrite(q, assign(7, 'christian'), '2026-02-10T09:06:00Z') // different axis — kept
+
+    expect(q).toHaveLength(2)
+    const pending = pendingWrites(q)
+    expect(pending).toEqual([
+      { kind: 'reestimate', issue: 7, estimate: 'est/5d' },
+      { kind: 'assign', issue: 7, assignee: 'christian' },
+    ])
+    expect(coalesceKey(reest(7, 'est/2d'))).toBe('7:reestimate')
+  })
+
+  it('keeps writes to different issues and axes distinct', () => {
+    let q: QueuedWrite[] = []
+    q = enqueueWrite(q, reest(7, 'est/2d'), 't1')
+    q = enqueueWrite(q, reest(8, 'est/3d'), 't2')
+    q = enqueueWrite(q, assign(8, null), 't3')
+    expect(q).toHaveLength(3)
+    expect(affectedIssues(q)).toEqual([7, 8])
+  })
+
+  it('a burst of edits then reconnect lands the final state without duplicating', async () => {
+    let q: QueuedWrite[] = []
+    // offline: three edits to #7's estimate, one assign
+    q = enqueueWrite(q, reest(7, 'est/1d'), 't1')
+    q = enqueueWrite(q, reest(7, 'est/2d'), 't2')
+    q = enqueueWrite(q, reest(7, 'est/8d'), 't3')
+    q = enqueueWrite(q, assign(7, 'stephen'), 't4')
+
+    const apply = vi.fn(async () => ({ ok: true }))
+    const { drained, remaining } = await replayQueue(q, apply)
+
+    // only the final estimate + the assign are applied — not three estimate writes
+    expect(apply).toHaveBeenCalledTimes(2)
+    expect(apply).toHaveBeenNthCalledWith(1, { kind: 'reestimate', issue: 7, estimate: 'est/8d' })
+    expect(apply).toHaveBeenNthCalledWith(2, { kind: 'assign', issue: 7, assignee: 'stephen' })
+    expect(remaining).toHaveLength(0)
+    expect(drained).toHaveLength(2)
+  })
+
+  it('keeps writes that still fail on reconnect queued (never throws)', async () => {
+    let q: QueuedWrite[] = []
+    q = enqueueWrite(q, reest(7, 'est/2d'), 't1')
+    q = enqueueWrite(q, reest(8, 'est/3d'), 't2')
+    // #7 applies, #8 rejects (still unreachable) — and one apply throws
+    const apply = vi.fn(async (c: IssueChange) => {
+      if (c.issue === 8) throw new Error('offline')
+      return { ok: true }
+    })
+    const { drained, remaining } = await replayQueue(q, apply)
+    expect(drained.map((w) => w.change.issue)).toEqual([7])
+    expect(remaining.map((w) => w.change.issue)).toEqual([8])
+  })
+})

packages/core/src/queue/write-queue-v0.ts

@@ -0,0 +1,71 @@
+/**
+ * Offline write-queue, v0 (#33). While gitea is unreachable, propose-approved
+ * writes are queued instead of lost; on reconnect they replay in order and
+ * resolve against a fresh reconcile. The one hard requirement is *no duplication*:
+ * replaying must not apply the same intent twice.
+ *
+ * The mechanism is coalescing by axis. Every write targets one field of one issue
+ * (its estimate, priority, assignee, or milestone). Queuing a second write to the
+ * same (issue, axis) supersedes the first — only the latest intent survives — so
+ * a burst of edits replays as one final write, and a replay is idempotent (the
+ * apply path no-ops a change already reflected server-side).
+ */
+
+import type { IssueChange } from '../changes/apply-changes-v0.js'
+
+export interface QueuedWrite {
+  change: IssueChange
+  /** ISO time the write was queued (for display + stable ordering). */
+  queuedAt: string
+}
+
+/**
+ * The coalescing key: one field of one issue. Two writes with the same key are
+ * the same intent expressed twice — the later wins. Each `IssueChange.kind` maps
+ * to exactly one axis, so `issue:kind` is the axis identity.
+ */
+export function coalesceKey(change: IssueChange): string {
+  return `${change.issue}:${change.kind}`
+}
+
+/**
+ * Queue a write, superseding any pending write to the same (issue, axis). The
+ * superseding write moves to the tail so replay order reflects latest intent.
+ */
+export function enqueueWrite(queue: readonly QueuedWrite[], change: IssueChange, queuedAt: string): QueuedWrite[] {
+  const key = coalesceKey(change)
+  return [...queue.filter((w) => coalesceKey(w.change) !== key), { change, queuedAt }]
+}
+
+/** The changes to replay, in order — one per (issue, axis) by construction. */
+export function pendingWrites(queue: readonly QueuedWrite[]): IssueChange[] {
+  return queue.map((w) => w.change)
+}
+
+/** Distinct issues touched by the queue — what a post-replay reconcile should re-read. */
+export function affectedIssues(queue: readonly QueuedWrite[]): number[] {
+  return [...new Set(queue.map((w) => w.change.issue))]
+}
+
+/**
+ * Replay the queue through an apply function (the same guarded write path used
+ * online), in order. Returns the writes that failed (still unreachable / rejected)
+ * so they stay queued; everything else drains. Never throws — a failure is data.
+ */
+export async function replayQueue(
+  queue: readonly QueuedWrite[],
+  apply: (change: IssueChange) => Promise<{ ok: boolean }>,
+): Promise<{ drained: QueuedWrite[]; remaining: QueuedWrite[] }> {
+  const drained: QueuedWrite[] = []
+  const remaining: QueuedWrite[] = []
+  for (const w of queue) {
+    let ok = false
+    try {
+      ok = (await apply(w.change)).ok
+    } catch {
+      ok = false
+    }
+    ;(ok ? drained : remaining).push(w)
+  }
+  return { drained, remaining }
+}