Skip to content

Ticket #218: native reconciliation and support surface — verification ​

  • Date: 2026-11-11
  • Branch: ticket/218-reconciliation
  • Spec: parent #209; ticket #218
  • ADRs: 0005, 0008, 0010
  • Unit gate: npm run verify (strict typecheck + full test suite)

Reconciliation triggers and limits ​

Each bound session is reconciled once per trigger against one session.context read:

TriggerPathBehavior
Service startstart() before the maintenance timerevery unique bound session, awaited
Location reconnect / new locationtrackLocation after the first location attachevery unique bound session, off the event path
Host session reappearssession.created for a bound sessionthat session only, off the event path
AdoptionadoptNativeSession after the binding write and before the heads-upthe adopted session only, awaited
WatchdogperformMaintenance (#217 bound)one turn, at most the configured read count

The transcript is read only at those points and at the existing settlement fallback for an incomplete text.ended set. The TUI never polls session.context; the heartbeat carries only the nativeSync label. A per-session reconcile is serialized on the same queue as host ingestion, and concurrent triggers coalesce into the run already in flight.

Recovered identity is deterministic: user message id = inbox id, turn id = nativeTurnID(sessionID, inboxID), assistant row id = nativeAssistantMessageID(turnID). A pre-reconciliation turn id is adopted by matching its recorded inbox id, so a restart does not duplicate a row.

What reconciliation repairs ​

  • A missing user turn and user row are recreated from a user/synthetic context message. Synthetic completions create a turn but no user row.
  • A missing assistant identity is merged into the durable turn; a missing assistant row is written as the exact final text and linked as the result.
  • A terminal turn (replied, failed, cancelled, interrupted) with a missing, streaming, empty, or drifted result row is repaired from the native transcript and its result id is restored.
  • An open turn with an answer settles replied unless a live execution, a held background child, or a recent watchdog receipt says it may still be running.
  • An answerless open turn settles interrupted only when the transcript's idle marker follows that turn's own user row. Without terminal evidence it stays working; time alone never guesses an interruption.
  • Internal/onboarding prompts are skipped. A managed service prompt attaches to its existing durable user row instead of mirroring a second one.

#215 merge-review fix ​

nativeTextTurn resolves a recorded assistant message id before consulting the session's active-turn marker. Late text for a settled turn now returns that settled turn and is an idempotent no-op: it neither pins the marker nor joins the next turn's final text. The regression sends the next turn's text first and replays the old turn's delta while the next turn is active.

Logging contract ​

Native logs carry ids, counts, phases, and reason codes only:

  • native.reconcile.start|done|session — session id, reason code, session/ failure/turn and recovery counts.
  • native.turn.recovered, native.message.recovered — session/turn/inbox/ message/assistant-message ids and a reason code.
  • native.turn.result.repaired — turn, inbox, assistant-message, result-message ids, phase, reason code.
  • native.turn.settled, native.turn.interruption, native.route.created — turn/session/inbox/route-task/agent ids, phase, reason code.
  • native.sync — state and reason code on a state change.
  • task.created never logs a native turn title (its instruction/title is conversation content).
  • Host error messages, paths, prompt text, answer text, and file bytes never enter a native log. A test seeds private markers and asserts none appear.

Doctor invariants ​

The diagnostic now carries a native block (sync state plus in-memory watchdog passes/held flags) and native identity rows. The doctor reports:

  • activeTurns — open queued/working/retrying native turns.
  • native_turn_duplicate — duplicate inbox identity, assistant identity, result/user/assistant row identity, multiple open turns per session, or one session bound to multiple conversations.
  • native_turn_missing_result — a replied turn with assistant ids but no result id, or any terminal turn naming a missing result row.
  • native_route_orphaned — a non-native task whose native parent turn is missing (id/group provenance).
  • native_turn_stuck — an open turn whose watchdog passes are exhausted, or one older than the finished retention window. A turn held for a live background child and a turn inside its watchdog bound are healthy.

The report exposes activeTurns, duplicates, missingResults, orphanRoutes, stuckTurns, and the sync label per location; the text report prints the same line.

Statusline ​

Revision.nativeSync and the snapshot metadata carry live, reconciling, or degraded with an optional reason code. The TUI heartbeat updates one signal; the statusline renders native:live, native:reconciling, or native:degraded only while nativeFirst is on. A failed transcript read marks degraded; the next successful reconciliation clears it to live.

Tests ​

npm run verify on this branch: strict typecheck passed; 1784 tests passed, 0 failed, 0 skipped. New #218 coverage:

  • service start recovers a missing turn, user row, and assistant result from one transcript read;
  • location reconnect recovers a gap once, a repeated reconnect is idempotent, and steady-state heartbeats perform no transcript read;
  • adoption reconciles the adopted session once and recovers its turn;
  • terminal result repair restores the exact answer row and result link;
  • answerless turn interruption requires the idle marker; an unconfirmed turn stays working;
  • late text for a settled turn never joins the next active turn;
  • native sync is degraded on a failed read and returns to live;
  • native and task logs carry ids/reason codes with no content or path;
  • native doctor invariants cover active turns, duplicate ids, missing results, orphan routes, stuck turns, held turns, and binding session uniqueness;
  • pure context grouping, prompt metadata, and statusline segment tests.

Live check ​

No live-host run was performed for this ticket. The evidence is the service-boundary suite with the fake host and the committed #210 host-contract fixture. A live fake-provider restart/reconnect and doctor run remains a #227 acceptance step; this record does not claim live evidence.

Merge and conflict risk with #222/#221/#226 ​

The final branch merged integration/native-first after #221 final-text routing, #222 Work history, and #226 legacy-direct-store removal. Reconciliation uses conversation channels only: it reads and writes Message rows on the conversation channel and never touches dmTranscripts, saveDmMessage, or the legacy direct store. The #226 one-way migration remains the only direct-history move.

  • #222 Work history adds a server-paged terminal read. This ticket does not add a history store or change Work retention; projectVisibleWork and deriveWorkStatus remain the only Work projection. The doctor reads durable turns, not a history page.
  • #221 final-text routing extends native ingestion and mention routing. The reconciliation pass deliberately does not route mentions recovered from a missed enqueue; it recovers messages/turns only and logs missing-enqueue. Route creation logs carry both the #221 source and the #218 routeTaskID/inboxID, so neither path needs a second route model.
  • Merge resolution kept the complete #218 service suite beside the #221/#222 suites and retained the #226 channel-only imports. Likely future merge points remain the native ingestion/reconciliation section of src/v2/service.ts, the doctor invariant block, and the service/doctor test appendices. #217's watchdog, deferred settlement, and recoverNativeTurns behavior are reused, not duplicated; a held turn is never treated as stuck.

Released under the MIT License.