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 evidence | Durable result | Visible Work / row |
|---|---|---|
session.retry.scheduled | same turn phase retrying; same deterministic agent row | retrying; row stays streaming; no interrupted row or notice |
session.execution.failed (terminal, no retry) | phase failed; failure = { kind: "native", reason: <error.type> }; native.errorCode set | failed; partial text preserved; row stops streaming, never marked interrupted |
session.execution.interrupted reason=user | phase cancelled; stoppedAt set; interrupted=false | cancelled; partial text preserved; no needs_you |
session.execution.interrupted reason=shutdown|inactivity|superseded|unknown | phase interrupted; interrupted=true | needs_you; partial text preserved and the row is marked interrupted |
session.inbox.cancelled with an inboxID | only that exact turn, when it exists | cancelled; an internal/onboarding or unknown inbox is ignored |
session.inbox.cancelled without an inboxID | the session's active turn (documented fallback) | cancelled |
session.idle / session.status | no durable change | the live card is not settled; idle only clears ephemeral activity |
session.execution.succeeded with a known live background child | turn stays working until every child for that turn is terminal or the #188 barrier bound expires | same 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
repliedand writes the existing row; - an answerless turn settles
needs_youonly when the transcript has anidlemarker after this turn's user row (confirmed terminal evidence); - without that marker the turn stays
workingand 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
- Cancellation identity.
session.inbox.cancelledfalls back to the session's active turn only wheninboxIDis 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. - 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
retryingand asserts one row and at most 10 message writes. - 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
cancelledstatus.
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 →
retryingon the same row/card, no interrupted row, then one exact final answer; - terminal execution failure →
failedwith a structured native reason and preserved partial text; - shutdown interruption →
needs_you, interrupted row, partial text preserved; session.idleandsession.statusalone → stillworking;- 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
idlemarker →needs_youwith 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, andperformMaintenanceare the likely merge points. #218 should reusenativeContextTurnAnswer,nativeContextTurnSettled,nativeInterruptionSettlement, and the watchdog state rather than adding a second transcript poll or a second settlement path.- Restart/reconnect reconciliation must leave
nativeDeferredSettlementsalone: a held parent turn is expected to beworking, 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.