Skip to content

Ticket #215: native turn ingestion for direct conversations — verification ​

  • Date: 2026-11-10
  • Branch: ticket/215-direct-native
  • Spec: parent #209; ticket #215
  • ADRs: 0009, 0010
  • Unit gate: npm run verify (strict typecheck + full test suite)

Behavior ​

  • A user prompt typed into a bound direct native session appears immediately as a durable user message on the direct channel (dm:<agentID>[:<workspaceID>]). The message id derives from the host inbox id, so replaying the event updates the same row.
  • The native turn is a normal Subtask with origin: "native", adopted: true, workKind: "turn", and conversationID equal to the channel. It has no lease, claim, or attempts; the queue pump, reaper, and waiting-work repair skip it.
  • deriveWorkStatus has an explicit native branch. The visible vocabulary is the ADR 0005 set: pending, working, retrying, replied, failed, cancelled, and needs_you for an honest interruption.
  • The direct TUI uses the durable channel rows, not chat.context, and shows one compact Work row using the same uppercase state words as the Work pane.

Event-to-message/turn flow ​

session.inbox.enqueued
  -> open Subtask (queued) + Work card
  -> durable user message (deterministic inbox id)
  -> internal prompts mirror no user row

session.execution.started
  -> phase working
  -> open one durable agent row with streaming=true (deterministic turn id)

session.inbox.delivered / delivery.changed
  -> delivery state only; never a start or settlement signal

session.text.started / delta / ended
  -> accumulate parts by assistantMessageId + ordinal
  -> coalesced ephemeral stream updates the same visible row

session.execution.succeeded
  -> exact text = join of ended parts
  -> missing/incomplete endings: one session.context read
  -> durable row written before the live overlay is dropped
  -> phase replied + resultMessageId

session.execution.failed | interrupted
  -> preserve partial text; derive failed or needs_you

session.inbox.cancelled
  -> phase cancelled; no fabricated answer

The event adapter subscribes to the inbox/text/execution/retry families as one ordered group. The service serializes events per session; different sessions process in parallel. Host event ids dedupe realm-wide, and deterministic durable ids make a replay harmless even when an event has no id.

Restart recovery ​

On service start, every open native turn is reconciled once:

  • a recorded answer in the native transcript becomes the exact durable agent row and the turn settles replied;
  • no answer marks the turn interrupted and preserves any durable partial text, so the card asks for the user instead of sticking.

Restart recovery runs even after a flag rollback so an existing native turn cannot remain stuck.

Flag and rollback ​

Ingestion requires settings.nativeFirst === "on". off and shadow keep the pre-#215 path (native transcript merge, live overlay, chat-context heartbeat). Rolling back is a settings change; it never deletes durable native rows, messages, bindings, or Work cards. Service prompts are marked in host prompt metadata: composer prompts skip only the user mirror (their durable row already exists), while identity/onboarding/system prompts are not ingested at all.

Tests ​

npm run verify result on this branch: strict typecheck passed; 1660 tests passed, 0 failed, 0 skipped. Coverage includes:

  • enqueue -> immediate durable user row, queued Work card, and attachment metadata;
  • execution start -> one streaming agent row; deltas update it; settle writes one exact linked agent row and a persisted Work card;
  • duplicate, repeated, and reordered events (including a delta before its text.started and a terminal event replayed after settlement);
  • a missing text.ended part with exactly one session.context fallback read while the streamed row stays visible;
  • internal prompts with no mirrored user row, plus a composer prompt that attaches to its existing user row;
  • restart recovery of a real answer and of an interrupted partial answer;
  • nativeFirst: "off" ingesting nothing;
  • no native transcript read and no full snapshot on a normal turn;
  • the direct surface reading only the durable channel and rendering the canonical Work row.

Live check ​

No new live-host run was performed for this ticket. The service-boundary suite uses the existing fake host context and the committed #210 fixture establishes the event identities and order the ingestion depends on. A live fake-provider direct turn remains a #227 acceptance step; this record does not claim live evidence for #215.

Released under the MIT License.