Skip to content

Ticket #217: retry and interruption semantics for native turns — verification ​

  • Date: 2026-11-11
  • Branch: ticket/217-retry-interruption
  • Spec: parent #209; ticket #217
  • ADRs: 0005, 0008, 0010
  • Unit gate: npm run verify (strict typecheck + full test suite): 1731 tests passed, 0 failed, 0 skipped.

Behavior ​

Every transition below keeps one durable native turn, one Work card, and one agent message row. A retry never mints a second turn or row, and no transition creates a row that was not opened by the turn's own execution.

Host evidenceDurable resultVisible Work / row
session.retry.scheduledsame turn phase retrying; same deterministic agent rowretrying; row stays streaming; no interrupted row or notice
session.execution.failed (terminal, no retry)phase failed; failure = { kind: "native", reason: <error.type> }; native.errorCode setfailed; partial text preserved; row stops streaming, never marked interrupted
session.execution.interrupted reason=userphase cancelled; stoppedAt set; interrupted=falsecancelled; partial text preserved; no needs_you
session.execution.interrupted reason=shutdown|inactivity|superseded|unknownphase interrupted; interrupted=trueneeds_you; partial text preserved and the row is marked interrupted
session.inbox.cancelled with an inboxIDonly that exact turn, when it existscancelled; an internal/onboarding or unknown inbox is ignored
session.inbox.cancelled without an inboxIDthe session's active turn (documented fallback)cancelled
session.idle / session.statusno durable changethe live card is not settled; idle only clears ephemeral activity
session.execution.succeeded with a known live background childturn stays working until every child for that turn is terminal or the #188 barrier bound expiressame card/row; then the exact answer settles and the synthetic completion becomes a second parent turn/card

Structured failure uses the host's error.type as the reason code, falling back to error.code and then native-error. Message text, error copy, file content, and paths never enter the reason code or logs.

Watchdog ​

performMaintenance (the existing serialized pass) runs a bounded missing- terminal reconciler for open native turns:

  • the first check happens only after nativeTurnWatchdogMs (default 60 s) with no locally received event; activity uses local receipt time, not host timestamps;
  • it performs at most nativeTurnWatchdogMaxPasses (default 3) transcript reads per turn, then stops; it is not a poll and never publishes a snapshot;
  • answer recovery uses strict identity only: a recorded assistant message id or the assistant message after this turn's own inbox user row;
  • an answer settles replied and writes the existing row;
  • an answerless turn settles needs_you only when the transcript has an idle marker after this turn's user row (confirmed terminal evidence);
  • without that marker the turn stays working and keeps its partial row. Time alone never interrupts.

The watchdog skips turns held for a background child, and restart recovery is still owned by the existing one-pass recoverNativeTurns path.

Background native subagents ​

A successful parent execution that arrives while a child mapped to the same parent turn is still working is held on the same durable turn. The card stays working and the row stays streaming. Terminal child transitions wake the hold; when all children are terminal the parent settles replied. If a child event is missing, the existing bounded barrier (nativeSubagentBarrierMs, 5 minutes by default, override only in tests) settles the parent and closes the live child record, matching #188's timeout behavior.

The child itself never creates a turn or message row. The host's synthetic completion remains a new parent inbox item and a second turn/card, as recorded in the #210 contract.

#215 merge-review fixes in scope ​

  1. Cancellation identity. session.inbox.cancelled falls back to the session's active turn only when inboxID is absent. The #217 regression enqueues a skipped internal prompt behind a live user turn, cancels that exact inbox id, and asserts the user turn keeps working; the no-id fallback still cancels the live turn.
  2. Bounded stream checkpoints. Deltas update in memory; a coalesced stream event plus at most one durable checkpoint per 250 ms (with one trailing write, cancelled at settlement) carries crash recovery. The #217 regression streams 60 deltas while retrying and asserts one row and at most 10 message writes.
  3. Same-row retry and cancel tests. A retry reuses the deterministic agent row and ends with exactly one user row and one agent row. User cancellation keeps the same row, partial text, and canonical cancelled status.

Tests ​

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

  • user interrupt → cancelled, same row/card, partial text preserved;
  • scheduled retry → retrying on the same row/card, no interrupted row, then one exact final answer;
  • terminal execution failure → failed with a structured native reason and preserved partial text;
  • shutdown interruption → needs_you, interrupted row, partial text preserved;
  • session.idle and session.status alone → still working;
  • watchdog answer recovery from one transcript read, with no read before the bound;
  • watchdog no-answer/no-idle → stays working, bounded reads, no guessed interruption;
  • watchdog confirmed answerless idle marker → needs_you with partial text;
  • background child hold until terminal, then a separate synthetic second turn;
  • child barrier timeout releases the parent and closes the live child record;
  • cancelled internal prompt never cancels an unrelated live user turn;
  • retry stream checkpoint bound;
  • pure tests for interruption-reason mapping, strict context recovery, and idle-marker settlement.

Live check ​

No new live-host run was performed for this ticket. The evidence is the service- boundary suite with the fake host and the committed #210 fixture. That probe did not exercise session.execution.failed, so this ticket implements the declared SessionStructuredError.type shape and does not claim live failure-payload evidence. A live fake-provider retry/interruption run remains a #227 acceptance step.

Conflict risk for #218 ​

  • recoverNativeTurns, nativeContextMessages, and performMaintenance are the likely merge points. #218 should reuse nativeContextTurnAnswer, nativeContextTurnSettled, nativeInterruptionSettlement, and the watchdog state rather than adding a second transcript poll or a second settlement path.
  • Restart/reconnect reconciliation must leave nativeDeferredSettlements alone: a held parent turn is expected to be working, not a stuck turn.
  • Doctor invariants should treat a held turn with live children and a turn within its watchdog pass bound as healthy; the timeout/exhaustion cases are the interesting ones.
  • #218's degraded/reconciling status should key off the existing watchdog and reconciliation logs. They carry ids, counts, pass numbers, and reason codes only, never conversation content or paths.

Released under the MIT License.