commandmate 0.49.2 → 0.49.3

package/dist/cli/utils/api-client.js

@@ -9,14 +9,10 @@
  * - ApiClient: HTTP get/post with base URL and auth headers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeadlineExceededError = exports.ApiError = exports.ApiClient = exports.FOREIGN_SESSION_ERROR_CODE = exports.MAX_STOP_PATTERN_LENGTH = void 0;
+exports.ApiClient = exports.MAX_STOP_PATTERN_LENGTH = exports.rethrowIfDeadlineExceeded = exports.isDeadlineExceeded = exports.DeadlineExceededError = exports.handleApiError = exports.foreignSessionMessage = exports.FOREIGN_SESSION_ERROR_CODE = exports.ApiError = void 0;
 exports.isValidWorktreeId = isValidWorktreeId;
 exports.isValidInstanceId = isValidInstanceId;
 exports.resolveAuthToken = resolveAuthToken;
-exports.foreignSessionMessage = foreignSessionMessage;
-exports.handleApiError = handleApiError;
-exports.isDeadlineExceeded = isDeadlineExceeded;
-exports.rethrowIfDeadlineExceeded = rethrowIfDeadlineExceeded;
 exports.assertResponseShape = assertResponseShape;
 exports.fetchDaemonVersion = fetchDaemonVersion;
 exports.warnIfVersionSkew = warnIfVersionSkew;
@@ -24,6 +20,17 @@ const types_1 = require("../types");
 const package_info_1 = require("./package-info");
 const uat_isolation_1 = require("../../config/uat-isolation");
 const server_url_1 = require("./server-url");
+const api_client_errors_1 = require("./api-client-errors");
+const api_client_deadline_1 = require("./api-client-deadline");
+var api_client_errors_2 = require("./api-client-errors");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return api_client_errors_2.ApiError; } });
+Object.defineProperty(exports, "FOREIGN_SESSION_ERROR_CODE", { enumerable: true, get: function () { return api_client_errors_2.FOREIGN_SESSION_ERROR_CODE; } });
+Object.defineProperty(exports, "foreignSessionMessage", { enumerable: true, get: function () { return api_client_errors_2.foreignSessionMessage; } });
+Object.defineProperty(exports, "handleApiError", { enumerable: true, get: function () { return api_client_errors_2.handleApiError; } });
+var api_client_deadline_2 = require("./api-client-deadline");
+Object.defineProperty(exports, "DeadlineExceededError", { enumerable: true, get: function () { return api_client_deadline_2.DeadlineExceededError; } });
+Object.defineProperty(exports, "isDeadlineExceeded", { enumerable: true, get: function () { return api_client_deadline_2.isDeadlineExceeded; } });
+Object.defineProperty(exports, "rethrowIfDeadlineExceeded", { enumerable: true, get: function () { return api_client_deadline_2.rethrowIfDeadlineExceeded; } });
 /** Maximum stop-pattern length [SEC4-06] */
 exports.MAX_STOP_PATTERN_LENGTH = 500;
 /** Worktree ID validation pattern [SEC4-04] */
@@ -68,175 +75,6 @@ function resolveAuthToken(options) {
     }
     return process.env.CM_AUTH_TOKEN;
 }
