@cabane/companion 0.6.86 → 0.6.88

package/dist/cli.js

@@ -2647,6 +2647,35 @@ var CabaneApi = class {
       signal
     );
   }
+  // CT1357: post ONE ordinary addressed message — not turn speech, no `turnId`
+  // — so `dispatch` is honoured and the target agent is woken. The turn-commit
+  // fork ignores `dispatch` (an act rides its own call now), which leaves this
+  // as the only way a companion can address a peer OUTSIDE a running turn.
+  //
+  // The prepare-failure handback is exactly that case and the reason this
+  // exists. It fires before the turn is ever admitted — the active-run PATCH
+  // that admits it comes after the prepare hook — so `turnAct` is not available:
+  // its route resolves the turn first and 404s when there is none. The failure
+  // notice's own commit is what admits the turn, and by then it has also settled
+  // it. An ordinary addressed post depends on no lease at all, which is what
+  // makes it the right shape here.
+  //
+  // Retried like any durable write, and therefore REQUIRING `idempotencyKey`:
+  // this is not outbox-queued (there is no `(turnId, seq)` for a non-turn row),
+  // so without a key a committed request whose response was lost — or a
+  // redelivered dispatch event — writes a second row and wakes the peer twice.
+  // The server dedupes on `(conversation_id, idempotency_key)`: the repeat
+  // returns the existing row and raises no second dispatch (CT239). Required,
+  // not optional, so a future caller cannot omit it and silently lose the
+  // guarantee.
+  postAddressedMessage(workspaceId, conversationId, body, signal) {
+    return this.request(
+      "POST",
+      `/api/workspaces/${workspaceId}/conversations/${conversationId}/messages`,
+      body,
+      signal ? { retry: true, signal } : { retry: true }
+    );
+  }
   // 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
@@ -7576,12 +7605,14 @@ var MAX_ASK_QUESTION_BYTES = 400;
 var MAX_ASK_HEADLINE_BYTES = 120;
 var MAX_ASK_ITEMS = 20;
 var MAX_ASK_OPTION_BYTES = 200;
+var MIN_ASK_OPTIONS = 2;
+var MAX_ASK_OPTIONS = 4;
 var MAX_WAKE_NOTE_BYTES = 2e3;
 var MAX_WITHDRAW_REASON_BYTES = 400;
 var MAX_SEND_MESSAGE_BYTES = 65536;
 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 2\u20134 \`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 hand work to another AGENT use send/dispatch instead.`,
+  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 hand work to another AGENT use send/dispatch instead.`,
   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.*\`).`,
   reply_to: `Declare which addressed ask your final response answers. Pass the \`messageId\` shown as the owed reply id in your turn context, then finish your response normally. This records lineage only: it does not send another message. The server verifies that this agent owes that ask in this conversation; one reply per turn \u2014 a later call replaces the earlier declaration.`,
   send: `Send one addressed message to another agent in THIS conversation. Pass the peer's \`agentId\` and the complete \`message\` they should act on. The message is WRITTEN the moment you call this \u2014 durable, in the conversation's queue, in the order you called \u2014 but it is DELIVERED only after your own turn ends: the peer is not running yet and cannot answer you inside this turn. Each call is one message; two calls are two messages. Writing \`@handle\` in prose dispatches nobody. An unknown, deactivated, or self target is refused here, in the result. A handoff to a DIFFERENT conversation is \`conversations.create\` / \`conversations.post\` with their \`dispatch\` field instead. Never use send to hand an answer back to the requester \u2014 declare that with reply_to.`,
