commandmate 0.49.2 → 0.50.0

package/dist/server/src/lib/session/instance-input-lock.js

@@ -56,11 +56,14 @@
  * @module lib/session/instance-input-lock
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InputBoundaryRefusedError = exports.INPUT_BOUNDARY_REFUSED_CODE = exports.InstanceInputSessionReplacedError = exports.InstanceInputOwnershipLostError = exports.InstanceInputLockTimeoutError = exports.INSTANCE_INPUT_OWNERSHIP_LOST_CODE = exports.INSTANCE_INPUT_SESSION_REPLACED_CODE = exports.INSTANCE_INPUT_LOCK_TIMEOUT_CODE = exports.CARRIED_PASTE_MARK_TTL_MS = exports.LATE_PASTE_OBSERVE_MS = exports.INSTANCE_INPUT_LOCK_WAIT_MS = void 0;
+exports.InputBoundaryRefusedError = exports.INPUT_BOUNDARY_REFUSED_CODE = exports.ANSWER_SKIP_RECORD_MAX = exports.InstanceInputSessionReplacedError = exports.InstanceInputOwnershipLostError = exports.InstanceInputLockTimeoutError = exports.INSTANCE_INPUT_OWNERSHIP_LOST_CODE = exports.INSTANCE_INPUT_SESSION_REPLACED_CODE = exports.INSTANCE_INPUT_LOCK_TIMEOUT_CODE = exports.CARRIED_PASTE_MARK_TTL_MS = exports.LATE_PASTE_OBSERVE_MS = exports.INSTANCE_INPUT_LOCK_WAIT_MS = void 0;
+exports.instanceInputAnswerSkipLife = instanceInputAnswerSkipLife;
+exports.isInstanceInputAnswerSkipLife = isInstanceInputAnswerSkipLife;
 exports.currentInstanceInputTicket = currentInstanceInputTicket;
 exports.withInstanceInputLock = withInstanceInputLock;
 exports.instanceInputReadMark = instanceInputReadMark;
 exports.instanceInputLaunchReadMark = instanceInputLaunchReadMark;
+exports.instanceInputGenerationMark = instanceInputGenerationMark;
 exports.answerUnderInstanceInputLock = answerUnderInstanceInputLock;
 exports.leaveCarriedPasteMark = leaveCarriedPasteMark;
 exports.getCarriedPasteMark = getCarriedPasteMark;
@@ -70,6 +73,7 @@ exports.invalidateInstanceInput = invalidateInstanceInput;
 exports.isInputBoundaryRefusal = isInputBoundaryRefusal;
 exports.observeInputStart = observeInputStart;
 exports.noteInputStart = noteInputStart;
+exports.noteInputTicket = noteInputTicket;
 exports.noteDispatchStart = noteDispatchStart;
 exports.noteDispatchFailed = noteDispatchFailed;
 exports.resetInstanceInputLocks = resetInstanceInputLocks;