-/**
- * The server's own explanation for a failure, when it sent one worth showing.
- *
- * Issue #1637: every 5xx used to be flattened into `Server error. Check server
- * logs for details.`, which is only useful to someone who has the server logs.
- * A cold-start `send` failed with an initialization timeout and told the
- * operator nothing but "go read the logs" — four orchestration runs in a row
- * then misdiagnosed it as a session-creation race and worked around it by
- * re-sending. Every route in this codebase already answers `{ error }`, so the
- * cause was always in the response body; nothing read it.
- *
- * Trimmed and length-capped because it is printed to a terminal, and an
- * unbounded server string is not something a CLI should paste verbatim.
- */
-const MAX_SERVER_ERROR_DETAIL = 2000;
-function serverErrorDetail(payload) {
-    const detail = typeof payload?.error === 'string' ? payload.error.trim() : '';
-    if (detail === '')
-        return undefined;
-    return detail.length > MAX_SERVER_ERROR_DETAIL
-        ? `${detail.slice(0, MAX_SERVER_ERROR_DETAIL)}…`
-        : detail;
-}
-/** Append `(server: <url>)` when the caller named one. */
-function withServerUrl(message, context) {
-    return context?.serverUrl ? `${message} (server: ${context.serverUrl})` : message;
-}
-/**
- * The `code` the server sends with the 409 for a tmux session another
- * CommandMate server created (Issue #2865). Spelled out rather than imported:
- * the server's constant lives next to the tmux gateway, which the CLI must not
- * load. `tests/unit/cli/utils/api-client-foreign-session-3334.test.ts` pins the
- * two to the same string.
- */
-exports.FOREIGN_SESSION_ERROR_CODE = 'session_owned_by_other_server';
-/**
- * Issue #3334: what the operator reads for that 409. It has to say three
- * things the status alone does not: the session is another CommandMate
- * server's, this command therefore did nothing to it, and where to go instead.
- */
-function foreignSessionMessage(payload) {
-    const name = typeof payload?.sessionName === 'string' && payload.sessionName !== ''
-        ? `"${payload.sessionName}" `
-        : '';
-    const where = typeof payload?.sessionPath === 'string' && payload.sessionPath !== ''
-        ? ` (it was started in ${payload.sessionPath})`
-        : '';
-    return (`The tmux session ${name}belongs to another CommandMate server${where}, ` +
-        'so nothing was sent to it, read from it or stopped. ' +
-        'Use the CommandMate server that started it, or stop that session there first.');
-}
-/**
- * Classify API errors into user-friendly messages and exit codes.
- * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
- *
- * @param error - Error object or unknown
- * @param status - HTTP status code if available
- * @param payload - Parsed error body, when the response carried one (Issue #1637).
- *   Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx
- *   messages below are already specific, and are pinned by tests as the CLI's
- *   own wording.
- * @param context - Which server answered, when the caller knows (Issue #2404).
- *   Read by the 404 branch only; the other messages do not send anyone looking
- *   in the wrong place.
- * @returns User-friendly error message and exit code
- */
-function handleApiError(error, status, payload, context) {
-    // HTTP status-based errors
-    if (status !== undefined) {
-        switch (status) {
-            case 400:
-                return {
-                    message: 'Bad request. Check your input parameters.',
-                    exitCode: types_1.ExitCode.CONFIG_ERROR,
-                };
-            case 401:
-            case 403:
-                // Issue #2489: the second sentence is the one that matters during a
-                // `commandmate remote` session. `remote` mints the token, hands its
-                // plaintext to the phone once through the pairing handoff and deletes
-                // it — so "set CM_AUTH_TOKEN" names a value the operator has no way to
-                // obtain, and following that advice is a dead end (#2489's report spent
-                // a session there). `--auth remote-only` is the exit: it leaves the
-                // loopback listener this client dials unauthenticated while the
-                // Provider's listener keeps demanding the token.
-                return {
-                    message: 'Authentication failed. Use --token <token> or set CM_AUTH_TOKEN environment variable. ' +
-                        'During a "commandmate remote" session the token is only ever shown to the paired phone — ' +
-                        'restart it with "commandmate remote --auth remote-only" to use the CLI from this machine without one.',
-                    exitCode: types_1.ExitCode.CONFIG_ERROR,
-                };
-            case 404:
-                // Issue #2404: the sentence stays, so everything matching on it keeps
-                // matching; the URL is appended because "check the worktree ID" is
-                // advice about the wrong thing whenever the id is fine and the SERVER
-                // is the one that is wrong.
-                return {
-                    message: withServerUrl('Resource not found. Check the worktree ID.', context),
-                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                };
-            case 409:
-                // Issue #3334: the one 409 every session route shares (#2865 / #3290).
-                // Without this it read "Unexpected HTTP status: 409", which does not say
-                // that nothing was done, nor why. Same exit code as that default branch,
-                // so a script branching on it sees no change. Every other 409 keeps the
-                // default wording below — the commands that own one (send's
-                // PROMPT_WAITING, verify's running run) already explain it themselves.
-                if (payload?.code === exports.FOREIGN_SESSION_ERROR_CODE) {
-                    return {
-                        message: foreignSessionMessage(payload),
-                        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                    };
-                }
-                return {
-                    message: `Unexpected HTTP status: ${status}`,
-                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                };
-            case 429:
-                return {
-                    message: 'Rate limited. Please retry after a moment.',
-                    exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-                };
-            case 500:
-            default:
-                if (status >= 500) {
-                    // Issue #1637: pass the server's own reason through. The prefix is
-                    // kept so "this came from the server, not from the CLI" survives, and
-                    // so does the log pointer when the body said nothing.
-                    const detail = serverErrorDetail(payload);
-                    return {
-                        message: detail
-                            ? `Server error: ${detail}`
-                            : 'Server error. Check server logs for details.',
-                        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                    };
-                }
-                return {
-                    message: `Unexpected HTTP status: ${status}`,
-                    exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-                };
-        }
-    }
-    // Network/connection errors
-    if (error instanceof Error) {
-        const msg = error.message || '';
-        if (msg.includes('ECONNREFUSED') || msg.includes('fetch failed')) {
-            return {
-                message: 'Server is not running. Start it with: commandmate start',
-                exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-            };
-        }
-        if (error.name === 'AbortError' || msg.includes('timeout') || msg.includes('Timeout')) {
-            return {
-                message: 'Server did not respond in time. Check server status.',
-                exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-            };
-        }
-        if (error.name === 'TypeError') {
-            return {
-                message: 'Network error. Check your connection and server status.',
-                exitCode: types_1.ExitCode.DEPENDENCY_ERROR,
-            };
-        }
-    }
-    return {
-        message: 'An unexpected error occurred.',
-        exitCode: types_1.ExitCode.UNEXPECTED_ERROR,
-    };
-}
 /**
  * Check if a URL points to a localhost address.
  */