@@ -7594,11 +7625,11 @@ var TURN_CONTROL_FIELD_DESCRIPTIONS = {
     targetUserId: "The workspace member (human) to ask \u2014 a user id, from your turn context's roster.",
     question: `SINGLE-question form: a short body \u2014 one or two sentences of framing the headline can't hold. NOT a report (up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only). Provide EITHER this or \`questions\`, not both. Put the crisp one-sentence question in \`headline\`.`,
     headline: `SINGLE-question form: the question itself as ONE clear, capitalized sentence ending in \`?\` ("Do we go to prod?"), up to ${MAX_ASK_HEADLINE_BYTES} characters. What the human reads first in the inbox and the chip \u2014 one scannable question, no elaboration (that goes in \`question\`). Strongly encouraged.`,
-    options: `SINGLE-question form: optional 2\u20134 suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
+    options: `SINGLE-question form: optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
     questions: `MULTI-question form: 1\u2013${MAX_ASK_ITEMS} questions to ask at once, when a plan ends with several bounded decisions. Provide EITHER this or \`question\`/\`headline\`/\`options\`, not both.`,
     "questions.headline": `The one-sentence question ("Do we go to prod?") \u2014 required for each item, up to ${MAX_ASK_HEADLINE_BYTES} characters.`,
     "questions.body": `Optional short framing beneath the headline, up to ${MAX_ASK_QUESTION_BYTES} characters. NOT a report.`,
-    "questions.options": `Optional 2\u20134 one-click answers for this question, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
+    "questions.options": `Optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} one-click answers for this question, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
     replaces: "Withdraw a stale ask in this conversation as part of raising this one. Both land in a single write, so the person goes from the old question to the new one and never sees neither or both.",
     "replaces.askId": "The id of the open ask to withdraw.",
     "replaces.reason": `Why the old question is no longer the question \u2014 shown to the person on their Done row. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
@@ -7753,12 +7784,12 @@ function createTurnControlMcpServer(acts, skipState, replyState) {
           targetUserId: z13.string().uuid().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.targetUserId),
           question: z13.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.question),
           headline: z13.string().min(1).max(MAX_ASK_HEADLINE_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.headline),
-          options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(2).max(4).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.options),
+          options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.options),
           questions: z13.array(
             z13.object({
               headline: z13.string().min(1).max(MAX_ASK_HEADLINE_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.headline"]),
               body: z13.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.body"]),
-              options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(2).max(4).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.options"])
+              options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.options"])
             })
           ).min(1).max(MAX_ASK_ITEMS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.questions),
           replaces: z13.object({
@@ -8615,12 +8646,31 @@ var TurnExecution = class {
     }
     let hookEnv;
     const triggerIsPrepareFailure = this.turnContext.message.body.startsWith(PREPARE_FAILED_PREFIX);
-    const prepareFailureDispatch = this.turnContext.dispatchedByAgentId && !triggerIsPrepareFailure ? {
-      dispatch: this.turnContext.dispatchedByAgentId,
-      dispatchBody: `${PREPARE_FAILED_PREFIX}
+    const sendPrepareFailureHandback = async () => {
+      if (!this.turnContext.dispatchedByAgentId || triggerIsPrepareFailure) return;
+      try {
+        await this.opts.api.postAddressedMessage(workspaceId, payload.conversationId, {
+          body: `${PREPARE_FAILED_PREFIX}
 
-The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`
-    } : {};
+The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`,
+          dispatch: this.turnContext.dispatchedByAgentId,
+          // Keyed on the TRIGGER, not the turn: a redelivered dispatch event is
+          // the replay this has to survive, and it mints a fresh `turnId` while
+          // carrying the same `messageId`. One handback per failed pickup of a
+          // given trigger — which is also CT992's rule, that the first failure
+          // is the one carrying information. A genuine re-dispatch after a
+          // repair authors a NEW trigger message, so it keys differently and
+          // hands back again.
+          idempotencyKey: `prepare-failure-handback:${payload.messageId}`,
+          parentMessageId: payload.messageId
+        });
+      } catch (err) {
+        turnLog.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "dispatcher: prepare-failure handback failed"
+        );
+      }
+    };
     if (prepareHook) {
       let cached2 = readPrepared(workspaceId, payload.conversationId, payload.agentId);
       if (cached2 && !checkoutState(cached2.cwd).ok) {
@@ -8659,8 +8709,7 @@ The dispatched turn could not start. Re-dispatch it after repairing the preparat
 ${reason}`,
                 kind: "final",
                 turnId,
-                parentMessageId: payload.messageId,
-                ...prepareFailureDispatch
+                parentMessageId: payload.messageId
               });
             } catch (postErr) {
               turnLog.warn(
@@ -8668,6 +8717,7 @@ ${reason}`,
                 "dispatcher: prepare-rejection post failed"
               );
             }
+            await sendPrepareFailureHandback();
             throw this.concluded(`prepare_failed: ${reason}`);
           }
         }
@@ -8735,8 +8785,7 @@ ${reason}`,
               kind: "final",
               turnId,
               // CT113: stamp the parent even on the prepare-failed close.
-              parentMessageId: payload.messageId,
-              ...prepareFailureDispatch
+              parentMessageId: payload.messageId
             });
           } catch (postErr) {
             turnLog.warn(
@@ -8744,6 +8793,7 @@ ${reason}`,
               "dispatcher: prepare-failure post failed"
             );
           }
+          await sendPrepareFailureHandback();
           const failReason = `prepare_failed: ${reason}`;
           throw this.concluded(failReason);
         }

package/dist/runtime.js

@@ -2065,6 +2065,35 @@ var CabaneApi = class {
       signal
     );
   }
+  // CT1357: post ONE ordinary addressed message — not turn speech, no `turnId`
+  // — so `dispatch` is honoured and the target agent is woken. The turn-commit
+  // fork ignores `dispatch` (an act rides its own call now), which leaves this
+  // as the only way a companion can address a peer OUTSIDE a running turn.
+  //
+  // The prepare-failure handback is exactly that case and the reason this
+  // exists. It fires before the turn is ever admitted — the active-run PATCH
+  // that admits it comes after the prepare hook — so `turnAct` is not available:
+  // its route resolves the turn first and 404s when there is none. The failure
+  // notice's own commit is what admits the turn, and by then it has also settled
+  // it. An ordinary addressed post depends on no lease at all, which is what
+  // makes it the right shape here.
+  //
+  // Retried like any durable write, and therefore REQUIRING `idempotencyKey`:
+  // this is not outbox-queued (there is no `(turnId, seq)` for a non-turn row),
+  // so without a key a committed request whose response was lost — or a
+  // redelivered dispatch event — writes a second row and wakes the peer twice.
+  // The server dedupes on `(conversation_id, idempotency_key)`: the repeat
+  // returns the existing row and raises no second dispatch (CT239). Required,
+  // not optional, so a future caller cannot omit it and silently lose the
+  // guarantee.
+  postAddressedMessage(workspaceId, conversationId, body, signal) {
+    return this.request(
+      "POST",
+      `/api/workspaces/${workspaceId}/conversations/${conversationId}/messages`,
+      body,
+      signal ? { retry: true, signal } : { retry: true }
+    );
+  }
   // 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
@@ -7073,12 +7102,14 @@ var MAX_ASK_QUESTION_BYTES = 400;
 var MAX_ASK_HEADLINE_BYTES = 120;
 var MAX_ASK_ITEMS = 20;
 var MAX_ASK_OPTION_BYTES = 200;
+var MIN_ASK_OPTIONS = 2;
+var MAX_ASK_OPTIONS = 4;
 var MAX_WAKE_NOTE_BYTES = 2e3;
 var MAX_WITHDRAW_REASON_BYTES = 400;
 var MAX_SEND_MESSAGE_BYTES = 65536;
 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 2\u20134 \`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 hand work to another AGENT use send/dispatch instead.`,
+  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 hand work to another AGENT use send/dispatch instead.`,
   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.*\`).`,
   reply_to: `Declare which addressed ask your final response answers. Pass the \`messageId\` shown as the owed reply id in your turn context, then finish your response normally. This records lineage only: it does not send another message. The server verifies that this agent owes that ask in this conversation; one reply per turn \u2014 a later call replaces the earlier declaration.`,
   send: `Send one addressed message to another agent in THIS conversation. Pass the peer's \`agentId\` and the complete \`message\` they should act on. The message is WRITTEN the moment you call this \u2014 durable, in the conversation's queue, in the order you called \u2014 but it is DELIVERED only after your own turn ends: the peer is not running yet and cannot answer you inside this turn. Each call is one message; two calls are two messages. Writing \`@handle\` in prose dispatches nobody. An unknown, deactivated, or self target is refused here, in the result. A handoff to a DIFFERENT conversation is \`conversations.create\` / \`conversations.post\` with their \`dispatch\` field instead. Never use send to hand an answer back to the requester \u2014 declare that with reply_to.`,
@@ -7091,11 +7122,11 @@ var TURN_CONTROL_FIELD_DESCRIPTIONS = {
     targetUserId: "The workspace member (human) to ask \u2014 a user id, from your turn context's roster.",
     question: `SINGLE-question form: a short body \u2014 one or two sentences of framing the headline can't hold. NOT a report (up to ${MAX_ASK_QUESTION_BYTES} characters, inline markdown only). Provide EITHER this or \`questions\`, not both. Put the crisp one-sentence question in \`headline\`.`,
     headline: `SINGLE-question form: the question itself as ONE clear, capitalized sentence ending in \`?\` ("Do we go to prod?"), up to ${MAX_ASK_HEADLINE_BYTES} characters. What the human reads first in the inbox and the chip \u2014 one scannable question, no elaboration (that goes in \`question\`). Strongly encouraged.`,
-    options: `SINGLE-question form: optional 2\u20134 suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
+    options: `SINGLE-question form: optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} suggested one-click answers, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
     questions: `MULTI-question form: 1\u2013${MAX_ASK_ITEMS} questions to ask at once, when a plan ends with several bounded decisions. Provide EITHER this or \`question\`/\`headline\`/\`options\`, not both.`,
     "questions.headline": `The one-sentence question ("Do we go to prod?") \u2014 required for each item, up to ${MAX_ASK_HEADLINE_BYTES} characters.`,
     "questions.body": `Optional short framing beneath the headline, up to ${MAX_ASK_QUESTION_BYTES} characters. NOT a report.`,
-    "questions.options": `Optional 2\u20134 one-click answers for this question, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
+    "questions.options": `Optional ${MIN_ASK_OPTIONS}\u2013${MAX_ASK_OPTIONS} one-click answers for this question, up to ${MAX_ASK_OPTION_BYTES} characters each.`,
     replaces: "Withdraw a stale ask in this conversation as part of raising this one. Both land in a single write, so the person goes from the old question to the new one and never sees neither or both.",
     "replaces.askId": "The id of the open ask to withdraw.",
     "replaces.reason": `Why the old question is no longer the question \u2014 shown to the person on their Done row. Up to ${MAX_WITHDRAW_REASON_BYTES} characters.`
@@ -7250,12 +7281,12 @@ function createTurnControlMcpServer(acts, skipState, replyState) {
           targetUserId: z13.string().uuid().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.targetUserId),
           question: z13.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.question),
           headline: z13.string().min(1).max(MAX_ASK_HEADLINE_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.headline),
-          options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(2).max(4).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.options),
+          options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.options),
           questions: z13.array(
             z13.object({
               headline: z13.string().min(1).max(MAX_ASK_HEADLINE_BYTES).describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.headline"]),
               body: z13.string().min(1).max(MAX_ASK_QUESTION_BYTES).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.body"]),
-              options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(2).max(4).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.options"])
+              options: z13.array(z13.string().min(1).max(MAX_ASK_OPTION_BYTES)).min(MIN_ASK_OPTIONS).max(MAX_ASK_OPTIONS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask["questions.options"])
             })
           ).min(1).max(MAX_ASK_ITEMS).optional().describe(TURN_CONTROL_FIELD_DESCRIPTIONS.ask.questions),
           replaces: z13.object({
@@ -8112,12 +8143,31 @@ var TurnExecution = class {
     }
     let hookEnv;
     const triggerIsPrepareFailure = this.turnContext.message.body.startsWith(PREPARE_FAILED_PREFIX);
-    const prepareFailureDispatch = this.turnContext.dispatchedByAgentId && !triggerIsPrepareFailure ? {
-      dispatch: this.turnContext.dispatchedByAgentId,
-      dispatchBody: `${PREPARE_FAILED_PREFIX}
+    const sendPrepareFailureHandback = async () => {
+      if (!this.turnContext.dispatchedByAgentId || triggerIsPrepareFailure) return;
+      try {
+        await this.opts.api.postAddressedMessage(workspaceId, payload.conversationId, {
+          body: `${PREPARE_FAILED_PREFIX}
 
-The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`
-    } : {};
+The dispatched turn could not start. Re-dispatch it after repairing the preparation failure shown in this conversation.`,
+          dispatch: this.turnContext.dispatchedByAgentId,
+          // Keyed on the TRIGGER, not the turn: a redelivered dispatch event is
+          // the replay this has to survive, and it mints a fresh `turnId` while
+          // carrying the same `messageId`. One handback per failed pickup of a
+          // given trigger — which is also CT992's rule, that the first failure
+          // is the one carrying information. A genuine re-dispatch after a
+          // repair authors a NEW trigger message, so it keys differently and
+          // hands back again.
+          idempotencyKey: `prepare-failure-handback:${payload.messageId}`,
+          parentMessageId: payload.messageId
+        });
+      } catch (err) {
+        turnLog.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "dispatcher: prepare-failure handback failed"
+        );
+      }
+    };
     if (prepareHook) {
       let cached2 = readPrepared(workspaceId, payload.conversationId, payload.agentId);
       if (cached2 && !checkoutState(cached2.cwd).ok) {
@@ -8156,8 +8206,7 @@ The dispatched turn could not start. Re-dispatch it after repairing the preparat
 ${reason}`,
                 kind: "final",
                 turnId,
-                parentMessageId: payload.messageId,
-                ...prepareFailureDispatch
+                parentMessageId: payload.messageId
               });
             } catch (postErr) {
               turnLog.warn(
@@ -8165,6 +8214,7 @@ ${reason}`,
                 "dispatcher: prepare-rejection post failed"
               );
             }
+            await sendPrepareFailureHandback();
             throw this.concluded(`prepare_failed: ${reason}`);
           }
         }
@@ -8232,8 +8282,7 @@ ${reason}`,
               kind: "final",
               turnId,
               // CT113: stamp the parent even on the prepare-failed close.
-              parentMessageId: payload.messageId,
-              ...prepareFailureDispatch
+              parentMessageId: payload.messageId
             });
           } catch (postErr) {
             turnLog.warn(
@@ -8241,6 +8290,7 @@ ${reason}`,
               "dispatcher: prepare-failure post failed"
             );
           }
+          await sendPrepareFailureHandback();
           const failReason = `prepare_failed: ${reason}`;
           throw this.concluded(failReason);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.86",
+  "version": "0.6.88",
   "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",