@cabane/companion 0.6.97 → 0.6.98

package/dist/cli.js

@@ -2607,11 +2607,12 @@ var CabaneApi = class {
   //   - terminal 4xx (a deterministic rejection a replay can't fix) → rethrow,
   //     so the caller's error path runs as it does today (e.g. the committer
   //     re-arms its empty-final fallback).
-  //   - retryable (transport / 5xx — provably non-committed) → persist + return
-  //     (swallow), so the caller treats the row as committed and the drainer
-  //     delivers it once the API returns. `(turnId, seq)` is the server's
-  //     idempotency key, so a replay whose original POST's fate is unknown
-  //     converges instead of duplicating.
+  //   - retryable (transport / 5xx — commit outcome may be unknown) → queue
+  //     and return. This acknowledges local delivery responsibility, not server
+  //     persistence. Replays retain the endpoint's identity: messages/thinking/
+  //     text use (turnId, seq) within each kind for nonzero seq; tool activity
+  //     uses (turnId, toolUseId). Legacy zero/missing seq bypasses row deduplication.
+  //     Server fences and the outbox's discard/eviction bounds still apply.
   async durableCommit(kind, path, body, turnId, seq, signal) {
     try {
       await this.request("POST", path, body, {
@@ -2737,14 +2738,11 @@ var CabaneApi = class {
       (e) => e.turnId === turnId && e.kind === "message" && e.body?.kind !== "runtime_notice"
     );
   }
-  // CT714: read a turn's recorded turn-control intent. An EXTERNAL adapter
-  // (Codex / opencode) records `reply_to` / `skip_turn` into `turn_intents`
-  // server-side (the URL MCP surface) rather than the dispatcher's in-memory
-  // closures, so the dispatcher fetches this once at settle — by `turnId` —
-  // and populates those closures, letting the unchanged settle path close the
-  // turn identically to claude-code. CT1354: those two verbs are all it
-  // carries now; the outgoing acts commit at the call (`turnAct`). Agent-PAT
-  // authed + self-scoped (`:agentId` must match the PAT's agent).
+  // Read the skip intent recorded by the URL turn-control MCP surface.
+  // Codex/opencode use this server-side state; settle imports skipped/skipReason
+  // into the same local skip state used by claude-code's in-process tools.
+  // Outgoing acts commit when called and are not buffered in this intent.
+  // Agent-PAT authenticated and scoped to this agent and turn.
   getTurnIntent(workspaceId, conversationId, agentId, turnId) {
     const q = `turnId=${encodeURIComponent(turnId)}`;
     return this.request(
@@ -2752,19 +2750,13 @@ var CabaneApi = class {
       `/api/workspaces/${workspaceId}/conversations/${conversationId}/participants/agents/${agentId}/turn-intent?${q}`
     );
   }
-  // CT1354: COMMIT ONE OUTGOING ACT of a running turn — a `send`, an `ask`, a
-  // `wake_me`, a `cancel_wake` — the moment the tool is called. The server
-  // runs `performTurnAct` inside the turn's write fence: the row is in the
-  // ledger when this resolves, and a 200 `ok: false` is the server's REFUSAL
-  // (an unknown target, a non-member, a wake outside its guardrails) for the
-  // tool to hand back as its error. 409 means the turn already settled.
-  //
-  // Bounded retry, on purpose: the act is a durable write whose loss strands a
-  // person or a peer, and `act.callId` — minted once per tool invocation by the
-  // caller — is what makes the retry safe: the server keys on `(turnId,
-  // callId)`, so an attempt that landed before the response was lost is
-  // replayed as the same row, never a second message. The caller's `signal`
-  // is the per-call deadline (the tool must answer the model, not hang it).
+  // Commit one outgoing act (ask, withdraw_ask, wake_me, cancel_wake) at
+  // invocation. The server records the effect and receipt in one transaction;
+  // an ok:false response is a recorded refusal for the tool to report.
+  // Retries retain the caller's callId and recover the same receipt while the
+  // HTTP route admits the request. Currently that route rejects ended spans
+  // before receipt lookup: a 409 cannot prove an earlier attempt had no effect.
+  // The caller's signal bounds how long the model waits for the tool result.
   turnAct(workspaceId, turnId, act, signal) {
     return this.request(
       "POST",
@@ -2824,13 +2816,9 @@ var CabaneApi = class {
   // loop; null when it settles) plus once with the session id on the
   // first `system/init` frame.
   //
-  // CT93: a write that touches the active-run *flag* (the set or the clear) is
-  // durable when an outbox is configured — a transient failure at the settle
-  // window queues it instead of dropping it on the floor (the exact strand this
-  // task fixes), and it drains with last-writer-wins per pair (see
-  // `durableActiveRunWrite`). The session-id-only write (first-frame capture) is
-  // left best-effort: it's lower-stakes and self-heals on the next turn, so it
-  // stays a single-shot PATCH and is deliberately out of CT93's scope.
+  // Admission is synchronous and bounded-retry: a start must return before
+  // the model runs. Only a clear can be queued after a transient failure.
+  // Session-id-only capture is a single-shot PATCH without outbox delivery.
   async setActiveRun(workspaceId, conversationId, agentId, body) {
     const path = `/api/workspaces/${workspaceId}/conversations/${conversationId}/participants/agents/${agentId}/active-run`;
     const touchesFlag = Object.prototype.hasOwnProperty.call(body, "activeRunStartedAt");
@@ -2906,25 +2894,16 @@ var CabaneApi = class {
   // CT29: per-device liveness moved off the per-workspace agent PAT and onto the
   // device token — see `DeviceApi.heartbeat`. There is no agent-PAT heartbeat
   // anymore.
-  // SJ477: commit one row of the companion's turn (a `progress` interim note or
-  // the `final` reply), derived from its own SDK transcript. Posts to the same
-  // public messages endpoint a user hits — the companion holds an agent-bound
-  // PAT, so the server attributes the row to this agent (role `agent`) and
-  // won't re-dispatch (the route gates re-dispatch on role `user`). `turnId`
-  // groups every row of one turn so the chat drawer renders them as a single
-  // turn. Body + response are the public message shapes; we don't need the
-  // response here.
-  // SJ516: the commit path is the one place a dropped POST is user-visible
-  // reply loss, so it opts into bounded retry-with-backoff (`retry: true`) —
-  // safe because `request` only retries the provably-non-committed failures
-  // (transport errors + 5xx), never a 4xx, so no `(turnId, kind)` row is
-  // double-posted. The caller threads its turn abort signal so a cancel
-  // mid-commit aborts the in-flight POST rather than letting it land.
-  // Workzone: a commit is a message — the agent's first or last words — or the
-  // runtime's own line (`runtime_notice`). The words between tool calls go
-  // through `reportText`, the trail's door. `seq` is the companion's per-turn
-  // monotonic counter, stamped on the row so the merged timeline orders the
-  // commit deterministically against the persisted tool/thinking rows.
+  // Commit the agent's first/last words (message) or a runtime_notice through
+  // the public messages endpoint. Intermediate working text uses reportText.
+  // Attribution comes from the agent credential; a new speech row can offer
+  // work to other agents under the server's current routing rules.
+  // Retried messages retain (turnId, seq), the server's duplicate identity for
+  // nonzero seq (legacy zero/missing seq bypasses it),
+  // so response loss need not produce a second row or repeat routing effects.
+  // seq also orders speech against the turn's tool/thinking/text trail.
+  // Transport/5xx failures get bounded retries and optional outbox delivery;
+  // terminal 4xx and cancellation stop delivery rather than proving no commit.
   postTurnMessage(workspaceId, conversationId, body, signal) {
     return this.durableCommit(
       "message",
@@ -2935,10 +2914,11 @@ var CabaneApi = class {
       signal
     );
   }
-  // SJ477: report one tool-activity transition (start / done / error) for the
-  // live activity cards. Transient — the server publishes an `agent_activity`
-  // SSE and writes no row. Agent-PAT authed; the URL `:agentId` must match the
-  // PAT's agent (server-enforced). Best-effort from the caller's view.
+  // Report a tool transition (start/done/error). The server checks span
+  // ownership, upserts by (turnId, toolUseId), and publishes agent_activity SSE.
+  // Ended spans accept late activity. Persistence failure is warn-only there:
+  // a successful response can still represent live SSE without a stored row.
+  // Agent-PAT authenticated; the URL agent must match the credential.
   reportActivity(workspaceId, conversationId, agentId, body, signal) {
     return this.durableCommit(
       "activity",
@@ -2949,11 +2929,10 @@ var CabaneApi = class {
       signal
     );
   }
-  // SJ530: report one thinking summary for the live activity list, mirroring
-  // `reportActivity`. Transient — the server republishes an `agent_thinking`
-  // SSE and writes no row. Agent-PAT authed; the URL `:agentId` must match the
-  // PAT's agent (server-enforced). Best-effort: a dropped thinking row is
-  // cosmetic (no retry), but the abort signal is threaded so a cancel stops it.
+  // Report thinking through bounded retry and optional outbox delivery.
+  // The server checks ownership, inserts by (turnId, type, seq), and publishes SSE,
+  // including for ended spans. As with activity, persistence failure is
+  // warn-only and a successful response does not guarantee a stored row.
   reportThinking(workspaceId, conversationId, agentId, body, signal) {
     return this.durableCommit(
       "thinking",
@@ -2964,10 +2943,10 @@ var CabaneApi = class {
       signal
     );
   }
-  // Workzone: report one text the agent wrote between tool calls — the trail's
-  // door. Durable like a thinking row (same outbox, same `(turnId, seq)`
-  // replay), and never a message: the server writes it to `message_activity`
-  // under the span and nothing lands, stamps or wakes on it.
+  // Report working text to message_activity without landing speech or waking
+  // agents. The server requires an owned, running span and persists before SSE.
+  // Outbox replay retains (turnId, type, seq) for nonzero seq, but an ended
+  // span rejects it: this queue does not promise delivery after settlement.
   reportText(workspaceId, conversationId, agentId, body, signal) {
     return this.durableCommit(
       "text",
@@ -3772,25 +3751,15 @@ var turnRequestSchema = z8.object({
     mcpUrl: z8.string(),
     bearer: z8.string(),
     activeConversationId: z8.string(),
-    // CT714: the scoped TURN-CONTROL MCP endpoint (`/api/turn-control`). The
-    // EXTERNAL adapters (Codex / opencode) mount it by URL under the key
-    // `cabane_companion` — using the same `bearer` (the turn token) and the same
-    // active-conversation header they send to the `cabane` server — so their
-    // agents get `ask`/`reply_to`/`wake_me`/`send`/`skip_turn`, the
-    // verbs they can't get from the companion's in-process SDK server. Optional:
-    // claude-code ignores it (it mounts the in-process instance instead), and
-    // every existing `cabane`-block fixture keeps parsing unchanged; the
-    // companion always populates it (`build-options.ts`).
+    // Scoped turn-control MCP URL. Codex/opencode mount it as cabane_companion
+    // with the bearer and active-conversation header. It supplies ask,
+    // withdraw_ask, wake_me, cancel_wake and skip_turn. Claude Code mounts the
+    // companion's in-process instance instead. Optional for compatibility;
+    // the companion populates it in build-options.ts.
     turnControlUrl: z8.string().optional(),
-    // CT598: the workspace this turn runs in. The claude-code/opencode/codex
-    // adapters never need it (they reach Cabane through the `cabane` MCP server,
-    // which takes `workspaceId` as a per-tool arg the model supplies); the
-    // native runtime's interim tool surface calls the workspace-scoped REST API
-    // DIRECTLY, so it needs the id host-side rather than trusting the model to
-    // pass it. Optional so every existing `cabane`-block constructor (the three
-    // adapters' conformance fixtures, tests) keeps parsing unchanged — the companion
-    // always populates it (`build-options.ts`), and the native adapter fails the
-    // turn loudly when it is somehow absent rather than guessing.
+    // Workspace coordinate retained for envelope compatibility. Current
+    // adapters use MCP, whose workspace operations take workspaceId explicitly.
+    // The companion supplies this field; it is not required by those adapters.
     workspaceId: z8.string().optional()
   }),
   // Machine-local resolution (host-filled): the checkout cwd, extra env from a
@@ -5255,8 +5224,8 @@ var OPENCODE_ADDENDUM = [
   "collision runs the other way too: `read` is a host tool here AND `files.read` is an",
   "operation name, so keep the bare verb and the dotted name apart. If a tool ever appears with",
   "an `mcp__\u2026__` prefix, that prefix is not part of its name here. One more harness fact: you",
-  "can interleave narration with tool calls, but only your final message is recorded as the",
-  "turn's reply \u2014 write your closing answer last."
+  "can interleave narration with tool calls, but your final message is the",
+  "turn's answer \u2014 write your closing answer last."
 ].join(" ");
 
 // packages/agent-runtime/src/opencode/events.ts
@@ -6320,7 +6289,7 @@ var CODEX_ADDENDUM = [
   "possibly deferred too. There is no Cabane `read`/`write`/`search` tool \u2014 those are",
   "operation NAMES you pass to `query` / `mutate`. One more harness fact: you can interleave",
   "narration",
-  "with tool calls, but only your final message is recorded as the turn's reply \u2014 write your",
+  "with tool calls, but your final message is the turn's answer \u2014 write your",
   "closing answer last."
 ].join(" ");
 
@@ -7921,7 +7890,7 @@ var MAX_WAKE_NOTE_BYTES = 2e3;
 var MAX_WITHDRAW_REASON_BYTES = 400;
 var MAX_SKIP_REASON_BYTES = 500;
 var TURN_CONTROL_TOOL_DESCRIPTIONS = {
-  ask: `Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass \`targetUserId\` (a workspace member's user id \u2014 every person's id is on the roster in your turn context). Two forms: a SINGLE question \u2014 a \`headline\` (the actual question as one clear, capitalized sentence ending in \`?\`, "Do we go to prod?") plus a short \`question\` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a \`questions\` array of 1\u2013${MAX_ASK_ITEMS} items, each \`{ headline, body?, options? }\`. Provide EITHER \`question\` (single) or \`questions\` (array), never both. **Several decisions landing together are ONE call with \`questions\`** \u2014 never cram the extras into prose, drop all but one, or fire an ask each: a second \`ask\` is a second inbox item competing with the first, never an edit to it. Each question keeps the same form: a one-sentence \`headline\`, a short \`body\` frame (NOT a report \u2014 your status, links and detail go in your REPLY; inline markdown only, no lists or headings), and ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} \`options\` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. The ask is a first-class attention item aimed at that person; your final reply carries the CONTEXT, the ask carries the QUESTION(S). It is written and delivered THE MOMENT you call this \u2014 the person sees it in their inbox while your turn is still running \u2014 so call it once you know the question. The human sends ONE response: supplied answers are recorded, omissions become terminally Unanswered. Ask only when blocked \u2014 never ceremonially. \`replaces\` withdraws a stale ask of yours (or anyone's) in this conversation in the same write, with the reason shown to the person. Targets a human only; to bring a peer AGENT in, name them by \`@handle\` in your reply.`,
+  ask: `Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass \`targetUserId\`. Two forms: a SINGLE question \u2014 a \`headline\` plus a short \`question\` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a \`questions\` array of 1\u2013${MAX_ASK_ITEMS} items, each \`{ headline, body?, options? }\`. Provide EITHER \`question\` (single) or \`questions\` (array), never both. **Several decisions landing together are ONE call with \`questions\`** \u2014 never cram the extras into prose, drop all but one, or fire an ask each: a second \`ask\` is a second inbox item competing with the first, never an edit to it. Each question keeps the same form: a one-sentence \`headline\`, a short \`body\` frame (NOT a report \u2014 your status, links and detail go in your REPLY; inline markdown only, no lists or headings), and ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} \`options\` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. The ask is a first-class attention item aimed at that person; your final reply carries the CONTEXT, the ask carries the QUESTION(S). It is written and delivered THE MOMENT you call this \u2014 the person sees it in their inbox while your turn is still running \u2014 so call it once you know the question. The human sends ONE response: supplied answers are recorded, omissions become terminally Unanswered. A person can DISMISS a question instead of answering it \u2014 it ends, you are not told, nothing wakes you. Check an ask's status before re-raising a vanished one. Ask only when blocked \u2014 never ceremonially. \`replaces\` withdraws a stale ask of yours (or anyone's) in this conversation in the same write, with the reason shown to the person. Targets a human only; to bring a peer AGENT in, name them by \`@handle\` in your reply.`,
   cancel_wake: `Stand down your own wake \u2014 the inverse of \`wake_me\`. No arguments: it cancels the wake you have armed in this conversation, NOW, when you call it. Reach for it when the thing you armed a wake to check has already happened, or the work it was watching is over \u2014 an armed wake you no longer need fires into a turn with nothing to do, and a supervision loop with no off switch is one you can only end by leaving it running. Whether you have one armed is printed in your turn context ("Wake armed: \u2026"); calling this with nothing armed is a clean no-op, no error. Each call acts as it arrives: \`cancel_wake\` then \`wake_me\` leaves the NEW wake armed; \`wake_me\` then \`cancel_wake\` leaves nothing armed. It reaches only your own wake in this conversation \u2014 never a peer's, and never a recurring schedule (those are \`schedules.*\`).`,
   skip_turn: `End your current turn WITHOUT posting a reply. Call this when you've been woken to read a message that genuinely doesn't need a response from you \u2014 a thanks/aside, a question already answered, chatter outside your lane, or something another participant clearly owns. Your turn ends silently: no message bubble is posted. The \`reason\` is a short free-text note for telemetry (e.g. "already answered by cabane", "thanks, nothing to add"). Prefer this over posting a low-value "ok!"/"got it" reply. Don't also write a reply when you skip \u2014 skipping IS the whole turn.`,
   wake_me: `Wake yourself later \u2014 end this turn now and be re-dispatched at a time you pick, with a note you write to yourself. Use it for "wait until X": when the thing you need hasn't happened yet (a PR isn't merged, a human hasn't answered), arm a wake, end your turn, and you're woken later to CHECK \u2014 read the workspace, and either act or re-arm. Ground the delay before you arm it. Almost every wake is short \u2014 seconds to a couple of hours \u2014 waiting on a condition you can name: a session limit resetting, a PR merging. Reach past a few hours only when (a) a human asked for that timing, or (b) the wait is pinned to a real external event you can name \u2014 a report that only runs Mondays, a known reset time. A speculative far-future check-in you invented yourself is the one thing not to arm: if no one asked and you can't name both what clears the wait and why it takes that long, don't arm it \u2014 finish now, or raise an \`ask\`. Pass EXACTLY ONE of \`afterSeconds\` (a relative delay \u2014 \`300\` for five minutes) or \`at\` (an absolute ISO-8601 timestamp WITH a zone, e.g. \`2026-07-16T09:00:00-07:00\` \u2014 YOU compute it; the system never parses natural-language time). \`note\` is a message to your future self \u2014 it becomes the body of the wake message that re-dispatches you, so write the condition to re-check ("check whether CT441 merged yet"). The wake arms NOW, when you call this, and the delay counts from this call; a later \`wake_me\` in the same turn replaces it, and \`cancel_wake\` stands it down. A wake that comes due while your turn is still running waits and is delivered after your reply. This is the ONLY sanctioned way to schedule your own continuation; never reach for a host cron/scheduler. Guardrails: at least 60s out, at most 14 days \u2014 a wake that can't be armed returns an error here, in this call, so you can recompute; widen the interval as a loop ages (5m \u2192 15m \u2192 1h\u2026) rather than hammering; after many consecutive re-arms with no other activity you'll be steered to raise an \`ask\` to the human instead.`,
@@ -9181,8 +9150,7 @@ var TurnExecution = class {
       // CT238: this turn's conversation, forwarded as the active-conversation
       // header so a cross-thread post/spawn stamps its origin.
       activeConversationId: payload.conversationId,
-      // CT598: the workspace this turn runs in — the native runtime's direct REST
-      // tool surface scopes its calls with it.
+      // Workspace coordinate retained in the compatible TurnRequest envelope.
       workspaceId,
       // CT289: the operator's auto-memory escape hatch (machine-local), when set.
       ...this.opts.local.claudeCode ? { claudeCode: this.opts.local.claudeCode } : {}
@@ -9707,11 +9675,9 @@ var Dispatcher = class {
     } catch {
     }
   }
-  // CT1288: `opts.turnId` is a RESUMED turn id — the id this event already ran
-  // under before the companion died. Passing it makes the replay ask the
-  // mailroom to re-admit the turn it already owns, which the server explicitly
-  // supports ("a replay reports, it never re-points"). Omitted on a fresh
-  // dispatch, where minting is correct.
+  // The supervisor supplies a stable turnId on both fresh and resumed dispatch.
+  // resumed is separate: only replay seeds sequence/speech recovery from the
+  // prior span. A direct caller omitting turnId gets a fresh id.
   //
   // CT1261: a short `handle` creates a `TurnExecution` and runs it. The
   // supervisor seam hands the execution exactly the three cross-turn duties —

package/dist/runtime.js

@@ -2025,11 +2025,12 @@ var CabaneApi = class {
   //   - terminal 4xx (a deterministic rejection a replay can't fix) → rethrow,
   //     so the caller's error path runs as it does today (e.g. the committer
   //     re-arms its empty-final fallback).
-  //   - retryable (transport / 5xx — provably non-committed) → persist + return
-  //     (swallow), so the caller treats the row as committed and the drainer
-  //     delivers it once the API returns. `(turnId, seq)` is the server's
-  //     idempotency key, so a replay whose original POST's fate is unknown
-  //     converges instead of duplicating.
+  //   - retryable (transport / 5xx — commit outcome may be unknown) → queue
+  //     and return. This acknowledges local delivery responsibility, not server
+  //     persistence. Replays retain the endpoint's identity: messages/thinking/
+  //     text use (turnId, seq) within each kind for nonzero seq; tool activity
+  //     uses (turnId, toolUseId). Legacy zero/missing seq bypasses row deduplication.
+  //     Server fences and the outbox's discard/eviction bounds still apply.
   async durableCommit(kind, path, body, turnId, seq, signal) {
     try {
       await this.request("POST", path, body, {
@@ -2155,14 +2156,11 @@ var CabaneApi = class {
       (e) => e.turnId === turnId && e.kind === "message" && e.body?.kind !== "runtime_notice"
     );
   }
-  // CT714: read a turn's recorded turn-control intent. An EXTERNAL adapter
-  // (Codex / opencode) records `reply_to` / `skip_turn` into `turn_intents`
-  // server-side (the URL MCP surface) rather than the dispatcher's in-memory
-  // closures, so the dispatcher fetches this once at settle — by `turnId` —
-  // and populates those closures, letting the unchanged settle path close the
-  // turn identically to claude-code. CT1354: those two verbs are all it
-  // carries now; the outgoing acts commit at the call (`turnAct`). Agent-PAT
-  // authed + self-scoped (`:agentId` must match the PAT's agent).
+  // Read the skip intent recorded by the URL turn-control MCP surface.
+  // Codex/opencode use this server-side state; settle imports skipped/skipReason
+  // into the same local skip state used by claude-code's in-process tools.
+  // Outgoing acts commit when called and are not buffered in this intent.
+  // Agent-PAT authenticated and scoped to this agent and turn.
   getTurnIntent(workspaceId, conversationId, agentId, turnId) {
     const q = `turnId=${encodeURIComponent(turnId)}`;
     return this.request(
@@ -2170,19 +2168,13 @@ var CabaneApi = class {
       `/api/workspaces/${workspaceId}/conversations/${conversationId}/participants/agents/${agentId}/turn-intent?${q}`
     );
   }
-  // CT1354: COMMIT ONE OUTGOING ACT of a running turn — a `send`, an `ask`, a
-  // `wake_me`, a `cancel_wake` — the moment the tool is called. The server
-  // runs `performTurnAct` inside the turn's write fence: the row is in the
-  // ledger when this resolves, and a 200 `ok: false` is the server's REFUSAL
-  // (an unknown target, a non-member, a wake outside its guardrails) for the
-  // tool to hand back as its error. 409 means the turn already settled.
-  //
-  // Bounded retry, on purpose: the act is a durable write whose loss strands a
-  // person or a peer, and `act.callId` — minted once per tool invocation by the
-  // caller — is what makes the retry safe: the server keys on `(turnId,
-  // callId)`, so an attempt that landed before the response was lost is
-  // replayed as the same row, never a second message. The caller's `signal`
-  // is the per-call deadline (the tool must answer the model, not hang it).
+  // Commit one outgoing act (ask, withdraw_ask, wake_me, cancel_wake) at
+  // invocation. The server records the effect and receipt in one transaction;
+  // an ok:false response is a recorded refusal for the tool to report.
+  // Retries retain the caller's callId and recover the same receipt while the
+  // HTTP route admits the request. Currently that route rejects ended spans
+  // before receipt lookup: a 409 cannot prove an earlier attempt had no effect.
+  // The caller's signal bounds how long the model waits for the tool result.
   turnAct(workspaceId, turnId, act, signal) {
     return this.request(
       "POST",
@@ -2242,13 +2234,9 @@ var CabaneApi = class {
   // loop; null when it settles) plus once with the session id on the
   // first `system/init` frame.
   //
-  // CT93: a write that touches the active-run *flag* (the set or the clear) is
-  // durable when an outbox is configured — a transient failure at the settle
-  // window queues it instead of dropping it on the floor (the exact strand this
-  // task fixes), and it drains with last-writer-wins per pair (see
-  // `durableActiveRunWrite`). The session-id-only write (first-frame capture) is
-  // left best-effort: it's lower-stakes and self-heals on the next turn, so it
-  // stays a single-shot PATCH and is deliberately out of CT93's scope.
+  // Admission is synchronous and bounded-retry: a start must return before
+  // the model runs. Only a clear can be queued after a transient failure.
+  // Session-id-only capture is a single-shot PATCH without outbox delivery.
   async setActiveRun(workspaceId, conversationId, agentId, body) {
     const path = `/api/workspaces/${workspaceId}/conversations/${conversationId}/participants/agents/${agentId}/active-run`;
     const touchesFlag = Object.prototype.hasOwnProperty.call(body, "activeRunStartedAt");
@@ -2324,25 +2312,16 @@ var CabaneApi = class {
   // CT29: per-device liveness moved off the per-workspace agent PAT and onto the
   // device token — see `DeviceApi.heartbeat`. There is no agent-PAT heartbeat
   // anymore.
-  // SJ477: commit one row of the companion's turn (a `progress` interim note or
-  // the `final` reply), derived from its own SDK transcript. Posts to the same
-  // public messages endpoint a user hits — the companion holds an agent-bound
-  // PAT, so the server attributes the row to this agent (role `agent`) and
-  // won't re-dispatch (the route gates re-dispatch on role `user`). `turnId`
-  // groups every row of one turn so the chat drawer renders them as a single
-  // turn. Body + response are the public message shapes; we don't need the
-  // response here.
-  // SJ516: the commit path is the one place a dropped POST is user-visible
-  // reply loss, so it opts into bounded retry-with-backoff (`retry: true`) —
-  // safe because `request` only retries the provably-non-committed failures
-  // (transport errors + 5xx), never a 4xx, so no `(turnId, kind)` row is
-  // double-posted. The caller threads its turn abort signal so a cancel
-  // mid-commit aborts the in-flight POST rather than letting it land.
-  // Workzone: a commit is a message — the agent's first or last words — or the
-  // runtime's own line (`runtime_notice`). The words between tool calls go
-  // through `reportText`, the trail's door. `seq` is the companion's per-turn
-  // monotonic counter, stamped on the row so the merged timeline orders the
-  // commit deterministically against the persisted tool/thinking rows.
+  // Commit the agent's first/last words (message) or a runtime_notice through
+  // the public messages endpoint. Intermediate working text uses reportText.
+  // Attribution comes from the agent credential; a new speech row can offer
+  // work to other agents under the server's current routing rules.
+  // Retried messages retain (turnId, seq), the server's duplicate identity for
+  // nonzero seq (legacy zero/missing seq bypasses it),
+  // so response loss need not produce a second row or repeat routing effects.
+  // seq also orders speech against the turn's tool/thinking/text trail.
+  // Transport/5xx failures get bounded retries and optional outbox delivery;
+  // terminal 4xx and cancellation stop delivery rather than proving no commit.
   postTurnMessage(workspaceId, conversationId, body, signal) {
     return this.durableCommit(
       "message",
@@ -2353,10 +2332,11 @@ var CabaneApi = class {
       signal
     );
   }
-  // SJ477: report one tool-activity transition (start / done / error) for the
-  // live activity cards. Transient — the server publishes an `agent_activity`
-  // SSE and writes no row. Agent-PAT authed; the URL `:agentId` must match the
-  // PAT's agent (server-enforced). Best-effort from the caller's view.
+  // Report a tool transition (start/done/error). The server checks span
+  // ownership, upserts by (turnId, toolUseId), and publishes agent_activity SSE.
+  // Ended spans accept late activity. Persistence failure is warn-only there:
+  // a successful response can still represent live SSE without a stored row.
+  // Agent-PAT authenticated; the URL agent must match the credential.
   reportActivity(workspaceId, conversationId, agentId, body, signal) {
     return this.durableCommit(
       "activity",
@@ -2367,11 +2347,10 @@ var CabaneApi = class {
       signal
     );
   }
-  // SJ530: report one thinking summary for the live activity list, mirroring
-  // `reportActivity`. Transient — the server republishes an `agent_thinking`
-  // SSE and writes no row. Agent-PAT authed; the URL `:agentId` must match the
-  // PAT's agent (server-enforced). Best-effort: a dropped thinking row is
-  // cosmetic (no retry), but the abort signal is threaded so a cancel stops it.
+  // Report thinking through bounded retry and optional outbox delivery.
+  // The server checks ownership, inserts by (turnId, type, seq), and publishes SSE,
+  // including for ended spans. As with activity, persistence failure is
+  // warn-only and a successful response does not guarantee a stored row.
   reportThinking(workspaceId, conversationId, agentId, body, signal) {
     return this.durableCommit(
       "thinking",
@@ -2382,10 +2361,10 @@ var CabaneApi = class {
       signal
     );
   }
-  // Workzone: report one text the agent wrote between tool calls — the trail's
-  // door. Durable like a thinking row (same outbox, same `(turnId, seq)`
-  // replay), and never a message: the server writes it to `message_activity`
-  // under the span and nothing lands, stamps or wakes on it.
+  // Report working text to message_activity without landing speech or waking
+  // agents. The server requires an owned, running span and persists before SSE.
+  // Outbox replay retains (turnId, type, seq) for nonzero seq, but an ended
+  // span rejects it: this queue does not promise delivery after settlement.
   reportText(workspaceId, conversationId, agentId, body, signal) {
     return this.durableCommit(
       "text",
@@ -3269,25 +3248,15 @@ var turnRequestSchema = z8.object({
     mcpUrl: z8.string(),
     bearer: z8.string(),
     activeConversationId: z8.string(),
-    // CT714: the scoped TURN-CONTROL MCP endpoint (`/api/turn-control`). The
-    // EXTERNAL adapters (Codex / opencode) mount it by URL under the key
-    // `cabane_companion` — using the same `bearer` (the turn token) and the same
-    // active-conversation header they send to the `cabane` server — so their
-    // agents get `ask`/`reply_to`/`wake_me`/`send`/`skip_turn`, the
-    // verbs they can't get from the companion's in-process SDK server. Optional:
-    // claude-code ignores it (it mounts the in-process instance instead), and
-    // every existing `cabane`-block fixture keeps parsing unchanged; the
-    // companion always populates it (`build-options.ts`).
+    // Scoped turn-control MCP URL. Codex/opencode mount it as cabane_companion
+    // with the bearer and active-conversation header. It supplies ask,
+    // withdraw_ask, wake_me, cancel_wake and skip_turn. Claude Code mounts the
+    // companion's in-process instance instead. Optional for compatibility;
+    // the companion populates it in build-options.ts.
     turnControlUrl: z8.string().optional(),
-    // CT598: the workspace this turn runs in. The claude-code/opencode/codex
-    // adapters never need it (they reach Cabane through the `cabane` MCP server,
-    // which takes `workspaceId` as a per-tool arg the model supplies); the
-    // native runtime's interim tool surface calls the workspace-scoped REST API
-    // DIRECTLY, so it needs the id host-side rather than trusting the model to
-    // pass it. Optional so every existing `cabane`-block constructor (the three
-    // adapters' conformance fixtures, tests) keeps parsing unchanged — the companion
-    // always populates it (`build-options.ts`), and the native adapter fails the
-    // turn loudly when it is somehow absent rather than guessing.
+    // Workspace coordinate retained for envelope compatibility. Current
+    // adapters use MCP, whose workspace operations take workspaceId explicitly.
+    // The companion supplies this field; it is not required by those adapters.
     workspaceId: z8.string().optional()
   }),
   // Machine-local resolution (host-filled): the checkout cwd, extra env from a
@@ -4752,8 +4721,8 @@ var OPENCODE_ADDENDUM = [
   "collision runs the other way too: `read` is a host tool here AND `files.read` is an",
   "operation name, so keep the bare verb and the dotted name apart. If a tool ever appears with",
   "an `mcp__\u2026__` prefix, that prefix is not part of its name here. One more harness fact: you",
-  "can interleave narration with tool calls, but only your final message is recorded as the",
-  "turn's reply \u2014 write your closing answer last."
+  "can interleave narration with tool calls, but your final message is the",
+  "turn's answer \u2014 write your closing answer last."
 ].join(" ");
 
 // packages/agent-runtime/src/opencode/events.ts
@@ -5817,7 +5786,7 @@ var CODEX_ADDENDUM = [
   "possibly deferred too. There is no Cabane `read`/`write`/`search` tool \u2014 those are",
   "operation NAMES you pass to `query` / `mutate`. One more harness fact: you can interleave",
   "narration",
-  "with tool calls, but only your final message is recorded as the turn's reply \u2014 write your",
+  "with tool calls, but your final message is the turn's answer \u2014 write your",
   "closing answer last."
 ].join(" ");
 
@@ -7418,7 +7387,7 @@ var MAX_WAKE_NOTE_BYTES = 2e3;
 var MAX_WITHDRAW_REASON_BYTES = 400;
 var MAX_SKIP_REASON_BYTES = 500;
 var TURN_CONTROL_TOOL_DESCRIPTIONS = {
-  ask: `Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass \`targetUserId\` (a workspace member's user id \u2014 every person's id is on the roster in your turn context). Two forms: a SINGLE question \u2014 a \`headline\` (the actual question as one clear, capitalized sentence ending in \`?\`, "Do we go to prod?") plus a short \`question\` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a \`questions\` array of 1\u2013${MAX_ASK_ITEMS} items, each \`{ headline, body?, options? }\`. Provide EITHER \`question\` (single) or \`questions\` (array), never both. **Several decisions landing together are ONE call with \`questions\`** \u2014 never cram the extras into prose, drop all but one, or fire an ask each: a second \`ask\` is a second inbox item competing with the first, never an edit to it. Each question keeps the same form: a one-sentence \`headline\`, a short \`body\` frame (NOT a report \u2014 your status, links and detail go in your REPLY; inline markdown only, no lists or headings), and ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} \`options\` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. The ask is a first-class attention item aimed at that person; your final reply carries the CONTEXT, the ask carries the QUESTION(S). It is written and delivered THE MOMENT you call this \u2014 the person sees it in their inbox while your turn is still running \u2014 so call it once you know the question. The human sends ONE response: supplied answers are recorded, omissions become terminally Unanswered. Ask only when blocked \u2014 never ceremonially. \`replaces\` withdraws a stale ask of yours (or anyone's) in this conversation in the same write, with the reason shown to the person. Targets a human only; to bring a peer AGENT in, name them by \`@handle\` in your reply.`,
+  ask: `Ask a HUMAN a structured question (or a short LIST of them) you need answered to continue, then END your turn \u2014 don't wait for the reply. Use it when you genuinely can't proceed without a person's input (a decision only they can make, a missing fact). Pass \`targetUserId\`. Two forms: a SINGLE question \u2014 a \`headline\` plus a short \`question\` body for the framing the headline can't hold \u2014 OR, when a plan ends with SEVERAL bounded decisions at once, a \`questions\` array of 1\u2013${MAX_ASK_ITEMS} items, each \`{ headline, body?, options? }\`. Provide EITHER \`question\` (single) or \`questions\` (array), never both. **Several decisions landing together are ONE call with \`questions\`** \u2014 never cram the extras into prose, drop all but one, or fire an ask each: a second \`ask\` is a second inbox item competing with the first, never an edit to it. Each question keeps the same form: a one-sentence \`headline\`, a short \`body\` frame (NOT a report \u2014 your status, links and detail go in your REPLY; inline markdown only, no lists or headings), and ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} \`options\` when the answer is a bounded choice \u2014 for a yes/no go-ahead always pass them, so it's one click, not a typed reply. The ask is a first-class attention item aimed at that person; your final reply carries the CONTEXT, the ask carries the QUESTION(S). It is written and delivered THE MOMENT you call this \u2014 the person sees it in their inbox while your turn is still running \u2014 so call it once you know the question. The human sends ONE response: supplied answers are recorded, omissions become terminally Unanswered. A person can DISMISS a question instead of answering it \u2014 it ends, you are not told, nothing wakes you. Check an ask's status before re-raising a vanished one. Ask only when blocked \u2014 never ceremonially. \`replaces\` withdraws a stale ask of yours (or anyone's) in this conversation in the same write, with the reason shown to the person. Targets a human only; to bring a peer AGENT in, name them by \`@handle\` in your reply.`,
   cancel_wake: `Stand down your own wake \u2014 the inverse of \`wake_me\`. No arguments: it cancels the wake you have armed in this conversation, NOW, when you call it. Reach for it when the thing you armed a wake to check has already happened, or the work it was watching is over \u2014 an armed wake you no longer need fires into a turn with nothing to do, and a supervision loop with no off switch is one you can only end by leaving it running. Whether you have one armed is printed in your turn context ("Wake armed: \u2026"); calling this with nothing armed is a clean no-op, no error. Each call acts as it arrives: \`cancel_wake\` then \`wake_me\` leaves the NEW wake armed; \`wake_me\` then \`cancel_wake\` leaves nothing armed. It reaches only your own wake in this conversation \u2014 never a peer's, and never a recurring schedule (those are \`schedules.*\`).`,
   skip_turn: `End your current turn WITHOUT posting a reply. Call this when you've been woken to read a message that genuinely doesn't need a response from you \u2014 a thanks/aside, a question already answered, chatter outside your lane, or something another participant clearly owns. Your turn ends silently: no message bubble is posted. The \`reason\` is a short free-text note for telemetry (e.g. "already answered by cabane", "thanks, nothing to add"). Prefer this over posting a low-value "ok!"/"got it" reply. Don't also write a reply when you skip \u2014 skipping IS the whole turn.`,
   wake_me: `Wake yourself later \u2014 end this turn now and be re-dispatched at a time you pick, with a note you write to yourself. Use it for "wait until X": when the thing you need hasn't happened yet (a PR isn't merged, a human hasn't answered), arm a wake, end your turn, and you're woken later to CHECK \u2014 read the workspace, and either act or re-arm. Ground the delay before you arm it. Almost every wake is short \u2014 seconds to a couple of hours \u2014 waiting on a condition you can name: a session limit resetting, a PR merging. Reach past a few hours only when (a) a human asked for that timing, or (b) the wait is pinned to a real external event you can name \u2014 a report that only runs Mondays, a known reset time. A speculative far-future check-in you invented yourself is the one thing not to arm: if no one asked and you can't name both what clears the wait and why it takes that long, don't arm it \u2014 finish now, or raise an \`ask\`. Pass EXACTLY ONE of \`afterSeconds\` (a relative delay \u2014 \`300\` for five minutes) or \`at\` (an absolute ISO-8601 timestamp WITH a zone, e.g. \`2026-07-16T09:00:00-07:00\` \u2014 YOU compute it; the system never parses natural-language time). \`note\` is a message to your future self \u2014 it becomes the body of the wake message that re-dispatches you, so write the condition to re-check ("check whether CT441 merged yet"). The wake arms NOW, when you call this, and the delay counts from this call; a later \`wake_me\` in the same turn replaces it, and \`cancel_wake\` stands it down. A wake that comes due while your turn is still running waits and is delivered after your reply. This is the ONLY sanctioned way to schedule your own continuation; never reach for a host cron/scheduler. Guardrails: at least 60s out, at most 14 days \u2014 a wake that can't be armed returns an error here, in this call, so you can recompute; widen the interval as a loop ages (5m \u2192 15m \u2192 1h\u2026) rather than hammering; after many consecutive re-arms with no other activity you'll be steered to raise an \`ask\` to the human instead.`,
@@ -8678,8 +8647,7 @@ var TurnExecution = class {
       // CT238: this turn's conversation, forwarded as the active-conversation
       // header so a cross-thread post/spawn stamps its origin.
       activeConversationId: payload.conversationId,
-      // CT598: the workspace this turn runs in — the native runtime's direct REST
-      // tool surface scopes its calls with it.
+      // Workspace coordinate retained in the compatible TurnRequest envelope.
       workspaceId,
       // CT289: the operator's auto-memory escape hatch (machine-local), when set.
       ...this.opts.local.claudeCode ? { claudeCode: this.opts.local.claudeCode } : {}
@@ -9204,11 +9172,9 @@ var Dispatcher = class {
     } catch {
     }
   }
-  // CT1288: `opts.turnId` is a RESUMED turn id — the id this event already ran
-  // under before the companion died. Passing it makes the replay ask the
-  // mailroom to re-admit the turn it already owns, which the server explicitly
-  // supports ("a replay reports, it never re-points"). Omitted on a fresh
-  // dispatch, where minting is correct.
+  // The supervisor supplies a stable turnId on both fresh and resumed dispatch.
+  // resumed is separate: only replay seeds sequence/speech recovery from the
+  // prior span. A direct caller omitting turnId gets a fresh id.
   //
   // CT1261: a short `handle` creates a `TurnExecution` and runs it. The
   // supervisor seam hands the execution exactly the three cross-turn duties —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.97",
+  "version": "0.6.98",
   "type": "module",
   "description": "The Cabane Companion (headless): connect a coding agent on your machine to your Cabane workspace as a responder — drive work against your own codebase, files, and MCP servers without putting any of it in Cabane.",
   "license": "UNLICENSED",