@@ -270,7 +108,7 @@ class ApiClient {
         // Issue #3360: in UAT isolation the default port 3000 is the user's production server,
         // so a client that was not told where to go must not go anywhere.
         if (!options?.baseUrl && (0, uat_isolation_1.isUatIsolationEnabled)() && !process.env.CM_PORT) {
-            throw new ApiError(`${uat_isolation_1.UAT_ISOLATION_ENV_VAR}=${process.env[uat_isolation_1.UAT_ISOLATION_ENV_VAR]} requires CM_PORT: refusing to fall back to the default port 3000.`, types_1.ExitCode.CONFIG_ERROR);
+            throw new api_client_errors_1.ApiError(`${uat_isolation_1.UAT_ISOLATION_ENV_VAR}=${process.env[uat_isolation_1.UAT_ISOLATION_ENV_VAR]} requires CM_PORT: refusing to fall back to the default port 3000.`, types_1.ExitCode.CONFIG_ERROR);
         }
         this.baseUrl = options?.baseUrl || (0, server_url_1.resolveServerEndpoint)((0, server_url_1.loadClientEnv)()).url;
         this.token = resolveAuthToken(options);
@@ -409,21 +247,21 @@ class ApiClient {
                 // Issue #1637: read the body first — handleApiError needs it to surface
                 // the server's reason for a 5xx instead of "check the logs".
                 const payload = await bounded(deadline, readErrorPayload(response));
-                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
-                throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+                const errResult = (0, api_client_errors_1.handleApiError)(null, response.status, payload, { serverUrl: this.baseUrl });
+                throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode, response.status, payload);
             }
             return (await bounded(deadline, response.json()));
         }
         catch (error) {
             if (deadline) {
                 const classified = deadline.classify(error);
-                if (classified instanceof DeadlineExceededError)
+                if (classified instanceof api_client_deadline_1.DeadlineExceededError)
                     throw classified;
             }
-            if (error instanceof ApiError)
+            if (error instanceof api_client_errors_1.ApiError)
                 throw error;
-            const errResult = handleApiError(error);
-            throw new ApiError(errResult.message, errResult.exitCode);
+            const errResult = (0, api_client_errors_1.handleApiError)(error);
+            throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode);
         }
         finally {
             deadline?.release();
@@ -459,8 +297,8 @@ async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
             // Issue #1637: read the body first — handleApiError needs it to surface
             // the server's reason for a 5xx instead of "check the logs".
             const payload = await bounded(deadline, readErrorPayload(response));
-            const errResult = handleApiError(null, response.status, payload, { serverUrl: baseUrl });
-            throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+            const errResult = (0, api_client_errors_1.handleApiError)(null, response.status, payload, { serverUrl: baseUrl });
+            throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode, response.status, payload);
         }
         // Handle 204 No Content
         const text = await bounded(deadline, response.text());
