commandmate 0.34.0 → 0.35.0

package/dist/server/server.js

@@ -87,6 +87,83 @@ const session_cleanup_1 = require("./src/lib/session-cleanup");
 const dev = process.env.NODE_ENV !== 'production';
 const hostname = (0, env_1.getEnvByKey)('CM_BIND') || '127.0.0.1';
 const port = parseInt((0, env_1.getEnvByKey)('CM_PORT') || '3000', 10);
+/**
+ * Issue #2489: the `CM_AUTH_SCOPE` value that exempts the local listener.
+ *
+ * Written out here rather than imported from `src/lib/ws-server.ts`, which
+ * exports the same constant for the Node-runtime side, for the same reason the
+ * `x-cm-raw-url` header name below is written out: this is read at MODULE SCOPE,
+ * before `app.prepare()`, and everything server.ts evaluates that early has to
+ * stand on its own. `tests/integration/remote-ingress-auth-2489.test.ts` holds
+ * the two spellings equal, so a rename cannot leave one of them behind.
+ */
+const REMOTE_ONLY_AUTH_SCOPE = 'remote-only';
+/**
+ * Issue #2489: the loopback address the Provider's upstream is pointed at.
+ *
+ * `commandmate remote --auth remote-only` asks for "the phone authenticates,
+ * the PC in front of the machine does not". The listener a request landed on is
+ * the only unforgeable way to tell those apart (see the header of
+ * `src/lib/ws-server.ts`'s ingress section), so this bind is deliberately the
+ * literal loopback address rather than `hostname`: the second listener must
+ * never be reachable from the LAN, whatever `CM_BIND` says.
+ */
+const REMOTE_INGRESS_BIND = '127.0.0.1';
+/**
+ * Issue #2489: whether `CM_BIND` keeps the local listener off the network.
+ *
+ * `remote-only` makes the local listener unauthenticated, so a non-loopback
+ * bind would extend "local means trusted" to every host on the LAN. The CLI
+ * refuses that combination up front (exit 2); this is the second, independent
+ * check, because `CM_BIND` can also be set in `.env` or exported after the fact.
+ */
+function isLoopbackBind(bind) {
+    return bind === '127.0.0.1' || bind === 'localhost' || bind === '::1' || bind === '[::1]';
+}
+/**
+ * Fall back to authenticating every listener, and say why.
+ *
+ * Writes the decision back into `process.env` rather than only returning it:
+ * `middleware.ts` and `ws-server.ts` read `CM_AUTH_SCOPE` per request, so a
+ * degradation that lived in a local variable would leave the local listener
+ * exempt while this process believed it had closed the door.
+ */
+function refuseRemoteOnly(reason) {
+    console.error(`[Security] CM_AUTH_SCOPE=${REMOTE_ONLY_AUTH_SCOPE} refused: ${reason}. ` +
+        'Every listener will require authentication.');
+    process.env.CM_AUTH_SCOPE = 'all';
+    return null;
+}
+/**
+ * Resolve the port of the remote-only ingress listener, or null for one listener.
+ *
+ * Fail-closed at every branch: anything this cannot verify turns into
+ * {@link refuseRemoteOnly}, which is the pre-#2489 behaviour (auth everywhere).
+ *
+ * @returns The loopback port to open for the Provider, or null
+ */
+function resolveRemoteIngressPort() {
+    if (process.env.CM_AUTH_SCOPE !== REMOTE_ONLY_AUTH_SCOPE)
+        return null;
+    if (!isLoopbackBind(hostname)) {
+        return refuseRemoteOnly(`CM_BIND is ${hostname}, which is not loopback`);
+    }
+    const raw = process.env.CM_REMOTE_INGRESS_PORT;
+    if (!raw) {
+        return refuseRemoteOnly('CM_REMOTE_INGRESS_PORT is not set');
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+        return refuseRemoteOnly(`CM_REMOTE_INGRESS_PORT is not a valid port: ${raw}`);
+    }
+    if (parsed === port) {
+        // One socket cannot be two ingresses, and "the Provider dials the port the
+        // user dials" is exactly the confusion this whole mechanism exists to avoid.
+        return refuseRemoteOnly('CM_REMOTE_INGRESS_PORT is the same port the server serves on');
+    }
+    return parsed;
+}
+const remoteIngressPort = resolveRemoteIngressPort();
 // Issue #331: HTTPS configuration
 const certPath = process.env.CM_HTTPS_CERT;
 const keyPath = process.env.CM_HTTPS_KEY;
