Skip to content

Ticket #216: native turn ingestion for workspace conversations — verification ​

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

Behavior ​

  • A native prompt typed into a workspace group session is attributed by the #213 reverse binding index to the workspace group conversation. It appends a durable user message on the workspace channel (workspaceID) and opens one native turn.
  • The exact final answer appends one durable agent message linked to the turn by taskID and resultMessageID.
  • The turn is a normal Subtask with origin: "native", adopted: true, workKind: "turn", conversationID equal to the workspace channel, and a deterministic root dispatchGroupID. It has no lease, claim, or attempts; the queue pump, reaper, and waiting-work repair skip it.
  • The group Work pane selects tasks by workspaceID, and deriveWorkStatus has the ADR 0005 native branch. The card therefore uses the same agent name, status words, glyphs, hold, and history vocabulary as delegated work. No second card type or lifecycle exists.
  • The session's own agent is the implicit addressee: assigneeID is the binding agent and no self-turn, peer turn, or child Subtask is created. Mention routing is intentionally not implemented here (#220/#221).
  • Direct and workspace conversations remain isolated. A group turn writes only the workspace channel; a direct turn writes only dm:<agentID>[:<workspaceID>]. Neither session's events can settle the other's turn.
  • Native subagent child sessions are not bound conversations, so they create no turn and no message rows. Their durable NativeSubagentRun keeps the parent session, parent turn, workspace, and dispatch group, so the child card renders under the parent turn.
  • Internal service prompts (ensemble.internal without a managed user row, or ensemble.mirror: false) are skipped. A service prompt that owns an existing user row attaches to that row instead of mirroring a second one.

Event-to-message/turn flow ​

session.inbox.enqueued
  -> resolve binding conversation (workspace group / workspace direct / home)
  -> workspace: channel = workspaceID; direct: channel = dm:<agentID>[:<workspaceID>]
  -> open Subtask (queued) + durable Work card
  -> durable user message (deterministic inbox id)
  -> internal/onboarding prompt: no user row, no turn; remembered in host order

session.execution.started
  -> claim the enqueue-order head:
       native turn -> phase working + one streaming agent row
       skipped prompt -> mark the execution as internal
  -> a delegated task run owning the session is never attributed to a turn

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

session.text.started / delta / ended
  -> ignored while an internal execution owns the session
  -> accumulate parts by assistantMessageId + ordinal
  -> coalesced ephemeral stream plus a bounded crash checkpoint

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
  -> an inbox id settles only that exact turn; a cancelled internal prompt
     never falls back to the session's live user turn
  -> no inbox id means the session's active turn

session.retry.scheduled
  -> retrying, same row and card

Events are serialized per session, different sessions process in parallel, host event ids dedupe realm-wide, and deterministic durable ids make a replay harmless. session.context is read only for reconciliation.

#215 merge-review fixes included ​

  1. Cancellation identity. session.inbox.cancelled falls back to the session's active turn only when inboxID is absent. A cancelled internal/onboarding prompt can no longer cancel an unrelated live user turn.
  2. Bounded stream checkpoints. Deltas update accumulated text in memory; the coalesced stream publishes it. The durable row is written only when the host identity changes or on a bounded checkpoint (at most one per 250 ms, with one trailing write and a settle-time cancel). A delta burst is no longer one durable store write per delta.
  3. Active-marker hygiene. The native active-turn marker is set only for open phases (queued, working, retrying). Reading or writing a settled turn clears the marker, so late text for a settled turn cannot claim the next turn.
  4. Workspace run attribution (merge review). A delegated run's skipped prompt is consumed from the enqueue-order ledger at its execution start and terminal, so it cannot block the user turn queued behind it or the next composer prompt. runBySession still guards the run's own text and terminal events; once its terminal is observed, a queued native turn may start even while run finalization briefly retains the mapping.

Workspace generalization also needed execution attribution so a delegated task run or a skipped internal execution on the same group session cannot start, settle, or absorb text for a user turn queued behind it. The service keeps a bounded per-session enqueue order plus the current execution owner; both are memory-only and never enter durable state.

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 on the turn's own conversation channel 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 retain the pre-#215 path. Rolling back is a settings change; it never deletes durable native rows, messages, bindings, or Work cards. The next prompt under on ingests normally.

Tests ​

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

  • workspace enqueue -> durable group user row, queued Work card, and the deterministic native dispatch group;
  • execution start, deltas, exact settlement, one linked agent row, and the canonical pending/working/replied Work vocabulary;
  • direct/workspace isolation with interleaved sessions and terminal events;
  • implicit addressing with two bound agents and no self-turn;
  • native subagent children linked to the parent turn with no child turn or child message rows;
  • internal service prompts skipped, including a queued user turn that still stays queued after the internal execution settles;
  • a delegated task run on the group session never claiming a queued turn;
  • a user turn queued during a delegated run starting once the run settles;
  • the first user turn after a completed delegated run still starting;
  • cancellation with an unknown inbox id vs. no inbox id;
  • late text for a settled turn followed by reordered text for the next turn;
  • restart recovery on the workspace channel;
  • nativeFirst off ingesting nothing and on ingesting the next prompt;
  • bounded native stream checkpoints (80 deltas, bounded durable writes).

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 host-contract fixture. A live fake-provider workspace native turn remains a #227 acceptance step; this record does not claim live evidence for #216.

Retry/interruption nuance (#217), reconciliation and doctor invariants (#218), Work history paging (#222), and mention routing (#220/#221) remain separate.

Released under the MIT License.