@@ -471,13 +309,13 @@ async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
     catch (error) {
         if (deadline) {
             const classified = deadline.classify(error);
-            if (classified instanceof DeadlineExceededError)
+            if (classified instanceof api_client_deadline_1.DeadlineExceededError)
                 throw classified;
         }
-        if (error instanceof ApiError)
+        if (error instanceof api_client_errors_1.ApiError)
             throw error;
-        const errResult = handleApiError(error);
-        throw new ApiError(errResult.message, errResult.exitCode, undefined, undefined, error);
+        const errResult = (0, api_client_errors_1.handleApiError)(error);
+        throw new api_client_errors_1.ApiError(errResult.message, errResult.exitCode, undefined, undefined, error);
     }
     finally {
         deadline?.release();
@@ -509,76 +347,11 @@ async function readErrorPayload(response) {
         return undefined;
     }
 }
-/**
- * API Error with exit code for CLI process.exit()
- */
-class ApiError extends Error {
-    exitCode;
-    statusCode;
-    payload;
-    transportError;
-    constructor(message, exitCode, statusCode, 
-    /** Typed error body, when the server sent one (Issue #1237). */
-    payload, 
-    /**
-     * The error `fetch` threw, when no HTTP response came back (Issue #3756):
-     * the strict `respond` tells "never connected" (nothing can have been sent)
-     * from "the connection broke" by its `cause.code`.
-     */
-    transportError) {
-        super(message);
-        this.exitCode = exitCode;
-        this.statusCode = statusCode;
-        this.payload = payload;
-        this.transportError = transportError;
-        this.name = 'ApiError';
-    }
-    /** Stable machine code the server assigned to this failure, if any. */
-    get apiCode() {
-        return this.payload?.code;
-    }
-}
-exports.ApiError = ApiError;
 // =============================================================================
 // Command deadline (Issue #3983)
 // =============================================================================
 /** The longest delay `setTimeout` honours (2^31-1 ms, ~24.8 days). */
 const MAX_TIMER_MS = 2 ** 31 - 1;