@@ -162,14 +239,27 @@ async function resolveWorktreeAliasRedirect(url) {
 // All WebSocket upgrades are handled by ws-server.ts (our own upgrade listener).
 app.setupWebSocketHandler = () => { };
 app.prepare().then(() => {
-    // Request handler for both HTTP and HTTPS
-    const requestHandler = async (req, res) => {
+    // Request handler for both HTTP and HTTPS.
+    //
+    // Issue #2489: a factory rather than a single handler, because the ONE thing a
+    // request cannot lie about is the listener it arrived on, and that fact is
+    // only known here — at the point the listener is constructed. Every listener
+    // is built through this function, so every request is stamped; a listener
+    // wired up any other way would leave the caller's own `x-cm-ingress` in place,
+    // which is the single way this scheme can fail open.
+    const requestHandlerFor = (ingress) => async (req, res) => {
         // Guard: res must be a proper HTTP ServerResponse (not a raw net.Socket).
         // Defense-in-depth: normally not needed after the setupWebSocketHandler fix above,
         // but kept for safety in case any other path passes a non-ServerResponse object.
         if (typeof res?.setHeader !== 'function') {
             return;
         }
+        // Issue #2489: overwrite, unconditionally and before anything reads it.
+        // `middleware.ts` and `ws-server.ts` decide whether to demand a token from
+        // this value alone — deliberately NOT from `X-Real-IP` / `X-Forwarded-For` /
+        // `Host`, all of which a tunnelled request carries identically to a local
+        // one (a Provider's upstream IS 127.0.0.1).
+        (0, ws_server_1.stampIngress)(req.headers, ingress);
         // Issue #332: Inject X-Real-IP header for IP restriction
         // [S3-005] This applies to HTTP requests only. WebSocket upgrade requests
         // are skipped below and handled by ws-server.ts (which uses socket.remoteAddress directly).
@@ -241,15 +331,16 @@ app.prepare().then(() => {
         }
     };
     // Issue #331: Create HTTP or HTTPS server
-    let server;
+    let tlsOptions = null;
     let protocol = 'http';
     if (certPath && keyPath) {
         const validatedCertPath = validateCertPath(certPath, 'Certificate');
         const validatedKeyPath = validateCertPath(keyPath, 'Key');
         try {
-            const cert = (0, fs_1.readFileSync)(validatedCertPath);
-            const key = (0, fs_1.readFileSync)(validatedKeyPath);
-            server = (0, https_1.createServer)({ cert, key }, requestHandler);
+            tlsOptions = {
+                cert: (0, fs_1.readFileSync)(validatedCertPath),
+                key: (0, fs_1.readFileSync)(validatedKeyPath),
+            };
             protocol = 'https';
             console.log('HTTPS server created with TLS certificates');
         }
@@ -258,11 +349,35 @@ app.prepare().then(() => {
             process.exit(2);
         }
     }
-    else {
-        server = (0, http_1.createServer)(requestHandler);
-    }
+    /**
+     * Issue #2489: build one listener, stamped with its own ingress.
+     *
+     * The TLS material is read once above and shared, so the remote listener is
+     * the same server in every respect except which socket it answers on — which
+     * is the only difference that is allowed to matter.
+     */
+    const createListener = (ingress) => tlsOptions === null
+        ? (0, http_1.createServer)(requestHandlerFor(ingress))
+        : (0, https_1.createServer)(tlsOptions, requestHandlerFor(ingress));
+    const server = createListener('local');
+    /**
+     * Issue #2489: the listener `commandmate remote --auth remote-only` points the
+     * Provider at. Null in every other configuration, which is what keeps
+     * `--auth all` (and a plain `commandmate start`) on exactly one socket.
+     */
+    const remoteServer = remoteIngressPort === null ? null : createListener('remote');
+    // Issue #2489: stamp WebSocket upgrades too, and BEFORE `setupWebSocket`
+    // registers its own 'upgrade' listener — Node fires listeners in registration
+    // order, so this is what guarantees the auth check downstream reads a value
+    // this process wrote. HTTP and WS must agree: a phone drives the terminal over
+    // this socket, so a WS path that exempted more than the HTTP path would hand
+    // the tunnel a live shell while the screen behind it still asked for a token.
+    server.on('upgrade', (request) => (0, ws_server_1.stampIngress)(request.headers, 'local'));
+    remoteServer?.on('upgrade', (request) => (0, ws_server_1.stampIngress)(request.headers, 'remote'));
     // Setup WebSocket server
-    (0, ws_server_1.setupWebSocket)(server);
+    (0, ws_server_1.setupWebSocket)(server, {
+        additionalServers: remoteServer === null ? [] : [remoteServer],
+    });
     // Scan and sync worktrees on startup
     async function initializeWorktrees() {
         try {
@@ -466,9 +581,35 @@ app.prepare().then(() => {
         }
         process.exit(1);
     });
+    // Issue #2489: open the Provider's door on its own loopback socket.
+    //
+    // Started before the main `listen` so the CLI's readiness probe on this port
+    // cannot outrun it. An error here is NOT fatal to the process — killing the
+    // server would take the user's local session down with the remote one, which
+    // is the same reason `--expires` closes only the Provider (§5.3) — but it IS
+    // fail-closed: without this socket there is no "remote" ingress, so the local
+    // exemption is withdrawn and every listener goes back to demanding a token.
+    // `commandmate remote` then fails its readiness probe on this port and rolls
+    // the whole session back, which is where the user sees the error.
+    if (remoteServer !== null && remoteIngressPort !== null) {
+        remoteServer.on('error', (err) => {
+            console.error(`[Security] Remote ingress listener on ${REMOTE_INGRESS_BIND}:${remoteIngressPort} failed ` +
+                `(${err.code ?? err.message}). Every listener will require authentication.`);
+            process.env.CM_AUTH_SCOPE = 'all';
+        });
+        remoteServer.listen(remoteIngressPort, REMOTE_INGRESS_BIND, () => {
+            console.log(`> Remote ingress ready on ${protocol}://${REMOTE_INGRESS_BIND}:${remoteIngressPort} (authentication required)`);
+        });
+    }
     server.listen(port, hostname, async () => {
         console.log(`> Ready on ${protocol}://${hostname}:${port}`);
         console.log(`> WebSocket server ready`);
+        if (remoteIngressPort !== null) {
+            // Say it on the main "Ready" line too: "the PC does not need to log in" is
+            // a security-relevant departure from the default, and a server log that
+            // only mentions it in a line above is a log nobody reads.
+            console.log(`> Auth scope: ${REMOTE_ONLY_AUTH_SCOPE} — ${protocol}://${hostname}:${port} does not require a token`);
+        }
         // Issue #2113: verify that the URL the documentation advertises
         // (`http://localhost:<port>`) actually reaches THIS process. It does not when
         // another process holds `::1:<port>`: `localhost` resolves ::1 before 127.0.0.1
@@ -647,12 +788,59 @@ app.prepare().then(() => {
             console.log('Graceful shutdown timeout, forcing exit...');
             process.exit(1);
         }, 3000);
-        // Try graceful HTTP server close
-        server.close(() => {
-            clearTimeout(forceExitTimeout);
-            console.log('Server closed gracefully');
-            process.exit(0);
-        });
+        // Try graceful HTTP server close.
+        //
+        // Issue #2489: EVERY listener this process opened, not just the main one.
+        // `remoteServer` was absent from this function entirely, and the cost was
+        // asymmetry on the door the user cannot see: `server.close()`'s callback
+        // fires once the LOCAL connections have drained, and the `process.exit(0)`
+        // inside it then cut off any request still in flight through the provider.
+        // The local listener had three seconds of grace and the remote one had
+        // none. (The accept window between the teardown above and this point is the
+        // same for both listeners, and effectively zero — everything between the
+        // signal and here is synchronous, so the event loop never turns to accept a
+        // connection. The in-flight requests are the real loss.)
+        //
+        // The invariant, rather than the fix: whatever shutdown does to one
+        // listener it does to all of them. Anything added here belongs INSIDE this
+        // loop rather than on `server` alone — applying it to `server` only would
+        // put the asymmetry straight back on the listener nobody is looking at.
+        const listeners = remoteServer === null ? [server] : [server, remoteServer];
+        // `close()` stops each accept loop immediately and calls back once that
+        // listener's own connections have ended, so both doors shut now and the
+        // exit waits for the last one to drain. A listener that never reached
+        // `listen()` (EADDRINUSE on the remote port) calls its callback with an
+        // Error instead of throwing, which counts as drained here — which is what
+        // we want: a door that never opened cannot be holding anything.
+        let draining = listeners.length;
+        for (const listener of listeners) {
+            listener.close(() => {
+                draining -= 1;
+                if (draining > 0)
+                    return;
+                clearTimeout(forceExitTimeout);
+                console.log('Server closed gracefully');
+                process.exit(0);
+            });
+            // Issue #2488: close() stops accepting immediately, but its callback only
+            // fires once every ESTABLISHED connection on that listener is gone. A
+            // browser tab left on the dashboard holds keep-alive sockets with no
+            // request in flight, and nothing ever closes them, so the callback never
+            // ran and the process lived the full 3 seconds to the force-exit — with
+            // its listening socket already closed. That window is what the stop
+            // scripts used to mistake for "stopped" (they looked for a listener,
+            // found none, and returned while this process was still alive and still
+            // named by logs/server.pid).
+            //
+            // closeIdleConnections() ends exactly those sockets. A connection with a
+            // request in flight is NOT idle and is left alone: it still gets the 3
+            // seconds above, so an in-flight response is no more truncated than
+            // before. The stop scripts no longer depend on this being fast — they
+            // wait for the PID — but the common case now exits in milliseconds
+            // instead of 3 seconds. Per #2489's invariant this runs on EVERY
+            // listener, so the remote door drains on the same terms as the local one.
+            listener.closeIdleConnections();
+        }
     }
     process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
     process.on('SIGINT', () => gracefulShutdown('SIGINT'));

package/dist/server/src/config/websocket-config.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * WebSocket heartbeat / reconnect constants shared by the server and the browser.
+ *
+ * Issue #2502: the socket had no liveness probe at all, so a half-open path — a
+ * phone that walked out of range, a laptop resuming from sleep, a Wi-Fi/LTE
+ * handover — stayed `connected` on both ends while every frame fell on the
+ * floor. TCP alone does not notice: without traffic neither side gets a RST,
+ * and `readyState` keeps answering OPEN. The only way out is to put bytes on
+ * the wire on a schedule and treat silence as a disconnect.
+ *
+ * Server and client read the same numbers from here because the two halves are
+ * a single protocol: the client's patience has to be a multiple of the server's
+ * beat, or a healthy connection gets killed between beats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WS_HALF_OPEN_CLOSE_CODE = exports.WS_RECONNECT_JITTER_RATIO = exports.WS_RECONNECT_MAX_DELAY_MS = exports.WS_RECONNECT_BASE_DELAY_MS = exports.WS_CLIENT_LIVENESS_TIMEOUT_MS = exports.WS_CLIENT_LIVENESS_CHECK_INTERVAL_MS = exports.WS_HEARTBEAT_MESSAGE_TYPE = exports.WS_SERVER_HEARTBEAT_INTERVAL_MS = void 0;
+/**
+ * How often the server pings every client and emits an application-level beat.
+ *
+ * 30s is the `ws` library's own recipe cadence and stays well inside the idle
+ * timeouts of the proxies CommandMate is tunnelled through (Cloudflare Quick
+ * Tunnel, Tailscale Serve), which is a second reason to send it at all.
+ */
+exports.WS_SERVER_HEARTBEAT_INTERVAL_MS = 30_000;
+/**
+ * Server → client application-level beat (Issue #2502).
+ *
+ * A protocol-level ping is invisible to a browser: the WebSocket API answers
+ * pings automatically and gives page JavaScript no way to observe either the
+ * ping or its own pong. So the server sends this frame alongside the protocol
+ * ping — same cadence, same sweep — purely so the tab has something it CAN see.
+ * The client consumes it for liveness and does not forward it to listeners.
+ */
+exports.WS_HEARTBEAT_MESSAGE_TYPE = 'heartbeat';
+/** How often the client checks how long it has been since anything arrived. */
+exports.WS_CLIENT_LIVENESS_CHECK_INTERVAL_MS = 5_000;
+/**
+ * Silence, in ms, after which the client declares the socket half-open.
+ *
+ * 2.5x the server beat: one lost or late heartbeat must not tear down a healthy
+ * connection, but two in a row is not something a live path does. Anything
+ * inbound refreshes the clock — a broadcast, a terminal chunk, the beat — so a
+ * busy socket never gets near this.
+ */
+exports.WS_CLIENT_LIVENESS_TIMEOUT_MS = 75_000;
+/** Default base delay for the client's reconnect backoff. */
+exports.WS_RECONNECT_BASE_DELAY_MS = 1_000;
+/** Default ceiling for the client's reconnect backoff. */
+exports.WS_RECONNECT_MAX_DELAY_MS = 30_000;
+/**
+ * Fraction of the computed backoff the client randomises by, +/- (Issue #2502).
+ *
+ * Without it every tab that was connected to a restarting server retries on the
+ * identical 1s/2s/4s grid and the thundering herd lands on the first socket the
+ * new process opens. +/-20% is enough to smear the herd across the window while
+ * keeping the backoff's shape recognisable.
+ */
+exports.WS_RECONNECT_JITTER_RATIO = 0.2;
+/**
+ * Close code the client uses when it gives up on a silent socket.
+ *
+ * In the application-private 4000-4999 range (1000-2999 are reserved by the
+ * protocol and browsers throw on most of them), so a server-side close log can
+ * tell "the tab decided this path was dead" apart from an ordinary goodbye.
+ */
+exports.WS_HALF_OPEN_CLOSE_CODE = 4001;

package/dist/server/src/lib/auto-yes-poller.js

@@ -49,6 +49,7 @@ exports.clearAllPollerStates = clearAllPollerStates;
 exports.getLastServerResponseTimestamp = getLastServerResponseTimestamp;
 exports.isPollerActive = isPollerActive;
 exports.validatePollingContext = validatePollingContext;
+exports.capturePollerFrame = capturePollerFrame;
 exports.captureAndCleanOutput = captureAndCleanOutput;
 exports.processStopConditionDelta = processStopConditionDelta;
 exports.detectAndRespondToPrompt = detectAndRespondToPrompt;
@@ -224,9 +225,28 @@ function validatePollingContext(compositeKey, pollerState) {
     }
     return 'valid';
 }
+/**
+ * Capture tmux session output once, keeping both spellings (Issue #2522).
+ *
+ * @internal Exported for testing purposes only.
+ * @param worktreeId - Worktree identifier
+ * @param cliToolId - CLI tool type being polled
+ * @param captureLines - Optional number of lines to capture
+ * @param instanceId - Optional agent instance ID (Issue #896; defaults to primary session)
+ * @returns The tick's raw capture and its cleaned form
+ */
+async function capturePollerFrame(worktreeId, cliToolId, captureLines, instanceId) {
+    const lines = captureLines ?? auto_yes_config_1.FULL_CAPTURE_LINES;
+    const output = await (0, cli_session_1.captureSessionOutput)(worktreeId, cliToolId, lines, instanceId);
+    return { raw: output, clean: (0, cli_patterns_1.stripBoxDrawing)((0, cli_patterns_1.stripAnsi)(output)) };
+}
 /**
  * Capture tmux session output and strip ANSI escape codes.
  *
+ * Kept as the cleaned half of {@link capturePollerFrame} so the many callers and
+ * tests that only ever wanted that string are untouched; `pollAutoYes` takes the
+ * pair. `stripBoxDrawing` still runs exactly once per capture either way.
+ *
  * @internal Exported for testing purposes only.
  * @param worktreeId - Worktree identifier
  * @param cliToolId - CLI tool type being polled
@@ -235,9 +255,7 @@ function validatePollingContext(compositeKey, pollerState) {
  * @returns Cleaned output string (ANSI stripped)
  */
 async function captureAndCleanOutput(worktreeId, cliToolId, captureLines, instanceId) {
-    const lines = captureLines ?? auto_yes_config_1.FULL_CAPTURE_LINES;
-    const output = await (0, cli_session_1.captureSessionOutput)(worktreeId, cliToolId, lines, instanceId);
-    return (0, cli_patterns_1.stripBoxDrawing)((0, cli_patterns_1.stripAnsi)(output));
+    return (await capturePollerFrame(worktreeId, cliToolId, captureLines, instanceId)).clean;
 }
 /**
  * Process stop condition check using delta-based approach.
@@ -276,9 +294,12 @@ function processStopConditionDelta(compositeKey, pollerState, cleanOutput) {
  * @param cleanOutput - ANSI-stripped terminal output
  * @param precomputedLines - Optional pre-split lines to reuse
  * @param instanceId - Optional agent instance ID (Issue #896; defaults to primary session)
+ * @param rawOutput - The SAME tick's capture with its box drawing intact
+ *   (Issue #2522). Omitting it costs Command Code's `AskUserQuestion` and
+ *   nothing else; see {@link capturePollerFrame}.
  * @returns 'responded' | 'no_prompt' | 'duplicate' | 'no_answer' | 'error'
  */
-async function detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, cleanOutput, precomputedLines, instanceId) {
+async function detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, cleanOutput, precomputedLines, instanceId, rawOutput) {
     const compositeKey = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
     try {
         // 1. Detect prompt.
@@ -301,7 +322,15 @@ async function detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, clea
         // `cleanOutput` is handed over already stripped, and the clean-frame entry
         // is the one that does not strip again (`stripBoxDrawing` is not
         // idempotent), so this poller and the response poller judge identical text.
-        const promptDetection = (0, response_checker_1.detectPromptOnCleanFrame)(cleanOutput, cliToolId, precomputedLines);
+        //
+        // Issue #2522 adds the fourth argument, and it is a WIRING change rather
+        // than a reader one: Command Code's `AskUserQuestion` is anchored on the
+        // rule row `captureAndCleanOutput` blanks, so teaching
+        // `detectPromptOnCleanFrame` to read it changed nothing on this path until
+        // the same tick's raw capture reached it. `precomputedLines` stays the split
+        // of `cleanOutput` — the stop-condition delta and every other tool's reading
+        // are measured on that string and must not move.
+        const promptDetection = (0, response_checker_1.detectPromptOnCleanFrame)(cleanOutput, cliToolId, precomputedLines, rawOutput);
         if (!promptDetection.isPrompt || !promptDetection.promptData) {
             pollerState.lastAnsweredPromptKey = null;
             pollerState.lastAnsweredAt = null;
@@ -519,14 +548,18 @@ async function pollAutoYes(worktreeId, cliToolId, instanceId) {
         const captureLines = autoYesState?.stopPattern
             ? auto_yes_config_1.FULL_CAPTURE_LINES
             : auto_yes_config_1.REDUCED_CAPTURE_LINES;
-        const cleanOutput = await captureAndCleanOutput(worktreeId, cliToolId, captureLines, instanceId);
+        // Issue #2522: one capture, both spellings. The cleaned string drives every
+        // step below exactly as it did; the raw one is carried to the prompt reading
+        // so a dialog anchored on box drawing is not invisible to the one path that
+        // can answer it without a human.
+        const { raw: rawOutput, clean: cleanOutput } = await capturePollerFrame(worktreeId, cliToolId, captureLines, instanceId);
         const lines = cleanOutput.split('\n');
         // 3. Stop condition delta check (Issue #314)
         if (processStopConditionDelta(compositeKey, pollerState, cleanOutput)) {
             return;
         }
         // 4. Detect and respond to prompt
-        const result = await detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, cleanOutput, lines, instanceId);
+        const result = await detectAndRespondToPrompt(worktreeId, pollerState, cliToolId, cleanOutput, lines, instanceId, rawOutput);
         if (result === 'responded') {
             scheduleNextPoll(worktreeId, cliToolId, instanceId, auto_yes_state_1.COOLDOWN_INTERVAL_MS);
             return;

package/dist/server/src/lib/db/agent-instances-db.js

@@ -136,6 +136,17 @@ function getAgentInstance(db, worktreeId, instanceId) {
  * conflict rather than silently overriding it: the roster is user-maintained
  * and a mismatch means one of the two is wrong. Callers surface it as an error.
  *
+ * @deprecated Issue #1925 made `resolveSessionTarget`
+ * (`src/lib/session/resolve-session-target.ts`) the one authority, and Issue
+ * #2491 moved the last two callers — `POST /send` and `resolveRelaySession` —
+ * onto it. **Do not give this function a new caller.** Step 2 above is exactly
+ * what #2487 corrected: with no roster row it takes `requestedCliTool` even
+ * when `instanceId` itself names a different tool, so a caller wired here gets
+ * `mcbd-<requested>-<wt>-<tool-named-id>` back instead of a conflict. It is
+ * kept only because its #1629 unit test
+ * (`tests/unit/db/agent-instances-resolve-cli-tool.test.ts`) still pins that
+ * behaviour; removing both is a separate change.
+ *
  * @param db - Database instance
  * @param worktreeId - Worktree ID
  * @param instanceId - Targeted agent instance ID (omitted for the primary instance)