@@ -196,6 +200,80 @@ function noteSharedRelease() {
  */
 const revokedTickets = (0, global_state_1.getOrInitGlobal)('__instanceInputRevoked', () => new WeakSet());
 const ownerScope = (0, global_state_1.getOrInitGlobal)('__instanceInputOwnerScope', () => new node_async_hooks_1.AsyncLocalStorage());
+/** How many sessions' lives {@link answerSkipLives} keeps (Issue #4175). */
+exports.ANSWER_SKIP_RECORD_MAX = 256;
+const answerSkipLives = (0, global_state_1.getOrInitGlobal)('__instanceInputAnswerSkipLives', () => ({ seq: 0, droppedUpTo: 0, bySession: new Map() }));
+/** Each scope's records, by session. */
+const answerSkipRecords = new WeakMap();
+function answerSkipLifeNow(sessionName) {
+    return { known: answerSkipLives.bySession.get(sessionName) ?? null, seq: answerSkipLives.seq };
+}
+/** Whether `sessionName` is still in the life `life` was taken in. */
+function stillAnswerSkipLife(sessionName, life) {
+    const current = answerSkipLives.bySession.get(sessionName);
+    if (life.known !== null)
+        return current === life.known;
+    return current === undefined && answerSkipLives.droppedUpTo <= life.seq;
+}
+function beginAnswerSkipLife(sessionName) {
+    const lives = answerSkipLives;
+    lives.seq += 1;
+    lives.bySession.delete(sessionName);
+    lives.bySession.set(sessionName, lives.seq);
+    while (lives.bySession.size > exports.ANSWER_SKIP_RECORD_MAX) {
+        const oldest = lives.bySession.entries().next().value;
+        if (oldest === undefined)
+            break;
+        lives.bySession.delete(oldest[0]);
+        lives.droppedUpTo = Math.max(lives.droppedUpTo, oldest[1]);
+    }
+}
+/** Read-only (Issue #4189): {@link InstanceInputAnswerSkipLife} as it stands now. */
+function instanceInputAnswerSkipLife(sessionName) {
+    return answerSkipLifeNow(sessionName);
+}
+/** Read-only (Issue #4189): whether the session is still in the life `life` was taken in. */
+function isInstanceInputAnswerSkipLife(sessionName, life) {
+    return stillAnswerSkipLife(sessionName, life);
+}
+/** The scope's record for the session, if it is of the life this answer is in. */
+function answerSkipRecordOf(scope, sessionName, life) {
+    if (!stillAnswerSkipLife(sessionName, life))
+        return undefined;
+    const record = answerSkipRecords.get(scope)?.get(sessionName);
+    return record !== undefined && stillAnswerSkipLife(sessionName, record.life) ? record : undefined;
+}
+function putAnswerSkipRecord(scope, sessionName, record) {
+    let bySession = answerSkipRecords.get(scope);
+    if (bySession === undefined) {
+        bySession = new Map();
+        answerSkipRecords.set(scope, bySession);
+    }
+    bySession.set(sessionName, record);
+}
+/** Write a decline's warn unless the scope's streak is already this reason. */
+function warnAnswerSkip(event, sessionName, scope, life, reason, fields) {
+    if (scope === undefined) {
+        logger.warn(event, fields);
+        return;
+    }
+    if (answerSkipRecordOf(scope, sessionName, life)?.reason === reason) {
+        logger.debug(event, { ...fields, repeated: true });
+        return;
+    }
+    logger.warn(event, fields);
+    // An answer of an older life writes nothing for the new one.
+    if (stillAnswerSkipLife(sessionName, life))
+        putAnswerSkipRecord(scope, sessionName, { life, reason });
+}
+/** A decline that is not a warn (`target-changed`), or an answer that went through, ends the streak. */
+function endAnswerSkipStreak(sessionName, scope, life, reason) {
+    if (scope === undefined)
+        return;
+    const record = answerSkipRecordOf(scope, sessionName, life);
+    if (record !== undefined)
+        record.reason = reason;
+}
 function entryOf(sessionName) {
     let entry = entries.get(sessionName);
     if (entry === undefined) {
@@ -364,6 +442,18 @@ function instanceInputReadMark() {
 function instanceInputLaunchReadMark() {
     return (generationSeq.exclusiveEvents ?? 0) + (generationSeq.sharedReleases ?? 0);
 }
+/**
+ * The generation counter as it stands now (Issue #4065): every ticket granted
+ * from here on carries a larger generation. A send request reads it once, at
+ * its outermost entry (the send route before it reads the body; the send
+ * service for the timer and relay), and a refusal it records before any lock
+ * was granted to it carries the value — so it is not taken over the record of
+ * a send granted after the request began. Process-wide, like the generations
+ * themselves; 0 before any grant.
+ */
+function instanceInputGenerationMark() {
+    return generationSeq.last;
+}
 function skipOfLockError(error) {
     const code = typeof error === 'object' && error !== null ? error.code : undefined;
     if (code === exports.INSTANCE_INPUT_LOCK_TIMEOUT_CODE)
@@ -399,12 +489,18 @@ function skipOfLockError(error) {
  * compared before admission there, since the launch's own admission moves it,
  * and `readMark` is {@link instanceInputLaunchReadMark}, so a `shared` answer
  * that finished after the launch's read also makes it read again (review P2-1).
+ *
+ * Issue #4175: `repeatScope` — one object per wait that asks again on every poll —
+ * makes a decline's warn once while the same reason goes on in that scope (see
+ * {@link ANSWER_SKIP_RECORD_MAX}'s record). Without it every decline is a warn.
  */
 async function answerUnderInstanceInputLock(sessionName, readMark, stillApplies, answer, options = {}) {
     // A context that already owns the composer (a send's own readiness wait)
     // has held it since before its read: it joins, and nothing is read again.
     const joined = currentInstanceInputTicket(sessionName) !== null;
     const mode = options.mode ?? 'shared';
+    const scope = options.repeatScope;
+    const life = answerSkipLifeNow(sessionName);
     const movedBeforeAdmission = (mode === 'exclusive' ? instanceInputLaunchReadMark() : instanceInputReadMark()) !== readMark;
     let admitted = false;
     try {
@@ -418,7 +514,7 @@ async function answerUnderInstanceInputLock(sessionName, readMark, stillApplies,
                     applies = await stillApplies();
                 }
                 catch (error) {
-                    logger.warn('instance-input-answer-recheck-failed', {
+                    warnAnswerSkip('instance-input-answer-recheck-failed', sessionName, scope, life, 'recheck-failed', {
                         sessionName,
                         error: error instanceof Error ? error.message : String(error),
                     });
@@ -426,12 +522,15 @@ async function answerUnderInstanceInputLock(sessionName, readMark, stillApplies,
                 }
                 if (!applies) {
                     logger.info('instance-input-answer-target-changed', { sessionName, generation: ticket.generation });
+                    endAnswerSkipStreak(sessionName, scope, life, 'target-changed');
                     return { answered: false, reason: 'target-changed' };
                 }
             }
             if (!ticket.isCurrent())
                 return { answered: false, reason: 'input-lock-lost' };
-            return { answered: true, value: await answer(ticket) };
+            const value = await answer(ticket);
+            endAnswerSkipStreak(sessionName, scope, life, null);
+            return { answered: true, value };
         }, { waitMs: options.waitMs, mode });
     }
     catch (error) {
@@ -440,7 +539,7 @@ async function answerUnderInstanceInputLock(sessionName, readMark, stillApplies,
         const skip = admitted ? null : skipOfLockError(error);
         if (skip === null)
             throw error;
-        logger.warn('instance-input-answer-not-admitted', { sessionName, reason: skip });
+        warnAnswerSkip('instance-input-answer-not-admitted', sessionName, scope, life, skip, { sessionName, reason: skip });
         return { answered: false, reason: skip };
     }
 }
@@ -519,6 +618,8 @@ async function waitOutCarriedPasteMark(ticket) {
  * pane it just created.
  */
 function invalidateInstanceInput(sessionName) {
+    // Issue #4175: the new process's first declined answer is a warn of its own.
+    beginAnswerSkipLife(sessionName);
     const entry = entries.get(sessionName);
     if (entry === undefined)
         return;
@@ -584,12 +685,16 @@ const inputStartScope = (0, global_state_1.getOrInitGlobal)('__instanceInputStar
  *   {@link noteInputStart}, so a caller can read state as of the moment the
  *   body started going in (Issue #3957: the send route's open-turn reading). A
  *   throw is logged and does not fail the send.
+ * @param request - Issue #4065: told, synchronously and as it happens, the
+ *   generation of the body's input lock ({@link noteInputTicket}) and a
+ *   dispatch ({@link noteDispatchStart}) — so a send that throws afterwards
+ *   still leaves them with the caller.
  * @returns `fn`'s value, and the moment input started — null when nothing in
  *   `fn` noted one (a path that never types a body: opencode's HTTP delivery,
  *   or a send refused before its first key). Never set when `fn` throws.
  */
-async function observeInputStart(fn, onStart, boundary) {
-    const observer = { at: null, onStart, boundary, dispatchOpen: false };
+async function observeInputStart(fn, onStart, boundary, request) {
+    const observer = { at: null, onStart, boundary, dispatchOpen: false, request };
     const value = await inputStartScope.run(observer, fn);
     return { value, inputStartedAt: observer.at };
 }
@@ -623,6 +728,25 @@ function runBoundaryHook(observer, at, kind) {
         throw error instanceof InputBoundaryRefusedError ? error : new InputBoundaryRefusedError(error);
     }
 }
+/**
+ * Tell the request observing this context the generation its body's input
+ * lock was granted under (Issue #4065). Called by the shared sender right
+ * after its lock is granted or joined — never for a launch key, an answer, a
+ * trust dialog or copilot's `/model` and selection-list keys, whose tickets
+ * are not the body's. Synchronous, never throws; outside an
+ * {@link observeInputStart} context it does nothing.
+ */
+function noteInputTicket(ticket) {
+    const observer = inputStartScope.getStore();
+    if (observer?.request?.onTicket === undefined)
+        return;
+    try {
+        observer.request.onTicket(ticket.generation);
+    }
+    catch (error) {
+        logger.warn('input-ticket-observer-failed', { error: error instanceof Error ? error.message : String(error) });
+    }
+}
 /**
  * Note that a body is about to be DISPATCHED without being typed (Issue #3957):
  * opencode's HTTP send, which reports no input start. Runs the required
@@ -636,6 +760,14 @@ function noteDispatchStart(now = new Date()) {
         return;
     runBoundaryHook(observer, now, 'dispatch');
     observer.dispatchOpen = true;
+    // Issue #4065: after the required hook, so a refused dispatch — nothing went
+    // out — is not reported as one.
+    try {
+        observer.request?.onDispatch?.();
+    }
+    catch (error) {
+        logger.warn('dispatch-start-observer-failed', { error: error instanceof Error ? error.message : String(error) });
+    }
 }
 /**
  * Say how a dispatch noted by {@link noteDispatchStart} ended when it did not
@@ -661,4 +793,6 @@ function resetInstanceInputLocks() {
             clearTimeout(waiter.timer);
     }
     entries.clear();
+    answerSkipLives.bySession.clear();
+    answerSkipLives.droppedUpTo = answerSkipLives.seq;
 }

package/dist/server/src/lib/session/prompt-submit-receipt.js

@@ -27,16 +27,19 @@
  * @module lib/session/prompt-submit-receipt
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportsPrompts = reportsPrompts;
 exports.notePromptSubmitSession = notePromptSubmitSession;
 exports.notePromptSubmitHook = notePromptSubmitHook;
 exports.getPromptSubmitTarget = getPromptSubmitTarget;
 exports.readPromptSubmitReceipt = readPromptSubmitReceipt;
 exports.noteSubmittedBody = noteSubmittedBody;
+exports.findSubmittedBody = findSubmittedBody;
 exports.matchesSubmittedBody = matchesSubmittedBody;
 exports.clearPromptSubmitReceipts = clearPromptSubmitReceipts;
 const crypto_1 = require("crypto");
 const auto_yes_state_1 = require("../../lib/auto-yes-state");
 const global_state_1 = require("../../lib/global-state");
+const send_attempt_state_1 = require("../../lib/session/send-attempt-state");
 /** How many sessions are tracked at once; the least recently started is forgotten first. */
 const MAX_TRACKED_SESSIONS = 1024;
 /**
@@ -49,13 +52,41 @@ const sessionByInstance = (0, global_state_1.getOrInitGlobal)('__promptSubmitSes
 function instanceKey(target) {
     return (0, auto_yes_state_1.buildCompositeKey)(target.worktreeId, target.cliToolId, target.instanceId);
 }
-/** The tools whose prompt hook is trusted as proof of a submit. */
+/**
+ * The tools whose prompt hook is trusted as proof of a submit — and, since
+ * Issue #4048, the only ones whose `lastSend` a found body may demote.
+ */
 function reportsPrompts(cliToolId) {
     // Claude only. codex's hooks run in a machine-wide daemon that can file a
     // turn under the wrong instance (#2874), and copilot's arrive out of order
     // (#1903); neither is evidence about one pane's composer.
     return cliToolId === 'claude';
 }
+/**
+ * The entry a send looks at (Issue #4048). By name alone, the name's entry. With
+ * an explicit target, the same entry only when the target's instance currently
+ * maps to this very name and the entry is that instance's — a target and a name
+ * that disagree are no entry at all, so nothing about another instance (or a
+ * generation the instance no longer runs under this name) is taken as proof.
+ * Looking never registers or resets anything.
+ */
+function entryFor(sessionName, cliToolId, expected) {
+    const entry = sessions.get(sessionName);
+    if (entry === undefined || expected === undefined)
+        return entry;
+    let key;
+    try {
+        key = instanceKey({ worktreeId: expected.worktreeId, cliToolId, instanceId: expected.instanceId });
+    }
+    catch {
+        return undefined;
+    }
+    if (sessionByInstance.get(key) !== sessionName)
+        return undefined;
+    if (instanceKey(entry.target) !== key)
+        return undefined;
+    return entry;
+}
 /**
  * A session's generation began here (`beginAgentSession`). Forgets what was
  * known about the previous process in the same pane name.
@@ -88,25 +119,49 @@ function notePromptSubmitHook(target, event, at) {
     if (entry === undefined)
         return;
     entry.lastEventAt = at;
-    if (event === 'user_prompt_submit')
+    if (event === 'user_prompt_submit') {
         entry.lastPromptAt = at;
+        // Issue #4048: the agent took a prompt, so a body the screen alone called
+        // submitted is no longer one to look for — the late report was that body's,
+        // or a later send went through after it. Either way no later send may find
+        // it and demote a record (review: X restored after Y's success).
+        entry.submittedBody = null;
+    }
 }
-/** The instance a session this server started runs, or null. */
-function getPromptSubmitTarget(sessionName) {
-    return sessions.get(sessionName)?.target ?? null;
+/**
+ * The instance a session this server started runs, or null. With `expected`
+ * (Issue #4048), null unless the explicit target names the same entry.
+ */
+function getPromptSubmitTarget(sessionName, expected) {
+    if (expected === undefined)
+        return sessions.get(sessionName)?.target ?? null;
+    return entryFor(sessionName, expected.cliToolId, expected)?.target ?? null;
 }
 /**
  * Whether the screen's B/F verdict for a send whose first Enter went in at
  * `enteredAt` needs the agent's own report (Issue #4035).
+ *
+ * `expected` (Issue #4048) is the instance the send was made for; a name that
+ * does not resolve to that instance's entry answers `not-required` (never
+ * `received`), exactly as a session this server did not start.
+ *
+ * Known limit, kept as it is (Issue #4048 item 3): the question is asked on
+ * every read, and a session whose first hook (`SessionStart`) has not arrived
+ * by the read-back is answered `not-required` — the screen's B/F verdict then
+ * stands and the send returns at once, before a hook that is only late could
+ * turn it into `awaited`. Pinned by `prompt-submit-receipt-4048.test.ts`.
  */
-function readPromptSubmitReceipt(sessionName, cliToolId, enteredAt) {
+function readPromptSubmitReceipt(sessionName, cliToolId, enteredAt, expected) {
     if (!reportsPrompts(cliToolId))
         return 'not-required';
-    const entry = sessions.get(sessionName);
+    const entry = entryFor(sessionName, cliToolId, expected);
     if (entry === undefined || entry.target.cliToolId !== cliToolId)
         return 'not-required';
     if (entry.lastPromptAt !== null && entry.lastPromptAt >= enteredAt)
         return 'received';
+    // Issue #4048 item 3 (known limit): no hook yet from this process — the
+    // screen decides, and a `SessionStart` that arrives after this read is not
+    // waited for.
     if (entry.lastEventAt === null || entry.lastEventAt < entry.startedAt)
         return 'not-required';
     if (entry.lastPromptAt !== null && entry.lastPromptAt >= entry.startedAt)
@@ -122,31 +177,45 @@ function digest(text) {
 /**
  * The sender reported this body submitted on this session from the screen
  * alone — not for one the agent's hook reported, which did leave.
+ *
+ * `expected` (Issue #4048): with an explicit target, nothing is noted unless it
+ * names the same entry as the session name.
  */
-function noteSubmittedBody(sessionName, message) {
-    const entry = sessions.get(sessionName);
+function noteSubmittedBody(sessionName, message, expected) {
+    const entry = expected === undefined ? sessions.get(sessionName) : entryFor(sessionName, expected.cliToolId, expected);
     if (entry === undefined)
         return;
     const body = compact(message);
     entry.submittedBody = {
         full: digest(body),
         prefix: body.length >= BODY_PREFIX_CHARS ? digest(body.slice(0, BODY_PREFIX_CHARS)) : null,
+        messageDigest: (0, send_attempt_state_1.sendMessageDigest)(message),
     };
 }
 /**
- * Whether a composer read is the body last reported submitted on this session:
- * the whole of it, or — for a read long enough — its beginning.
+ * The body last reported submitted on this session, when a composer read is it
+ * — the whole of it, or (for a read long enough) its beginning — or null.
+ * `messageDigest` is the attempt's digest, for demoting only that attempt's
+ * record (Issue #4048).
  */
-function matchesSubmittedBody(sessionName, composerText) {
-    const body = sessions.get(sessionName)?.submittedBody;
+function findSubmittedBody(sessionName, composerText, expected) {
+    const entry = expected === undefined ? sessions.get(sessionName) : entryFor(sessionName, expected.cliToolId, expected);
+    const body = entry?.submittedBody;
     if (body === null || body === undefined)
-        return false;
+        return null;
     const read = compact(composerText);
     if (read === '')
-        return false;
-    if (digest(read) === body.full)
-        return true;
-    return body.prefix !== null && read.length >= BODY_PREFIX_CHARS && digest(read.slice(0, BODY_PREFIX_CHARS)) === body.prefix;
+        return null;
+    const matched = digest(read) === body.full ||
+        (body.prefix !== null && read.length >= BODY_PREFIX_CHARS && digest(read.slice(0, BODY_PREFIX_CHARS)) === body.prefix);
+    return matched ? { messageDigest: body.messageDigest } : null;
+}
+/**
+ * Whether a composer read is the body last reported submitted on this session:
+ * the whole of it, or — for a read long enough — its beginning.
+ */
+function matchesSubmittedBody(sessionName, composerText) {
+    return findSubmittedBody(sessionName, composerText) !== null;
 }
 /** Forget every session (tests). */
 function clearPromptSubmitReceipts() {

package/dist/server/src/lib/session/prompt-waiting-guard.js

@@ -24,6 +24,7 @@ exports.PROMPT_WAITING_CODE = void 0;
 exports.isPromptWaiting = isPromptWaiting;
 exports.promptWaitingMessage = promptWaitingMessage;
 const manager_1 = require("../../lib/cli-tools/manager");
+const respond_target_1 = require("../../lib/session/respond-target");
 const cli_session_1 = require("../../lib/session/cli-session");
 const status_detector_1 = require("../../lib/detection/status-detector");
 const status_capture_config_1 = require("../../config/status-capture-config");
@@ -133,11 +134,16 @@ async function isPromptWaiting(worktreeId, cliToolId, instanceId, options) {
  * waiting. A request for the primary instance (no `instanceId`) gets the
  * sentence as before.
  *
+ * Issue #4049: a request that named only a tool other than the worktree
+ * default gets ` --agent <tool>` instead (the caller decides, through
+ * `respondAgentFor`), since a bare `respond` goes to the default tool.
+ *
  * @param blockedBy - Which layer refused; omitted callers get the plain message
  * @param instanceId - The instance the refused request named, if any
+ * @param agent - The tool to name when no instance was named (`respondAgentFor`)
  */
-function promptWaitingMessage(worktreeId, blockedBy, instanceId) {
-    const target = instanceId ? ` --instance ${instanceId}` : '';
+function promptWaitingMessage(worktreeId, blockedBy, instanceId, agent) {
+    const target = (0, respond_target_1.respondTargetFlags)(instanceId, agent);
     const base = `${worktreeId} is waiting on a prompt. Sending now would type into the ` +
         `prompt's input line instead of reaching the agent, and would leave that ` +
         `text in place for the next answer. Answer the prompt first: ` +

package/dist/server/src/lib/session/respond-target.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Where the `respond` a server-side guidance sentence names has to go
+ * (Issue #4049).
+ *
+ * #4031 gave the PROMPT_WAITING refusal and the structured-dialog question a
+ * ` --instance <id>` when the request named an instance. A request that named
+ * only a tool (`send … --agent codex`) still got a bare `commandmate respond
+ * <id> <answer>`, and the CLI resolves a bare `respond` to the worktree's
+ * default tool — so the answer could reach a different agent than the one that
+ * is waiting.
+ *
+ * Type-only imports and string building, like `structured-prompt`, so the
+ * client bundle that reads that module can read this one too.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.respondTargetFlags = respondTargetFlags;
+exports.respondAgentFor = respondAgentFor;
+exports.commandCodePlanReviewSendMessage = commandCodePlanReviewSendMessage;
+/**
+ * The flags that aim a `respond` (or `send`) at the waiting session, by the
+ * CLI's own order (`targetFlags` in `src/cli/utils/follow-up-command.ts`): an
+ * instance first, else a tool, else nothing — the sentence as it was before.
+ *
+ * @param instanceId - The instance the request named, if any
+ * @param agent - The tool to name when no instance was named (see {@link respondAgentFor})
+ */
+function respondTargetFlags(instanceId, agent) {
+    if (instanceId)
+        return ` --instance ${instanceId}`;
+    if (agent)
+        return ` --agent ${agent}`;
+    return '';
+}
+/**
+ * The tool a guidance `respond` must name, or undefined when a bare one already
+ * reaches the waiting session.
+ *
+ * Only a request that named a tool explicitly and no instance gets one, and
+ * only when that tool is not what an unqualified request resolves to (the
+ * worktree default): `--agent claude` on a claude worktree, and a request that
+ * named nothing, keep the sentence they had (#4031's "primary and default are
+ * unchanged").
+ *
+ * @param requestedCliTool - The tool the request named explicitly, if any
+ * @param instanceId - The instance the request named, if any
+ * @param unqualifiedCliTool - The tool a request naming nothing resolves to
+ */
+function respondAgentFor(requestedCliTool, instanceId, unqualifiedCliTool) {
+    if (instanceId || !requestedCliTool)
+        return undefined;
+    return requestedCliTool === unqualifiedCliTool ? undefined : requestedCliTool;
+}
+/**
+ * Why `send` stops at the plan review overlay (Issue #3125).
+ *
+ * The overlay replaces the composer until a human decides, so waiting for the
+ * composer only ran out the clock (`prompt not ready` after the full timeout).
+ * Its comments, Submit review, approval and cancel go through `respond`.
+ *
+ * Issue #4049: a function, not a constant. The constant named a
+ * `<worktree-id>` placeholder and no instance, so on `command-code-2` the
+ * `respond` it showed went to the primary instance. The primary instance
+ * (no id, or the tool's own id — #868) gets no `--instance`.
+ *
+ * Issue #4063: and the tool, by {@link respondTargetFlags}' rule, when the
+ * request named Command Code on a worktree whose default is another tool
+ * ({@link respondAgentFor}). `CommandCodeTool.sendMessage` does not know the
+ * request, so the routes (send, terminal) rebuild the sentence with the `agent`
+ * they resolved; the tool's own throw leaves it out. Kept here, with no import
+ * beyond types, so those routes do not load the tool module.
+ *
+ * @param worktreeId - The worktree whose session is showing the review
+ * @param instanceId - The instance the send was for, if any
+ * @param agent - The tool the `respond` must name when no instance is (see `respondAgentFor`)
+ */
+function commandCodePlanReviewSendMessage(worktreeId, instanceId, agent) {
+    const target = respondTargetFlags(instanceId && instanceId !== 'command-code' ? instanceId : undefined, agent);
+    return ('Command Code is showing a plan review (REVIEW), which takes review comments, not messages. ' +
+        `Comment with \`commandmate respond ${worktreeId} "<text>"${target}\`, then \`--plan-review submit\` (ctrl+r), ` +
+        '`--plan-review approve` (ctrl+a) or `--plan-review cancel` (esc).');
+}