-/**
- * A request ended by the deadline of a client from {@link ApiClient.withDeadline}
- * (Issue #3983).
- *
- * An `ApiError` with exit 124 so that the commands' own error handling reports
- * it as the timeout it is, and a class of its own so that a catch which turns
- * failures into a degraded result ("verification resolves its own task", "use
- * the selector as an instance id") can tell it apart and rethrow it — see
- * {@link isDeadlineExceeded}. Wrapped into another `ApiError`, it travels as
- * that error's `transportError`.
- */
-class DeadlineExceededError extends ApiError {
-    constructor(serverUrl) {
-        super(withServerUrl('--timeout reached before the server answered', { serverUrl }), types_1.WaitExitCode.TIMEOUT);
-        this.name = 'DeadlineExceededError';
-    }
-}
-exports.DeadlineExceededError = DeadlineExceededError;
-/**
- * Whether `error` is — or wraps — a request ended by a command deadline
- * (Issue #3983). The catches that degrade on failure ask this first and
- * rethrow: a deadline is the command's answer, not a reason to carry on.
- */
-function isDeadlineExceeded(error) {
-    if (error instanceof DeadlineExceededError)
-        return true;
-    if (error instanceof ApiError && error.transportError instanceof DeadlineExceededError)
-        return true;
-    return error instanceof Error && error.cause instanceof DeadlineExceededError;
-}
-/** Rethrow `error` when it is a command deadline; otherwise return (Issue #3983). */
-function rethrowIfDeadlineExceeded(error) {
-    if (isDeadlineExceeded(error))
-        throw error;
-}
 /**
  * Arm the deadline of one request. Its signal goes to `fetch` (which then also
  * aborts the body stream), and every await of the request is raced against it
@@ -592,7 +365,7 @@ function startRequestDeadline(deadlineAt, serverUrl, callerSignal) {
     const controller = new AbortController();
     const fire = () => {
         if (!controller.signal.aborted)
-            controller.abort(new DeadlineExceededError(serverUrl));
+            controller.abort(new api_client_deadline_1.DeadlineExceededError(serverUrl));
     };
     const remaining = deadlineAt - Date.now();
     let timer;
@@ -605,9 +378,9 @@ function startRequestDeadline(deadlineAt, serverUrl, callerSignal) {
         timer.unref?.();
     }
     const signal = callerSignal ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
-    const deadlineError = () => controller.signal.reason instanceof DeadlineExceededError
+    const deadlineError = () => controller.signal.reason instanceof api_client_deadline_1.DeadlineExceededError
         ? controller.signal.reason
-        : new DeadlineExceededError(serverUrl);
+        : new api_client_deadline_1.DeadlineExceededError(serverUrl);
     return {
         signal,
         run(promise) {
@@ -686,12 +459,12 @@ function versionSkewMessage(detail) {
  */
 function assertResponseShape(value, fields, context) {
     if (value === null || typeof value !== 'object') {
-        throw new ApiError(versionSkewMessage(`${context}: expected an object from the server`), types_1.ExitCode.UNEXPECTED_ERROR);
+        throw new api_client_errors_1.ApiError(versionSkewMessage(`${context}: expected an object from the server`), types_1.ExitCode.UNEXPECTED_ERROR);
     }
     const record = value;
     for (const field of fields) {
         if (!(field in record)) {
-            throw new ApiError(versionSkewMessage(`${context}: the server response is missing the "${field}" field`), types_1.ExitCode.UNEXPECTED_ERROR);
+            throw new api_client_errors_1.ApiError(versionSkewMessage(`${context}: the server response is missing the "${field}" field`), types_1.ExitCode.UNEXPECTED_ERROR);
         }
     }
     return value;

package/dist/lib/cli-tools/types.d.ts

@@ -408,6 +408,12 @@ export interface IImageCapableCLITool extends ICLITool {
      * @param instanceId - Agent instance ID (Issue #868). Defaults to the primary instance.
      */
     sendMessageWithImage(worktreeId: string, message: string, imagePath: string, instanceId?: string): Promise<void>;
+    /**
+     * The body {@link sendMessageWithImage} types for `message` and `imagePath`
+     * (Issue #4048), so the send's record names the attempt by what reached the
+     * composer. Omitted when it types `message` unchanged.
+     */
+    imageMessageBody?(message: string, imagePath: string): string;
 }
 /**
  * Type guard to check if a CLI tool supports image sending

package/dist/lib/cli-tools/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/cli-tools/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/cli-tools/types.ts"],"names":[],"mappings":"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"}

package/dist/server/locales/en/worktree.json

@@ -1286,6 +1286,13 @@
         "stripAwaitingMany": "Waiting for {count} delegated replies.",
         "stripPrompt": "{alias} is waiting for a confirmation.",
         "stripOwed": "Owed to {alias}: this session's reply is delivered when the turn ends.",
+        "badgeHeld": "Delivery from {alias} unconfirmed",
+        "badgeHeldMany": "Unconfirmed deliveries ({count})",
+        "heldTitle": "Whether a relay delivery to this session (a reply, a confirmation notice or an expiry notice) arrived is not known. It is not resent automatically. Check this pane, then settle it with commandmate relays resolve.",
+        "stripHeld": "Delivery from {alias} unconfirmed: check this pane, then settle it with relays resolve.",
+        "stripHeldMany": "{count} unconfirmed deliveries: check this pane, then settle them with relays resolve.",
+        "unplacedHeldHeading": "Unconfirmed deliveries to sessions not in the roster",
+        "unplacedHeldLine": "{requester} ← {alias} (relay {relayId})",
         "historyBadge": "relay",
         "historyBadgeTitle": "Delivered by another agent session (Issue #2377 relay).",
         "historyCount": "{count} relayed message(s) in view"

package/dist/server/locales/ja/worktree.json

@@ -1286,6 +1286,13 @@
         "stripAwaitingMany": "返信待ち {count} 件",
         "stripPrompt": "{alias} が確認待ち",
         "stripOwed": "{alias} へ返信予定: ターン完了時に届きます",
+        "badgeHeld": "{alias} からの配送が未確認",
+        "badgeHeldMany": "配送未確認 {count} 件",
+        "heldTitle": "このセッションへの relay の配送（返信・確認待ちの通知・期限切れの通知）が届いたか分かりません。自動では再送しません。この画面を確かめてから commandmate relays resolve で片付けてください。",
+        "stripHeld": "{alias} からの配送が未確認: 画面を確かめて relays resolve で片付けてください",
+        "stripHeldMany": "配送未確認 {count} 件: 画面を確かめて relays resolve で片付けてください",
+        "unplacedHeldHeading": "名簿に無いセッションへの配送未確認",
+        "unplacedHeldLine": "{requester} ← {alias}（relay {relayId}）",
         "historyBadge": "relay",
         "historyBadgeTitle": "別のエージェントセッションから届いたメッセージです（Issue #2377 relay）。",
         "historyCount": "表示範囲に relay メッセージが {count} 件"

package/dist/server/src/lib/cli-tools/claude.js

@@ -97,9 +97,15 @@ class ClaudeTool extends base_1.BaseCLITool {
      * @param instanceId - Optional agent instance ID (defaults to primary)
      */
     async sendMessageWithImage(worktreeId, message, imagePath, instanceId) {
+        await this.sendMessage(worktreeId, this.imageMessageBody(message, imagePath), instanceId);
+    }
+    /**
+     * The body {@link sendMessageWithImage} types: the message with the image's
+     * markdown reference appended (Issue #4048: the send's record digests it).
+     */
+    imageMessageBody(message, imagePath) {
         const imageMarkdown = `\n![](${imagePath})`;
-        const fullMessage = message ? `${message}${imageMarkdown}` : imageMarkdown;
-        await this.sendMessage(worktreeId, fullMessage, instanceId);
+        return message ? `${message}${imageMarkdown}` : imageMarkdown;
     }
     /**
      * Kill Claude session

package/dist/server/src/lib/cli-tools/command-code.js

@@ -36,7 +36,7 @@
  * only the correlation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CommandCodeTool = exports.COMMAND_CODE_PLAN_REVIEW_SEND_MESSAGE = exports.COMMAND_CODE_STARTING_WINDOW_MS = exports.COMMAND_CODE_EXIT_COMMAND = exports.COMMAND_CODE_LAUNCH_FLAGS = exports.COMMAND_CODE_COMMAND = void 0;
+exports.CommandCodeTool = exports.commandCodePlanReviewSendMessage = exports.COMMAND_CODE_STARTING_WINDOW_MS = exports.COMMAND_CODE_EXIT_COMMAND = exports.COMMAND_CODE_LAUNCH_FLAGS = exports.COMMAND_CODE_COMMAND = void 0;
 exports.buildCommandCodeLaunchCommand = buildCommandCodeLaunchCommand;
 exports.isCommandCodeReady = isCommandCodeReady;
 const base_1 = require("./base");
@@ -48,6 +48,8 @@ const cli_patterns_1 = require("../detection/cli-patterns");
 const errors_1 = require("../../lib/errors");
 const logger_1 = require("../../lib/logger");
 const send_attempt_types_1 = require("../../lib/session/send-attempt-types");
+const respond_target_1 = require("../../lib/session/respond-target");
+Object.defineProperty(exports, "commandCodePlanReviewSendMessage", { enumerable: true, get: function () { return respond_target_1.commandCodePlanReviewSendMessage; } });
 const tool_id_1 = require("../../lib/hooks/sources/command-code/tool-id");
 const agent_session_lifecycle_1 = require("../../lib/session/agent-session-lifecycle");
 const cli_tool_timing_config_1 = require("../../config/cli-tool-timing-config");
@@ -146,16 +148,6 @@ function isCommandCodeReady(rawOutput) {
         return false;
     return !cli_patterns_1.COMMAND_CODE_THINKING_PATTERN.test((0, cli_patterns_1.stripAnsi)(rawOutput));
 }
-/**
- * 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`.
- */
-exports.COMMAND_CODE_PLAN_REVIEW_SEND_MESSAGE = 'Command Code is showing a plan review (REVIEW), which takes review comments, not messages. ' +
-    'Comment with `commandmate respond <worktree-id> "<text>"`, then `--plan-review submit` (ctrl+r), ' +
-    '`--plan-review approve` (ctrl+a) or `--plan-review cancel` (esc).';
 /**
  * Command Code CLI tool implementation.
  * Manages `commandcode` sessions using tmux.
@@ -295,11 +287,11 @@ class CommandCodeTool extends base_1.BaseCLITool {
      *
      * @throws SessionStartTimeoutError when a just-launched session's composer
      *   has still not appeared
-     * @throws Error ({@link COMMAND_CODE_PLAN_REVIEW_SEND_MESSAGE}) at once when
+     * @throws Error ({@link commandCodePlanReviewSendMessage}) at once when
      *   the plan review overlay is on screen (Issue #3125)
      * @throws Error when the composer is not detected within the timeout
      */
-    async waitForPrompt(sessionName) {
+    async waitForPrompt(sessionName, worktreeId, instanceId) {
         const startTime = Date.now();
         const pollInterval = 500;
         let planReviewPolls = 0;
@@ -323,7 +315,7 @@ class CommandCodeTool extends base_1.BaseCLITool {
             planReviewPolls = planReviewUp ? planReviewPolls + 1 : 0;
             if (planReviewPolls >= 2) {
                 logger.info('command-code-plan-review-blocks-send', { sessionName });
-                throw Object.assign(new Error(exports.COMMAND_CODE_PLAN_REVIEW_SEND_MESSAGE), {
+                throw Object.assign(new Error((0, respond_target_1.commandCodePlanReviewSendMessage)(worktreeId, instanceId)), {
                     code: send_attempt_types_1.PLAN_REVIEW_SEND_REFUSED_CODE,
                 });
             }
@@ -355,7 +347,7 @@ class CommandCodeTool extends base_1.BaseCLITool {
         // pane when the tool is gone; costs one `capture-pane` when it is not.
         await this.requireSession('Command Code', worktreeId, instanceId, { relaunch: true });
         try {
-            await this.waitForPrompt(sessionName);
+            await this.waitForPrompt(sessionName, worktreeId, instanceId);
             // Issue #1471: body/Enter separation + read-back submit verification.
             await (0, submit_verified_sender_1.sendMessageWithSubmitVerification)({
                 sessionName,