commandmate 0.49.1 → 0.49.3

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

@@ -9,12 +9,10 @@
  * - ApiClient: HTTP get/post with base URL and auth headers
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.assertResponseShape = assertResponseShape;
 exports.fetchDaemonVersion = fetchDaemonVersion;
 exports.warnIfVersionSkew = warnIfVersionSkew;
@@ -22,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] */
@@ -66,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.
  */
@@ -255,6 +95,8 @@ function isLocalhost(url) {
 class ApiClient {
     baseUrl;
     token;
+    /** Epoch ms after which every request of this client fails (Issue #3983). */
+    deadlineAt;
     constructor(options) {
         // Issue #1743: resolve through loadClientEnv() rather than `process.env.CM_PORT || '3000'`.
         // Reading process.env alone ignored ~/.commandmate/.env, so with two servers running,
@@ -266,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);
@@ -289,6 +131,51 @@ class ApiClient {
     get serverUrl() {
         return this.baseUrl;
     }
+    /**
+     * This client with every request bounded by `deadlineAt` (Issue #3983).
+     *
+     * `wait` / `ask` / `verify` take `--timeout` as the deadline of the whole
+     * command, but only the poll's own reads were bounded by it: a task-ledger
+     * read, an `--instance` resolution or a capability probe before the poll had
+     * no deadline at all, so a server that stopped answering held the command for
+     * as long as undici's own timeouts (minutes) and then, swallowed into a
+     * degraded path, kept it going. The derived client carries one deadline for
+     * every method (`get` / `post` / `patch` / `rawGet`), and a request it ends
+     * fails with {@link DeadlineExceededError} — exit 124 — which the
+     * degrade-on-failure catches rethrow ({@link isDeadlineExceeded}).
+     *
+     * One request lasts until its body has been read (`json()` / `text()`), the
+     * body of a {@link rawGet} response included: a server that sends headers and
+     * then stalls the body is not an answer.
+     *
+     * @param deadlineAt - Epoch ms; undefined returns this client unchanged
+     * @returns A client sharing this one's server and token
+     */
+    withDeadline(deadlineAt) {
+        if (deadlineAt === undefined || !Number.isFinite(deadlineAt))
+            return this;
+        // Not `new ApiClient(...)`: the constructor re-resolves the endpoint and
+        // re-prints the --token warning, and the derived client must dial the very
+        // server this one does.
+        const derived = Object.create(Object.getPrototypeOf(this));
+        derived.baseUrl = this.baseUrl;
+        derived.token = this.token;
+        derived.deadlineAt = deadlineAt;
+        return derived;
+    }
+    /** The deadline this client carries, if any (Issue #3983). */
+    get deadline() {
+        return this.deadlineAt;
+    }
+    /**
+     * The bound of one request: a signal that fires at the deadline (combined
+     * with the caller's own, when it gave one), or null without a deadline.
+     */
+    startDeadline(callerSignal) {
+        if (this.deadlineAt === undefined)
+            return null;
+        return startRequestDeadline(this.deadlineAt, this.baseUrl, callerSignal);
+    }
     getHeaders() {
         const headers = {
             'Content-Type': 'application/json',
@@ -314,11 +201,28 @@ class ApiClient {
      * @returns The raw Response, whatever its status
      */
     async rawGet(path, init) {
-        return fetch(`${this.baseUrl}${path}`, {
-            method: 'GET',
-            headers: { ...this.getHeaders(), ...(init?.headers ?? {}) },
-            redirect: 'manual',
-        });
+        const deadline = this.startDeadline();
+        if (!deadline) {
+            return fetch(`${this.baseUrl}${path}`, {
+                method: 'GET',
+                headers: { ...this.getHeaders(), ...(init?.headers ?? {}) },
+                redirect: 'manual',
+            });
+        }
+        // Issue #3983: the caller reads the body, so the deadline is not released
+        // here — it stays armed (unref'd) for the body read, which it also bounds.
+        try {
+            const response = await deadline.run(fetch(`${this.baseUrl}${path}`, {
+                method: 'GET',
+                headers: { ...this.getHeaders(), ...(init?.headers ?? {}) },
+                redirect: 'manual',
+                signal: deadline.signal,
+            }));
+            return boundBodyReads(response, deadline);
+        }
+        catch (error) {
+            throw deadline.classify(error);
+        }
     }
     /**
      * HTTP GET request
@@ -330,26 +234,37 @@ class ApiClient {
      * before (no `signal` key on the fetch init).
      */
     async get(path, init) {
+        // Issue #3983: a client with a deadline bounds the request and its body.
+        const deadline = this.startDeadline(init?.signal);
+        const signal = deadline ? deadline.signal : init?.signal;
         try {
-            const response = await fetch(`${this.baseUrl}${path}`, {
+            const response = await bounded(deadline, fetch(`${this.baseUrl}${path}`, {
                 method: 'GET',
                 headers: this.getHeaders(),
-                ...(init?.signal ? { signal: init.signal } : {}),
-            });
+                ...(signal ? { signal } : {}),
+            }));
             if (!response.ok) {
                 // 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 readErrorPayload(response);
-                const errResult = handleApiError(null, response.status, payload, { serverUrl: this.baseUrl });
-                throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+                const payload = await bounded(deadline, readErrorPayload(response));
+                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 response.json());
+            return (await bounded(deadline, response.json()));
         }
         catch (error) {
-            if (error instanceof ApiError)
+            if (deadline) {
+                const classified = deadline.classify(error);
+                if (classified instanceof api_client_deadline_1.DeadlineExceededError)
+                    throw classified;
+            }
+            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();
         }
     }
     /**
@@ -357,7 +272,7 @@ class ApiClient {
      * [DR1-05] Generic type parameter specified at call site
      */
     async post(path, body) {
-        return sendWithBody(this.baseUrl, 'POST', this.getHeaders(), path, body);
+        return sendWithBody(this.baseUrl, 'POST', this.getHeaders(), path, body, this.startDeadline());
     }
     /**
      * HTTP PATCH request (Issue #1000: agent-instance roster mutations via
@@ -365,36 +280,45 @@ class ApiClient {
      * [DR1-05] Generic type parameter specified at call site
      */
     async patch(path, body) {
-        return sendWithBody(this.baseUrl, 'PATCH', this.getHeaders(), path, body);
+        return sendWithBody(this.baseUrl, 'PATCH', this.getHeaders(), path, body, this.startDeadline());
     }
 }
 exports.ApiClient = ApiClient;
 /** POST / PATCH share everything but the method; an empty body (204) is `undefined`. */
-async function sendWithBody(baseUrl, method, headers, path, body) {
+async function sendWithBody(baseUrl, method, headers, path, body, deadline) {
     try {
-        const response = await fetch(`${baseUrl}${path}`, {
+        const response = await bounded(deadline, fetch(`${baseUrl}${path}`, {
             method,
             headers,
             body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
+            ...(deadline ? { signal: deadline.signal } : {}),
+        }));
         if (!response.ok) {
             // 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 readErrorPayload(response);
-            const errResult = handleApiError(null, response.status, payload, { serverUrl: baseUrl });
-            throw new ApiError(errResult.message, errResult.exitCode, response.status, payload);
+            const payload = await bounded(deadline, readErrorPayload(response));
+            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 response.text();
+        const text = await bounded(deadline, response.text());
         if (!text)
             return undefined;
         return JSON.parse(text);
     }
     catch (error) {
-        if (error instanceof ApiError)
+        if (deadline) {
+            const classified = deadline.classify(error);
+            if (classified instanceof api_client_deadline_1.DeadlineExceededError)
+                throw classified;
+        }
+        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();
     }
 }
 /**
@@ -423,36 +347,87 @@ async function readErrorPayload(response) {
         return undefined;
     }
 }
+// =============================================================================
+// Command deadline (Issue #3983)
+// =============================================================================
+/** The longest delay `setTimeout` honours (2^31-1 ms, ~24.8 days). */
+const MAX_TIMER_MS = 2 ** 31 - 1;
 /**
- * API Error with exit code for CLI process.exit()
+ * 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
+ * as well — so a stalled body or a transport that ignores the signal still ends
+ * on time. Past the deadline the signal is already aborted and no request is
+ * sent; started exactly at it, the request gets the current tick (a read at the
+ * deadline may still bring the answer `verify` reports, Issue #1544). Beyond
+ * what a timer can hold the request is left unbounded.
  */
-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';
+function startRequestDeadline(deadlineAt, serverUrl, callerSignal) {
+    const controller = new AbortController();
+    const fire = () => {
+        if (!controller.signal.aborted)
+            controller.abort(new api_client_deadline_1.DeadlineExceededError(serverUrl));
+    };
+    const remaining = deadlineAt - Date.now();
+    let timer;
+    if (remaining < 0) {
+        fire();
     }
-    /** Stable machine code the server assigned to this failure, if any. */
-    get apiCode() {
-        return this.payload?.code;
+    else if (remaining <= MAX_TIMER_MS) {
+        timer = setTimeout(fire, remaining);
+        // A command that is done must not stay alive for a deadline it no longer needs.
+        timer.unref?.();
     }
+    const signal = callerSignal ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
+    const deadlineError = () => controller.signal.reason instanceof api_client_deadline_1.DeadlineExceededError
+        ? controller.signal.reason
+        : new api_client_deadline_1.DeadlineExceededError(serverUrl);
+    return {
+        signal,
+        run(promise) {
+            if (controller.signal.aborted) {
+                promise.catch(() => { });
+                return Promise.reject(deadlineError());
+            }
+            return new Promise((resolve, reject) => {
+                const onAbort = () => reject(deadlineError());
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                promise.then((value) => {
+                    controller.signal.removeEventListener('abort', onAbort);
+                    resolve(value);
+                }, (error) => {
+                    controller.signal.removeEventListener('abort', onAbort);
+                    reject(error);
+                });
+            });
+        },
+        classify(error) {
+            return controller.signal.aborted ? deadlineError() : error;
+        },
+        release() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        },
+    };
+}
+/** `promise` raced against `deadline`, or `promise` itself without one. */
+function bounded(deadline, promise) {
+    return deadline ? deadline.run(promise) : promise;
+}
+/**
+ * A {@link ApiClient.rawGet} response whose body reads are raced against the
+ * request's deadline (Issue #3983). The caller reads the body, so the bound has
+ * to travel with the response.
+ */
+function boundBodyReads(response, deadline) {
+    const read = (method) => () => deadline.run(method()).catch((error) => {
+        throw deadline.classify(error);
+    });
+    const json = response.json.bind(response);
+    const text = response.text.bind(response);
+    Object.defineProperty(response, 'json', { value: read(json), configurable: true });
+    Object.defineProperty(response, 'text', { value: read(text), configurable: true });
+    return response;
 }
-exports.ApiError = ApiError;
 // =============================================================================
 // Response shape validation & version-skew detection (Issue #1357)
 // =============================================================================
@@ -484,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/cli/utils/follow-up-command.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The next command a CLI message tells the operator to run, aimed at the
+ * target the command actually addressed (Issue #3982).
+ *
+ * Each hint used to append ` --instance ${options.instance}` itself: the string
+ * the user typed (an alias reached `capture` unresolved), and nothing at all for
+ * `--agent` (so the hint read the worktree default's pane). One of them was
+ * fixed in #3975 and the others were not. These builders take the RESOLVED
+ * target — {@link CommandTarget}, what `resolveCommandTarget` returns — so the
+ * raw option cannot be passed where the hint's target belongs.
+ */
+import type { CommandTarget } from '../commands/command-target';
+/**
+ * The `capture` flags that read a dialog: the pane itself (the stored reply is
+ * not what is on screen), and enough of it to hold the dialog and its numbers.
+ */
+export declare const DIALOG_CAPTURE_FLAGS = "--pane --tail 40";
+/**
+ * ` --instance <id>` for a resolved instance, else ` --agent <tool>` when one
+ * was named, else nothing — a command that named no target keeps naming none.
+ */
+export declare function targetFlags(target: CommandTarget): string;
+/**
+ * `commandmate <verb> <worktree-id>[ <args>]<target flags>[ <trailing>]`.
+ *
+ * @param args - What follows the worktree id, e.g. `<number>` or `"<text>"`
+ * @param trailing - Flags that follow the target, e.g. `--pane --tail 40`
+ */
+export declare function followUpCommand(verb: string, worktreeId: string, target: CommandTarget, args?: string, trailing?: string): string;
+/** The `capture` that shows the target's dialog as it is on screen. */
+export declare function dialogCaptureCommand(worktreeId: string, target: CommandTarget): string;
+/**
+ * `commandmate capture <id>[ target] --pane`: the pane a message went to, to
+ * look at before a resend (Issue #3992). Without a target (a caller that has
+ * none to give) it names none.
+ */
+export declare function paneCaptureCommand(worktreeId: string, target: CommandTarget | undefined): string;
+//# sourceMappingURL=follow-up-command.d.ts.map

package/dist/cli/utils/follow-up-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow-up-command.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/follow-up-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAIzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAER;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,CAEtF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAIhG"}

package/dist/cli/utils/follow-up-command.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * The next command a CLI message tells the operator to run, aimed at the
+ * target the command actually addressed (Issue #3982).
+ *
+ * Each hint used to append ` --instance ${options.instance}` itself: the string
+ * the user typed (an alias reached `capture` unresolved), and nothing at all for
+ * `--agent` (so the hint read the worktree default's pane). One of them was
+ * fixed in #3975 and the others were not. These builders take the RESOLVED
+ * target — {@link CommandTarget}, what `resolveCommandTarget` returns — so the
+ * raw option cannot be passed where the hint's target belongs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIALOG_CAPTURE_FLAGS = void 0;
+exports.targetFlags = targetFlags;
+exports.followUpCommand = followUpCommand;
+exports.dialogCaptureCommand = dialogCaptureCommand;
+exports.paneCaptureCommand = paneCaptureCommand;
+/**
+ * The `capture` flags that read a dialog: the pane itself (the stored reply is
+ * not what is on screen), and enough of it to hold the dialog and its numbers.
+ */
+exports.DIALOG_CAPTURE_FLAGS = '--pane --tail 40';
+/**
+ * ` --instance <id>` for a resolved instance, else ` --agent <tool>` when one
+ * was named, else nothing — a command that named no target keeps naming none.
+ */
+function targetFlags(target) {
+    if (target.instanceId)
+        return ` --instance ${target.instanceId}`;
+    if (target.agent)
+        return ` --agent ${target.agent}`;
+    return '';
+}
+/**
+ * `commandmate <verb> <worktree-id>[ <args>]<target flags>[ <trailing>]`.
+ *
+ * @param args - What follows the worktree id, e.g. `<number>` or `"<text>"`
+ * @param trailing - Flags that follow the target, e.g. `--pane --tail 40`
+ */
+function followUpCommand(verb, worktreeId, target, args, trailing) {
+    return `commandmate ${verb} ${worktreeId}${args ? ` ${args}` : ''}${targetFlags(target)}${trailing ? ` ${trailing}` : ''}`;
+}
+/** The `capture` that shows the target's dialog as it is on screen. */
+function dialogCaptureCommand(worktreeId, target) {
+    return followUpCommand('capture', worktreeId, target, undefined, exports.DIALOG_CAPTURE_FLAGS);
+}
+/**
+ * `commandmate capture <id>[ target] --pane`: the pane a message went to, to
+ * look at before a resend (Issue #3992). Without a target (a caller that has
+ * none to give) it names none.
+ */
+function paneCaptureCommand(worktreeId, target) {
+    return target
+        ? followUpCommand('capture', worktreeId, target, undefined, '--pane')
+        : `commandmate capture ${worktreeId} --pane`;
+}

package/dist/cli/utils/reply-ledger.d.ts

@@ -17,7 +17,7 @@
  * and whether an unmarked row may stand in for one — stays with the caller.
  */
 import type { PromptMessageResponse } from '../types/api-responses';
-import type { ApiClient } from './api-client';
+import { type ApiClient } from './api-client';
 /**
  * Chat rows read back per request.
  *