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:
| Trigger | Path | Behavior |
|---|---|---|
| Service start | start() before the maintenance timer | every unique bound session, awaited |
| Location reconnect / new location | trackLocation after the first location attach | every unique bound session, off the event path |
| Host session reappears | session.created for a bound session | that session only, off the event path |
| Adoption | adoptNativeSession after the binding write and before the heads-up | the adopted session only, awaited |
| Watchdog | performMaintenance (#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
repliedunless a live execution, a held background child, or a recent watchdog receipt says it may still be running. - An answerless open turn settles
interruptedonly when the transcript'sidlemarker follows that turn's own user row. Without terminal evidence it staysworking; 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.creatednever 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— openqueued/working/retryingnative 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— arepliedturn 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
degradedon a failed read and returns tolive; - 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;
projectVisibleWorkandderiveWorkStatusremain 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 #221sourceand the #218routeTaskID/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, andrecoverNativeTurnsbehavior are reused, not duplicated; a held turn is never treated as stuck.