commandmate 0.49.0 → 0.49.2

package/dist/cli/commands/ask.js

@@ -62,6 +62,11 @@ const PANE_FALLBACK_TAIL = 80;
  * marked yet — a session that already answered returns on the first read. When
  * it does elapse the existing pane fallback takes over, so the cost of guessing
  * this too low is a screen scrape, never a lost turn.
+ *
+ * Issue #3983: also the bound of each read after the turn ended (the ledger,
+ * the overlap pages, the pane). Those are outside `--timeout` — the turn has
+ * already completed in time — so a read that does not answer within the grace
+ * moves on to the next fallback rather than ending the ask with 124.
  */
 const REPLY_TURN_ROW_GRACE_MS = 15_000;
 /** How often the grace above re-reads the ledger. */
@@ -130,15 +135,28 @@ function parseTimeout(raw) {
 async function readLatestReply(client, worktreeId, instanceId, since, cliToolId) {
     const requireTurnRow = cliToolId !== undefined && reply_ledger_1.TRANSCRIPT_READER_TOOLS.has(cliToolId);
     const deadline = Date.now() + (requireTurnRow ? REPLY_TURN_ROW_GRACE_MS : 0);
+    // Issue #3983: every read is bounded by the grace, with or without a turn row
+    // to wait for; one that runs out falls back to the pane like an empty ledger.
+    const graceClient = client.withDeadline(Date.now() + REPLY_TURN_ROW_GRACE_MS);
     for (;;) {
-        const messages = await (0, reply_ledger_1.fetchRecentMessages)(client, worktreeId, instanceId);
+        let messages;
+        try {
+            messages = await (0, reply_ledger_1.fetchRecentMessages)(graceClient, worktreeId, instanceId);
+        }
+        catch (error) {
+            if (!(0, api_client_1.isDeadlineExceeded)(error))
+                throw error;
+            return { content: null, messages: null };
+        }
         // The rules are `reply`'s too (Issue #3039). A tool with no transcript
         // takes the newest row after the send, marker or not, with no wait.
         const reply = (0, reply_ledger_1.pickLatestReply)((0, reply_ledger_1.replyCandidates)(messages ?? [], since), requireTurnRow);
+        // The rows go back with the answer so the overlap check (Issue #3955)
+        // reads the same ledger the reply came from, with no request of its own.
         if (reply)
-            return reply.content;
+            return { content: reply.content, messages };
         if (!requireTurnRow || Date.now() >= deadline)
-            return null;
+            return { content: null, messages };
         await sleep(REPLY_TURN_ROW_POLL_MS);
     }
 }
@@ -156,7 +174,10 @@ async function readLatestReply(client, worktreeId, instanceId, since, cliToolId)
  * @param instanceId - Resolved instance ID
  */
 async function readPaneTail(client, worktreeId, cliToolId, instanceId) {
-    return (0, capture_1.readSqueezedPaneTail)(client, worktreeId, cliToolId, instanceId, PANE_FALLBACK_TAIL);
+    // Issue #3983: bounded like the ledger reads; a pane that does not answer is
+    // "no readable pane" (readSqueezedPaneTail never throws).
+    const graceClient = client.withDeadline(Date.now() + REPLY_TURN_ROW_GRACE_MS);
+    return (0, capture_1.readSqueezedPaneTail)(graceClient, worktreeId, cliToolId, instanceId, PANE_FALLBACK_TAIL);
 }
 /** Argument checks. A mocked `process.exit` returns, so nothing here stops early. */
 function validateAskArgs(worktreeId, message, options) {
@@ -222,7 +243,8 @@ function reportWaitFailure(result, worktreeId, instanceId, agent, options) {
 /** Reads the reply from the transcript, falling back to the pane. */
 async function readAskReply(client, worktreeId, instanceId, askedAt, agent) {
     let source = 'history';
-    let reply = await readLatestReply(client, worktreeId, instanceId, askedAt, agent);
+    const latest = await readLatestReply(client, worktreeId, instanceId, askedAt, agent);
+    let reply = latest.content;
     if (reply === null && agent) {
         source = 'pane';
         const pane = await readPaneTail(client, worktreeId, agent, instanceId);
@@ -232,17 +254,133 @@ async function readAskReply(client, worktreeId, instanceId, askedAt, agent) {
     if (reply === null) {
         source = 'none';
     }
-    return { source, reply };
+    return { source, reply, messages: latest.messages };
+}
+/**
+ * Whether this ask's turn was shared with another message (Issue #3955).
+ *
+ * codex 0.164.0 folds a message typed while a turn is running into that turn
+ * ("Messages to be submitted after next tool call") and answers both with one
+ * reply, so two overlapping asks to one instance both exit 0 and one of them
+ * prints the other's answer (UAT 2026-10-27: 3 runs out of 4). Which reply
+ * belongs to which message is not on the wire, so this does not try to
+ * attribute it; it says the reply may not be this ask's.
+ *
+ * Both sides of the overlap, from records `ask` already reads:
+ *
+ * - the later ask: the send API's `turnOpenAtSend` (Issue #3957) — whether a
+ *   turn was open at the moment the body started going in, read on the server
+ *   at that moment. When the key is there its value alone decides this side:
+ *   it does not depend on the record a poll sees (the server publishes only
+ *   the newest one, and a turn opening right after the send replaces it before
+ *   the first poll), and `askedAt` is earlier than the input, so a turn that
+ *   closed in between is not this message's. Without the key ("not known": a
+ *   tool whose hooks report no turn start, an older server), a turn that
+ *   opened before `askedAt` and had not closed by
+ *   it — the turn `wait` adopted, or any turn record a poll saw (`wait` drops a
+ *   closed turn that opened more than one poll interval before it started, so
+ *   a turn that closed before this ask's first poll is only in the record).
+ *   Only a tool whose hooks report turns publishes one, and a turn that had
+ *   closed before the send does not count, so a plain ask never sees it;
+ * - the earlier ask: a `user` row with other text on the same instance sits
+ *   between this ask's own input and the end of the turn. The lower bound is
+ *   the row the send API returned (`foreignSince`, the server's stamp of the
+ *   input start), so a request that went in and was answered while this one
+ *   waited for the input lock is not counted (Issue #3957); `askedAt` when the
+ *   send did not say. The upper bound is the server's close time when it
+ *   published one, else the moment the turn was seen to end, so a message sent
+ *   after the `Stop` (to the next turn) is not counted. With no instance
+ *   resolved for the send there is no "same instance", and this side is off.
+ *
+ * @returns The first reason that applies, or null
+ */
+function detectOverlap(input) {
+    if (input.turnOpenAtSend !== undefined) {
+        if (input.turnOpenAtSend)
+            return 'turn-already-open';
+    }
+    else {
+        const closedBeforeSend = input.turnClosedAt !== null && input.turnClosedAt < input.askedAt;
+        if (input.turnStartedAt !== null && input.turnStartedAt < input.askedAt && !closedBeforeSend) {
+            return 'turn-already-open';
+        }
+        if (input.openAtSend)
+            return 'turn-already-open';
+    }
+    if (input.messages
+        && input.instanceId !== null
+        && (0, reply_ledger_1.hasForeignPromptInWindow)(input.messages, input.message, input.foreignSince, input.until, input.instanceId)) {
+        return 'foreign-message';
+    }
+    return null;
+}
+/**
+ * The stamp of the row the send API wrote for this ask, in epoch ms, or null
+ * when the body carried none (an older server, a mocked send) (Issue #3957).
+ */
+function sentRowStamp(sent) {
+    if (typeof sent?.timestamp !== 'string')
+        return null;
+    const at = Date.parse(sent.timestamp);
+    return Number.isFinite(at) ? at : null;
+}
+/**
+ * Where this ask's turn ended, for the overlap window (Issue #3955): the
+ * server's close time when one is known and not before the send, else the
+ * moment the turn was seen to end. A message stamped later went to the next
+ * turn.
+ */
+function overlapWindowEnd(askedAt, turnEndedAt, closedAt) {
+    return closedAt !== null && closedAt >= askedAt ? Math.min(closedAt, turnEndedAt) : turnEndedAt;
+}
+/**
+ * The ledger rows the overlap check reads, and the instance it is about
+ * (Issue #3955).
+ *
+ * The reply read's rows, plus — when that read came back full of rows newer
+ * than the send, so a `user` row may have been cut off — every `user` row since
+ * the send, paged in its own requests. The reply read itself is left as it is.
+ * The instance is the one the send was resolved to, else the one the ledger
+ * shows this ask's own row on inside `[askedAt, until]`, else null — the same
+ * window the overlap is looked for in, so the same text sent to another
+ * instance after this turn ended cannot leave the instance undecided.
+ */
+async function readOverlapLedger(client, worktreeId, instanceId, message, askedAt, until, messages) {
+    let rows = messages;
+    if (rows && (0, reply_ledger_1.mayHaveDroppedRowsSince)(rows, askedAt)) {
+        // Issue #3983: bounded by the reply grace; a page that does not answer in
+        // it is read like one that failed — the rows already read stand.
+        const graceClient = client.withDeadline(Date.now() + REPLY_TURN_ROW_GRACE_MS);
+        const since = await (0, reply_ledger_1.fetchPromptRowsSince)(graceClient, worktreeId, instanceId, askedAt).catch((error) => {
+            if ((0, api_client_1.isDeadlineExceeded)(error))
+                return null;
+            throw error;
+        });
+        if (since)
+            rows = [...rows, ...since];
+    }
+    const target = instanceId ?? (rows ? (0, reply_ledger_1.ownPromptInstance)(rows, message, askedAt, until) : null);
+    return { messages: rows, instanceId: target };
+}
+/** The one stderr line for an overlap (Issue #3955). */
+function formatOverlapWarning(reason, target) {
+    const what = reason === 'turn-already-open'
+        ? `${target} was already in a turn when this message was sent, so the reply may be that turn's`
+        : `another message reached ${target} during this turn, so the reply may answer it`;
+    return `overlapped: ${what} rather than this ask's (send one ask at a time per instance)`;
 }
 /** Prints the reply (or its JSON, or the no-reply warning). */
-function printAskReply(worktreeId, instanceId, agent, source, reply, options) {
+function printAskReply(worktreeId, instanceId, agent, source, reply, options, overlapped) {
     if (options.json) {
+        // `overlapped` only when it is true (Issue #3955): an ask that did not
+        // overlap prints exactly the payload it always did.
         console.log(JSON.stringify({
             worktreeId,
             instanceId: instanceId ?? null,
             cliToolId: agent ?? null,
             source,
             reply,
+            ...(overlapped ? { overlapped: true } : {}),
         }, null, 2));
     }
     else if (reply === null) {
@@ -289,16 +427,31 @@ Exit codes (wait's, unchanged; --async always exits 0 once the relay exists):
        name it (id=...). id=context-limit: the conversation is over the model's
        limit; \`instances <id> kill <instance>\` and ask again in a fresh session
   21   nothing was running to ask
-  124  timed out. Look with \`capture <id> --instance <id> --pane --tail 60\`
+  124  timed out. Look with \`capture <id> --instance <id> --pane --tail 60\`.
+       When the send itself returned past the deadline, the message WAS sent
+       (stderr says so); do not send it again
+
+Send one ask at a time to an instance (Issue #3955). A message sent while the
+instance is mid-turn can be folded into that turn (codex does), and the two
+asks then get one reply between them. When ask sees that, it still exits 0
+with the reply but prints \`overlapped: ...\` on stderr and --json adds
+"overlapped": true — the reply may answer the other message.
+--async relays (and send --reply-to) take only a turn that ended after the
+message went in, and note a proven overlap on the delivered reply's second line
+(\`[CommandMate relay] ... (overlap=later)\`); see \`relays --id <relay-id>\`.
 
 There is deliberately no --auto-yes: turning another session's Auto-Yes on is
 a decision about that session's guard rails, not part of asking it a question.
 `)
         .action(async (worktreeId, message, options) => {
+        // Issue #3983: `--timeout` counts from here, the resolution and the send
+        // included.
+        const commandStartedAt = Date.now();
         try {
             validateAskArgs(worktreeId, message, options);
             const timeout = parseTimeout(options.timeout);
             const client = new api_client_1.ApiClient({ token: options.token });
+            const deadlineAt = commandStartedAt + timeout * 1000;
             // Resolved once, before the send, and reused for the wait and both
             // reads: the alias-to-id mapping and the roster's tool are the same
             // facts for all four requests, and asking twice is how two of them end
@@ -312,7 +465,10 @@ a decision about that session's guard rails, not part of asking it a question.
             // worktree default: exit 21 while the default was not running, and the
             // default's turn instead of <tool>'s while it was.
             const selector = options.instance ?? options.agent;
-            const { agent, instanceId } = await (0, command_target_1.resolveCommandTarget)(client, worktreeId, selector, options.agent);
+            //
+            // Issue #3983: bounded by `--timeout`; running out is exit 124, nothing sent.
+            const commandTarget = await (0, command_target_1.resolveCommandTarget)(client.withDeadline(deadlineAt), worktreeId, selector, options.agent);
+            const { agent, instanceId } = commandTarget;
             // Taken BEFORE the send so a reply written by the previous turn cannot
             // be read as this one's. Milliseconds, compared against the row's own
             // timestamp rather than against a re-derived clock.
@@ -320,14 +476,18 @@ a decision about that session's guard rails, not part of asking it a question.
             // Issue #2377: registered BEFORE the send, so a session that answers
             // immediately cannot finish its turn in the window between the message
             // and the ledger row. A refusal exits 2 having sent nothing.
-            let relayId;
+            //
+            // Issue #3983: the endpoint resolution is bounded by `--timeout` (exit
+            // 124, nothing registered or sent); the relay POST is not cut, like `/send`.
+            let relay;
             if (options.async) {
-                relayId = await (0, message_dispatch_1.registerRelayForMessage)(client, {
+                relay = await (0, message_dispatch_1.registerRelayForMessage)(client, {
                     worktreeId,
                     replyTo: options.replyTo ?? 'self',
                     instance: options.instance,
                     agent: options.agent,
                     allowRelayChain: options.allowRelayChain,
+                    resolveClient: client.withDeadline(deadlineAt),
                 });
             }
             const sendBody = { content: message };
@@ -340,34 +500,90 @@ a decision about that session's guard rails, not part of asking it a question.
             // reaching the agent. Reported as a config error with the server's
             // own sentence: the answer is to look at that session, never to
             // re-send.
-            await (0, message_dispatch_1.postMessage)(client, worktreeId, sendBody, {
-                relayId,
+            // Issue #3957: a bound relay's id rides on the send (see `postMessage`).
+            const sent = await (0, message_dispatch_1.postMessage)(client, worktreeId, sendBody, {
+                relay,
                 promptWaitingFallback: `${worktreeId} is waiting on a prompt; the message was not sent.`,
+                target: commandTarget,
             });
             // Issue #2377: the whole point of `--async`. Nothing is waited on, so
             // the caller's own turn ends here and the answer arrives later, in their
             // composer, as a `relay` row.
-            if (relayId) {
-                printAsyncAck(worktreeId, instanceId, agent, relayId, options);
+            if (relay) {
+                printAsyncAck(worktreeId, instanceId, agent, relay.id, options);
+                return;
+            }
+            // Issue #3983: the send itself is not cut by `--timeout` — aborting it
+            // would leave "was it sent?" unanswered — but its time counts. Past the
+            // deadline once it returns, the ask ends here, saying the message went in.
+            if (Date.now() >= deadlineAt) {
+                console.error(`Timeout: ${worktreeId} exceeded ${timeout}s while the message was being sent. `
+                    + 'The message was sent; not waiting for the reply. '
+                    + `Look with \`capture ${worktreeId}${instanceId ? ` --instance ${instanceId}` : ''} --pane --tail 60\`.`);
+                process.exit(types_1.WaitExitCode.TIMEOUT);
                 return;
             }
             console.error('Message sent. Waiting for the reply...');
             // `wait`'s own poller, with `wait`'s own defaults: --on-prompt is left
             // at `agent`, so a prompt ends this ask with exit 10 and the payload
             // rather than blocking until the timeout.
+            // Issue #3955: the turn `wait` settled on, for the overlap check.
+            const turn = { startedAt: null, closedAt: null };
+            // Every turn record a poll saw, adopted or not: whether one was open at
+            // the send, and the close time of the newest.
+            const record = { openAtSend: false, closedAt: null };
             const result = await (0, wait_1.pollWorktree)(client, worktreeId, {
                 timeout,
+                timeoutStartedAt: commandStartedAt,
                 instance: instanceId,
                 token: options.token,
                 // Always on (Issue #3011): a turn that never ran must not read as a reply.
                 failOnUpstreamFault: true,
+                onTurnStart: (startedAt, closedAt) => {
+                    // The close time is kept from the first poll that saw this turn
+                    // closed; a later poll publishing a newer turn does not erase it.
+                    if (startedAt !== turn.startedAt)
+                        turn.closedAt = null;
+                    turn.startedAt = startedAt;
+                    if (closedAt !== null && turn.closedAt === null)
+                        turn.closedAt = closedAt;
+                },
+                onTurnRecord: (openedAt, closedAt) => {
+                    record.closedAt = closedAt;
+                    if (openedAt !== null && openedAt < askedAt && (closedAt === null || closedAt >= askedAt)) {
+                        record.openAtSend = true;
+                    }
+                },
             });
             if (result.exitCode !== types_1.WaitExitCode.SUCCESS) {
                 reportWaitFailure(result, worktreeId, instanceId, agent, options);
                 return;
             }
-            const { source, reply } = await readAskReply(client, worktreeId, instanceId, askedAt, agent);
-            printAskReply(worktreeId, instanceId, agent, source, reply, options);
+            // Taken before the reply grace: a message sent after the turn ended
+            // went to the next turn, and is not an overlap with this one.
+            const turnEndedAt = Date.now();
+            const { source, reply, messages } = await readAskReply(client, worktreeId, instanceId, askedAt, agent);
+            // Reported, not acted on (Issue #3955): the exit code and the reply
+            // stay as they are; the line says the reply may not be this ask's.
+            const until = overlapWindowEnd(askedAt, turnEndedAt, turn.closedAt ?? record.closedAt);
+            const ledger = await readOverlapLedger(client, worktreeId, instanceId, message, askedAt, until, messages);
+            const overlap = detectOverlap({
+                message,
+                askedAt,
+                until,
+                turnStartedAt: turn.startedAt,
+                turnClosedAt: turn.closedAt,
+                openAtSend: record.openAtSend,
+                // Issue #3957: the server's own reading at the input start, when it has one.
+                turnOpenAtSend: typeof sent?.turnOpenAtSend === 'boolean' ? sent.turnOpenAtSend : undefined,
+                foreignSince: sentRowStamp(sent) ?? askedAt,
+                instanceId: ledger.instanceId,
+                messages: ledger.messages,
+            });
+            if (overlap) {
+                console.error(formatOverlapWarning(overlap, instanceId ?? ledger.instanceId ?? agent ?? worktreeId));
+            }
+            printAskReply(worktreeId, instanceId, agent, source, reply, options, overlap !== null);
             process.exit(types_1.ExitCode.SUCCESS);
         }
         catch (error) {

package/dist/cli/commands/attach.d.ts

@@ -32,6 +32,7 @@
 import { Command } from 'commander';
 import { ApiClient } from '../utils/api-client';
 import type { ApiErrorPayload } from '../utils/api-client';
+import { type CommandTarget } from './command-target';
 /** The name `attach` will connect to, and whether the server published it. */
 export interface AttachSessionTarget {
     sessionName: string;
@@ -136,11 +137,13 @@ export declare function planGuardedAttach(ownership: Extract<AttachOwnership, {
  * @param cliToolId - Resolved CLI tool
  * @param worktreeId - Worktree id, so the hint's commands are copy-pasteable
  * @param sessionName - Resolved tmux session name
- * @param options - The flags as given
+ * @param options - The flags as given; `target` is the resolved target the
+ *   `capture` hints name (Issue #3982), none when absent
  */
 export declare function buildAttachHints(cliToolId: string, worktreeId: string, sessionName: string, options: {
     readOnly?: boolean;
     live?: boolean;
+    target?: CommandTarget;
 }): string[];
 export declare function createAttachCommand(): Command;
 //# sourceMappingURL=attach.d.ts.map

package/dist/cli/commands/attach.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EACL,SAAS,EAMV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAsD3D,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAqCD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACpB;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAqB1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,OAAO,EAAE,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC,EAC3E,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,eAAe,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C/C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9C,MAAM,EAAE,CAmCV;AAiDD,wBAAgB,mBAAmB,IAAI,OAAO,CAoF7C"}
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EACL,SAAS,EAMV,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAO3D,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAsDvE,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAqCD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACpB;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,eAAe,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,YAAY,GAAG,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAqB1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,OAAO,EAAE,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC,EAC3E,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,eAAe,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CA0C/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAA;CAAE,GACtE,MAAM,EAAE,CAuCV;AAiDD,wBAAgB,mBAAmB,IAAI,OAAO,CAqF7C"}

package/dist/cli/commands/attach.js

@@ -44,6 +44,8 @@ const cli_tool_ids_1 = require("../config/cli-tool-ids");
 const agent_target_options_1 = require("../config/agent-target-options");
 const session_target_1 = require("../utils/session-target");
 const agent_instances_1 = require("../utils/agent-instances");
+const follow_up_command_1 = require("../utils/follow-up-command");
+const command_target_1 = require("./command-target");
 const session_name_1 = require("../../lib/cli-tools/session-name");
 const validation_1 = require("../../lib/cli-tools/validation");
 const tmux_session_surface_1 = require("../../lib/session/tmux-session-surface");
@@ -71,9 +73,14 @@ async function resolveTarget(client, worktreeId, options) {
         console.error(`Error: ${(0, session_target_1.describeSessionTargetConflict)(target.conflict)}`);
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
+    const cliToolId = target.cliToolId ?? options.agent ?? cli_tool_ids_1.DEFAULT_CLI_TOOL_ID;
+    const instanceId = target.instanceId ?? options.instance;
     return {
-        cliToolId: target.cliToolId ?? options.agent ?? cli_tool_ids_1.DEFAULT_CLI_TOOL_ID,
-        instanceId: target.instanceId ?? options.instance,
+        cliToolId,
+        instanceId,
+        // Issue #3982: what the hints name — the instance only when one was asked
+        // for (the server echoes the default instance otherwise), as `resolveCommandTarget`.
+        commandTarget: (0, command_target_1.commandTargetOf)(options.instance ? { cliToolId, instanceId } : null, options.agent),
     };
 }
 /**
@@ -233,18 +240,22 @@ function planGuardedAttach(ownership, sessionName, options) {
  * @param cliToolId - Resolved CLI tool
  * @param worktreeId - Worktree id, so the hint's commands are copy-pasteable
  * @param sessionName - Resolved tmux session name
- * @param options - The flags as given
+ * @param options - The flags as given; `target` is the resolved target the
+ *   `capture` hints name (Issue #3982), none when absent
  */
 function buildAttachHints(cliToolId, worktreeId, sessionName, options) {
+    const capture = (flags) => options.target
+        ? (0, follow_up_command_1.followUpCommand)('capture', worktreeId, options.target, undefined, flags)
+        : `commandmate capture ${worktreeId} ${flags}`;
     const hints = [`Attaching to ${sessionName} (${cliToolId}). Detach with Ctrl+b then d.`];
     if ((0, tmux_session_surface_1.usesAltScreen)(cliToolId) && !options.live) {
-        hints.push(`${cliToolId} draws its transcript at the top of a 200x1000 canvas and its composer at the`, 'bottom, and tmux follows the cursor — so this attach shows the composer and blank rows,', 'not the conversation. To read it:', `  prefix + g                                     popup, in this terminal`, `  commandmate capture ${worktreeId} --pane --tail 60   without attaching`, `  commandmate capture ${worktreeId} --pane --follow    live, without attaching`);
+        hints.push(`${cliToolId} draws its transcript at the top of a 200x1000 canvas and its composer at the`, 'bottom, and tmux follows the cursor — so this attach shows the composer and blank rows,', 'not the conversation. To read it:', `  prefix + g                                     popup, in this terminal`, `  ${capture('--pane --tail 60')}   without attaching`, `  ${capture('--pane --follow')}    live, without attaching`);
         if ((0, tmux_session_surface_1.isLiveAttachSupported)(cliToolId)) {
             hints.push(`  commandmate attach ${worktreeId} --live               re-lay-out to this terminal`);
         }
     }
     if (options.readOnly) {
-        hints.push('Read-only attach: tmux delivers no keys but the detach one, so prefix + g does NOT open', 'the popup here. Read with `commandmate capture <id> --pane --follow` in another terminal.');
+        hints.push('Read-only attach: tmux delivers no keys but the detach one, so prefix + g does NOT open', `the popup here. Read with \`${capture('--pane --follow')}\` in another terminal.`);
     }
     if (options.live) {
         hints.push('Live attach: this session follows THIS terminal until you detach, then goes back to', '200x1000. The web terminal shows the smaller frame while you are attached.');
@@ -322,11 +333,11 @@ function createAttachCommand() {
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
             const client = new api_client_1.ApiClient({ token: options.token });
-            const { cliToolId, instanceId } = await resolveTarget(client, worktreeId, options);
+            const { cliToolId, instanceId, commandTarget } = await resolveTarget(client, worktreeId, options);
             if (options.live && !(0, tmux_session_surface_1.isLiveAttachSupported)(cliToolId)) {
                 console.error(`Error: --live is not supported for ${cliToolId}. It is claude-only until each other `
                     + "agent's detection rules are re-measured at a terminal-sized pane (Issue #2317). "
-                    + `Attach without it, or read with: commandmate capture ${worktreeId} --pane --follow`);
+                    + `Attach without it, or read with: ${(0, follow_up_command_1.followUpCommand)('capture', worktreeId, commandTarget, undefined, '--pane --follow')}`);
                 process.exit(types_1.ExitCode.CONFIG_ERROR);
             }
             const target = await resolveAttachSessionName(client, worktreeId, cliToolId, instanceId);
@@ -357,6 +368,7 @@ function createAttachCommand() {
             for (const line of buildAttachHints(cliToolId, worktreeId, sessionName, {
                 readOnly,
                 live: options.live,
+                target: commandTarget,
             })) {
                 console.error(line);
             }

package/dist/cli/commands/command-target.d.ts

@@ -20,4 +20,11 @@ export interface CommandTarget {
  * @param mode - Passed on only when given, so the call shape stays as it was
  */
 export declare function resolveCommandTarget(client: ApiClient, worktreeId: string, selector: string | undefined, requestedAgent: string | undefined, mode?: InstanceConflictMode): Promise<CommandTarget>;
+/**
+ * The {@link CommandTarget} for a target resolved some other way (Issue #3982:
+ * `attach` and `wait` resolve their own), by the same rule as above.
+ *
+ * @param target - The resolved instance, or null when no selector was given
+ */
+export declare function commandTargetOf(target: ResolvedInstanceTarget | null, requestedAgent: string | undefined): CommandTarget;
 //# sourceMappingURL=command-target.d.ts.map

package/dist/cli/commands/command-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-target.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/command-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CASxB"}
+{"version":3,"file":"command-target.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/command-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,sBAAsB,GAAG,IAAI,EACrC,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,aAAa,CAIf"}

package/dist/cli/commands/command-target.js

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCommandTarget = resolveCommandTarget;
+exports.commandTargetOf = commandTargetOf;
 const instances_1 = require("./instances");
 /**
  * @param selector - Falsy means "no instance": nothing is requested of the server
@@ -19,6 +20,15 @@ async function resolveCommandTarget(client, worktreeId, selector, requestedAgent
             ? await (0, instances_1.resolveInstanceTarget)(client, worktreeId, selector, requestedAgent)
             : await (0, instances_1.resolveInstanceTarget)(client, worktreeId, selector, requestedAgent, mode)
         : null;
+    return commandTargetOf(target, requestedAgent);
+}
+/**
+ * The {@link CommandTarget} for a target resolved some other way (Issue #3982:
+ * `attach` and `wait` resolve their own), by the same rule as above.
+ *
+ * @param target - The resolved instance, or null when no selector was given
+ */
+function commandTargetOf(target, requestedAgent) {
     const agent = target ? target.cliToolId : requestedAgent;
     const instanceId = target?.instanceId;
     return { target, agent, instanceId };

package/dist/cli/commands/instances.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAkD,MAAM,qBAAqB,CAAC;AAsKhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AAqUD,wBAAgB,sBAAsB,IAAI,OAAO,CAgFhD"}
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/instances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EAAE,SAAS,EAAkD,MAAM,qBAAqB,CAAC;AA4KhG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAG7B;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAE6D,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,QAE0B,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,oBAA+B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAmCjC;AAsWD,wBAAgB,sBAAsB,IAAI,OAAO,CAgFhD"}

package/dist/cli/commands/instances.js

@@ -26,6 +26,9 @@ const session_target_1 = require("../utils/session-target");
 // "the worktree id is wrong", and only the session's own identity can tell them
 // apart.
 const whoami_1 = require("./whoami");
+// Issue #3993: each kill is recorded so the env-clean gate can tell a sibling
+// session the orchestrator stopped from one a worker killed.
+const session_kill_ledger_1 = require("../../lib/verification/session-kill-ledger");
 // Issue #2317: the tmux session name each instance runs in, so `commandmate
 // attach` / `tmux attach` need no hand-assembly of `mcbd-<tool>-<wt>[-<suffix>]`.
 const session_name_1 = require("../../lib/cli-tools/session-name");
@@ -388,6 +391,37 @@ async function addInstance(client, worktreeId, options) {
         console.log(JSON.stringify(next, null, 2));
     }
 }
+/**
+ * Record a successful kill in the session-kill ledger (Issue #3993): which
+ * worktree and instance, the tmux sessions the server says it stopped
+ * (`killedSessions` of the kill-session response), and who asked — this
+ * process's cwd and tmux session. A response without `killedSessions` (an
+ * older server) records no session, which excuses nothing.
+ * Best effort: the ledger never fails the command, the kill already happened.
+ */
+function recordSessionKill(worktreeId, instanceId, response) {
+    let callerCwd;
+    try {
+        callerCwd = process.cwd();
+    }
+    catch {
+        callerCwd = null;
+    }
+    const killed = response?.killedSessions;
+    (0, session_kill_ledger_1.appendSessionKillRecord)({
+        version: session_kill_ledger_1.SESSION_KILL_LEDGER_VERSION,
+        at: Date.now(),
+        api: 'kill-session',
+        origin: 'cli',
+        worktreeId,
+        instanceId,
+        sessionNames: Array.isArray(killed)
+            ? killed.filter((name) => typeof name === 'string')
+            : [],
+        callerCwd,
+        callerSession: (0, whoami_1.readTmuxSessionName)(),
+    });
+}
 /**
  * Remove action: drop an instance from the roster. Kills the session first
  * (when --kill) so the server can still resolve its CLI tool from the roster.
@@ -408,7 +442,8 @@ async function removeInstance(client, worktreeId, instanceId, options) {
     }
     if (options.kill) {
         try {
-            await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+            const killResponse = await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+            recordSessionKill(worktreeId, instanceId, killResponse);
             console.error(`Session killed: ${instanceId}`);
         }
         catch (killError) {
@@ -451,7 +486,8 @@ async function killInstance(client, worktreeId, instanceId) {
         console.error('Error: Invalid instance id. Must be an alphanumeric/underscore/hyphen identifier (max 64 chars).');
         process.exit(types_1.ExitCode.CONFIG_ERROR);
     }
-    await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+    const killResponse = await client.post(`/api/worktrees/${worktreeId}/kill-session?instance=${encodeURIComponent(instanceId)}`);
+    recordSessionKill(worktreeId, instanceId, killResponse);
     console.error(`Session killed: ${instanceId}`);
 }
 /**