commandmate 0.31.3 → 0.32.1

package/dist/server/src/lib/hooks/sources/launch-command.js

@@ -28,8 +28,10 @@
  * @module lib/hooks/sources/launch-command
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_LAUNCH_CONFIG_ENV_VARS = exports.AGENT_CORRELATION_ENV_VARS = exports.COMMANDMATE_HOOK_ENV_VARS = exports.HOOK_PORT_ENV_VAR = exports.AGENT_EVENT_URL_ENV_VAR = void 0;
+exports.AGENT_LAUNCH_CONFIG_ENV_VARS = exports.SERVER_PORT_ENV_VAR = exports.AGENT_CORRELATION_ENV_VARS = exports.COMMANDMATE_HOOK_ENV_VARS = exports.HOOK_PORT_ENV_VAR = exports.AGENT_EVENT_URL_ENV_VAR = void 0;
+exports.resolveAgentLaunchEnv = resolveAgentLaunchEnv;
 exports.renderAgentLaunchCommand = renderAgentLaunchCommand;
+const env_1 = require("../../../lib/env");
 const hook_settings_generator_1 = require("../../../lib/hooks/hook-settings-generator");
 /**
  * The variable `scripts/hooks/cmate-agent-event.sh` reads its endpoint from.
@@ -116,17 +118,62 @@ exports.AGENT_CORRELATION_ENV_VARS = [
     'CM_PERMISSION_HOOK_URL',
 ];
 /**
- * The other thing a launch line carries: where a tool reads its own settings.
- *
- * A per-tool HOME/config redirect, set by a source so the agent resolves the
- * same settings file CommandMate just wrote — codex's `CODEX_HOME` is the whole
- * of it today. Deliberately **not** stripped from CommandMate's child
- * processes: a redirect is neither a credential nor an identity, and a child
- * that inherits one is unaffected.
- *
- * **One name, measured, not three.** #1933's test carried a local allowlist of
- * `CODEX_HOME` / `COPILOT_HOME` / `XDG_CONFIG_HOME`; building the seven plans
- * shows only the first is ever written. `COPILOT_HOME` and `XDG_CONFIG_HOME` are
+ * The variable a CommandMate CLI run inside an agent resolves its server from
+ * (Issue #2403).
+ *
+ * `src/cli/utils/server-url.ts` resolves a destination as `process.env` first,
+ * `~/.commandmate/.env` second — the documented precedence from #1743, which is
+ * what makes `CM_PORT=3011 commandmate ls` work. #2403 measured what that
+ * precedence costs when two servers share one tmux server: the tmux server's
+ * *global* environment carries whichever `CM_PORT` the server that started it
+ * had, every pane's `-zsh` inherits it, and an agent launched by the OTHER
+ * server therefore types `commandmate` at a destination that is not the server
+ * that launched it. The measured split was hooks on 60301 and the CLI on 3000 —
+ * `whoami` right (it reads the tmux session name), `ls` and `instances` wrong,
+ * and `ask` returning exit 0 from the wrong database, so no caller could tell.
+ *
+ * The launch line is the one place that outranks the inherited environment, so
+ * the launching server states its own port there. {@link resolveAgentLaunchEnv}
+ * is what writes it and carries the rule about when.
+ *
+ * Listed here, beside `CODEX_HOME`, rather than in
+ * {@link AGENT_CORRELATION_ENV_VARS}: see that decision below.
+ */
+exports.SERVER_PORT_ENV_VAR = 'CM_PORT';
+/**
+ * The other thing a launch line carries: config the agent — and everything it
+ * spawns — is meant to keep.
+ *
+ * Two names, and the same test: neither is a credential and neither is an
+ * *identity*, so both are deliberately **not** stripped from CommandMate's own
+ * child processes by `lib/security/env-sanitizer`.
+ *
+ *  - `CODEX_HOME` is a per-tool HOME/config redirect, set by a source so the
+ *    agent resolves the same settings file CommandMate just wrote. A child that
+ *    inherits one is unaffected.
+ *  - {@link SERVER_PORT_ENV_VAR} says which CommandMate server this process
+ *    belongs to. #2403 put it here rather than on the correlation list on
+ *    purpose, and the reason is inheritance: a correlation variable answers
+ *    "which agent is this?", which a child is not, and #1996 strips all six
+ *    precisely so a relay firing from a grandchild cannot claim the agent's
+ *    identity. `CM_PORT` answers "which server do I dial?", and the right
+ *    answer for a descendant is *the same one* — a `commandmate send` typed by
+ *    a shell the agent spawned must reach the server that launched the agent.
+ *    Stripping it would recreate the bug one level down, and would also delete
+ *    an operator-facing variable (#1743) from every child of the server.
+ *
+ *    Measured, not assumed: because `CM_PORT` is on this list,
+ *    `sanitizeEnvForChildProcess()` is byte-identical to what it returned
+ *    before #2403, so none of its six call sites
+ *    (`assistant/non-interactive-runner`, `updates/agent-updater`,
+ *    `cli-tools/copilot-executable`, `slash-command-catalog`,
+ *    `detection/version-probes`, `session/claude-executor`) can change
+ *    behaviour. `tests/unit/security/child-process-server-port-2403.test.ts`
+ *    asserts that with a real child process.
+ *
+ * **Still not `COPILOT_HOME` or `XDG_CONFIG_HOME`.** #1933's test carried a
+ * local allowlist of `CODEX_HOME` / `COPILOT_HOME` / `XDG_CONFIG_HOME`;
+ * building the seven plans shows only the first is ever written. `COPILOT_HOME` and `XDG_CONFIG_HOME` are
  * *read* from the ambient environment by `copilot/hook-settings` and the
  * antigravity config writer to decide where a file goes — they never reach
  * `plan.env`. An allowlist wide enough to admit them would wave through a source
@@ -135,7 +182,48 @@ exports.AGENT_CORRELATION_ENV_VARS = [
  * Enumerated for the same reason as the list above: so the drift guard can
  * subtract it and hold the remainder to an exact set.
  */
-exports.AGENT_LAUNCH_CONFIG_ENV_VARS = ['CODEX_HOME'];
+exports.AGENT_LAUNCH_CONFIG_ENV_VARS = [
+    'CODEX_HOME',
+    exports.SERVER_PORT_ENV_VAR,
+];
+/**
+ * The environment a launch line actually carries: the plan's own, plus this
+ * server's port (Issue #2403).
+ *
+ * A source's `prepareLaunch` builds `plan.env` out of what it knows about *its
+ * tool*. Which server is running is not that — it is the same fact for all
+ * seven sources, and seven copies of it would be seven chances to forget one.
+ * Two sources would have had to grow an environment they do not otherwise have
+ * (claude keeps its correlation keys inside the `--settings` file, opencode
+ * puts its port in argv), and those two are exactly where the reported failure
+ * was found. So it belongs at the one place that already exists for
+ * "everything a launch line carries", which is this module.
+ *
+ * **`getServerPort()`, unconditionally.** The same call the hook URL on the
+ * same line is built from (#1722), so the two cannot name different servers —
+ * including in the degenerate case where `CM_PORT` is unusable and both fall
+ * back to 3000 together. Writing it when nothing was configured is not a guess:
+ * a server given no `CM_PORT` really is listening on 3000, and the pane it
+ * launches an agent into really can have inherited some other server's port
+ * from the tmux server's global environment. A pin that only fired when
+ * `CM_PORT` was set would leave that case — the unconfigured server as the
+ * *victim* — broken.
+ *
+ * **Appended, never overriding.** A source that names `CM_PORT` itself has said
+ * something more specific than "the server that launched me", and keeps it.
+ * Appending also leaves every existing assignment in its existing position, so
+ * codex's `CODEX_HOME` is still the first thing on its line and the correlation
+ * URLs are still where a reader of a `ps` line expects them.
+ *
+ * @param plan - What the source's `prepareLaunch` returned
+ * @returns A copy of `plan.env` with {@link SERVER_PORT_ENV_VAR} appended,
+ *   unless the plan named it first
+ */
+function resolveAgentLaunchEnv(plan) {
+    if (exports.SERVER_PORT_ENV_VAR in plan.env)
+        return plan.env;
+    return { ...plan.env, [exports.SERVER_PORT_ENV_VAR]: String((0, env_1.getServerPort)()) };
+}
 /**
  * Turn a plan into the line a shell can run.
  *
@@ -145,11 +233,20 @@ exports.AGENT_LAUNCH_CONFIG_ENV_VARS = ['CODEX_HOME'];
  * Values are quoted; names are not, because a name that needed quoting would
  * not be a name a shell would assign.
  *
+ * Since #2403 the environment rendered is {@link resolveAgentLaunchEnv}'s, not
+ * `plan.env` directly — the difference is this server's own `CM_PORT`, added
+ * last.
+ *
+ * The empty-assignment branch survives because the renderer is a total
+ * function on plans, not because any plan reaches it: since #2403 every
+ * resolved environment names at least the port.
+ *
  * @param plan - What the source's `prepareLaunch` returned
- * @returns `NAME='value' … command`, or just `command` when `env` is empty
+ * @returns `NAME='value' … command`, or just `command` when there is no
+ *   environment to apply
  */
 function renderAgentLaunchCommand(plan) {
-    const assignments = Object.entries(plan.env).map(([name, value]) => `${name}=${(0, hook_settings_generator_1.shellQuote)(value)}`);
+    const assignments = Object.entries(resolveAgentLaunchEnv(plan)).map(([name, value]) => `${name}=${(0, hook_settings_generator_1.shellQuote)(value)}`);
     if (assignments.length === 0)
         return plan.command;
     return `${assignments.join(' ')} ${plan.command}`;

package/dist/server/src/lib/hooks/stop-history-capture.js

@@ -4,12 +4,18 @@
  *
  * ## Why the poller was not enough
  *
- * `lib/polling/structured-history-gate` is asked to record a turn at exactly one
- * moment: the poll on which the scraper decided the turn had finished and was
- * about to save its own copy. That is the right moment — doing the handover at
- * the point of the write is what makes it impossible for both writers to run —
- * but it is the *only* moment, and the decision behind it is a string analysis
- * of a terminal frame.
+ * `lib/polling/structured-history-gate` is asked to record a turn from exactly
+ * one place: the scraper's own judgement that the turn had finished and its copy
+ * was about to be saved. That is the right place — doing the handover at the
+ * point of the write is what makes it impossible for both writers to run — but
+ * the judgement behind it is a string analysis of a terminal frame, and the
+ * whole trigger hangs off it.
+ *
+ * Issue #2399 made the ask itself repeat: the poll that saves the scrape now
+ * re-asks the reader on the duplicate ticks after it, throttled, until it
+ * answers. That closes the case where the frame is judged finished BEFORE the
+ * transcript closes — the ordinary one. It does nothing for a completion the
+ * frame analysis never judges at all, which is the case below.
  *
  * When that analysis misses one completion the cost is not a delay. By the time
  * the next completion is judged, the newest turn is the next one; before #2246
@@ -22,12 +28,41 @@
  *
  * ## Knowing the boundary is not the same as the file having reached it
  *
- * The `stop` post and the transcript's last append are two events with no
- * ordering between them, and Issue #2264 is what happens when the reader is
- * asked in the gap. The reader now refuses a turn it cannot prove is closed, so
- * the cost of asking too early is a `false` rather than a truncated row — and
- * this module's answer to a `false` is to ask again, up to
- * {@link STOP_TRANSCRIPT_MAX_ATTEMPTS} times, before handing the turn back.
+ * The `stop` post and the transcript's last append are two events, and the
+ * reader refuses a turn it cannot prove is closed — so the cost of asking too
+ * early is a `false` rather than a truncated row. What to *do* about that
+ * `false` is the whole of this module, and the answer depends on which of the
+ * two events is waiting for the other.
+ *
+ * ## Waiting inside the hook is sometimes waiting on ourselves (Issue #2398)
+ *
+ * #2246 and #2264 both read the gap as a race — two appends with no ordering
+ * between them, so asking again after half a second eventually wins. That
+ * reading is Claude Code's, and for Claude Code it is true: claude writes the
+ * transcript and *then* runs its Stop hook, which is why 506 of 508 measured
+ * claude stops captured on the first ask, and why the two that did not were
+ * caught by the retry #2264 added.
+ *
+ * codex is the other way round, and there the ordering is not a race but a
+ * dependency. Measured across three days of logs (2026-09-07): of **105** codex
+ * stop events, **0** captured. Every one of them logged
+ * `codex-transcript-turn-open` three times, 500 ms apart, and the rollout's
+ * `task_complete` for that same `turn_id` was appended **3–63 ms after the
+ * receiver answered** — five turns measured, every one on that side of the
+ * response. codex does not write the record that closes the turn until the Stop
+ * hook's command exits, and the Stop hook's command is a synchronous `curl` at
+ * this receiver. The retry loop was waiting for an append its own caller was
+ * holding up. That is a self-wait: no number of attempts and no interval can
+ * win it, and the 1 s it spent losing was added to the end of every codex turn.
+ *
+ * So the shape is not "ask again", it is **ask once, then get out of the way**:
+ * one synchronous attempt — all claude, antigravity and command-code have ever
+ * needed — and, for a tool whose transcript is waiting on this very hook, a
+ * detached read that only starts once the receiver has answered. The detached
+ * read goes through the same gate as everything else, so it inherits the
+ * per-instance serialisation, the idempotent write, the `broadcastMessage` and
+ * the relay's `onRelayTurnCompleted`; nothing about what a captured turn *does*
+ * changes with when it is captured.
  *
  * ## What it does not do
  *
@@ -79,26 +114,32 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STOP_TRANSCRIPT_MAX_ATTEMPTS = exports.STOP_TRANSCRIPT_RETRY_DELAY_MS = void 0;
+exports.STOP_HOOK_BLOCKS_TRANSCRIPT_CLOSE = exports.STOP_TRANSCRIPT_DEFERRED_DELAYS_MS = exports.STOP_TRANSCRIPT_MAX_ATTEMPTS = exports.STOP_TRANSCRIPT_RETRY_DELAY_MS = void 0;
+exports.resolveStopTranscriptCapture = resolveStopTranscriptCapture;
 exports.captureTranscriptTurnOnStop = captureTranscriptTurnOnStop;
+const tool_id_1 = require("../../lib/hooks/sources/codex/tool-id");
 const logger_1 = require("../../lib/logger");
 const logger = (0, logger_1.createLogger)('lib/hooks/stop-history-capture');
 /**
- * How long to wait before asking again.
+ * How long to wait before asking again, on the awaited path.
  *
- * The `stop` hook fires when the agent considers the turn over, and the last
- * assistant record is appended to the transcript around — not necessarily
- * before — that instant. A reader that arrives in the gap sees a turn that is
- * not closed, answers false (correctly: the row it would write is a reply with
- * its last paragraph missing, frozen under the turn key forever) and, without a
- * retry, hands a turn the agent has definitely finished back to the scraper.
+ * The `stop` hook fires when the agent considers the turn over, and — for a tool
+ * that writes its transcript first — the last assistant record is appended
+ * around, not necessarily before, that instant. A reader that arrives in the gap
+ * sees a turn that is not closed, answers false (correctly: the row it would
+ * write is a reply with its last paragraph missing, frozen under the turn key
+ * forever) and, without a retry, hands a turn the agent has definitely finished
+ * back to the scraper.
  *
  * Half a second is chosen against what the gap actually is — a file append that
- * has already been issued — rather than against a timeout.
+ * has already been issued — rather than against a timeout. Which is exactly why
+ * it is the wrong instrument for a tool where the append has *not* been issued
+ * because this handler has not returned; see
+ * {@link STOP_HOOK_BLOCKS_TRANSCRIPT_CLOSE}.
  */
 exports.STOP_TRANSCRIPT_RETRY_DELAY_MS = 500;
 /**
- * How many times the reader is asked in total (Issue #2264).
+ * How many times the reader is asked in total, on the awaited path (Issue #2264).
  *
  * #2246 asked twice, on the reading that the only thing a retry waits for is one
  * append that has already been issued. The incident #2264 was reported for says
@@ -107,21 +148,151 @@ exports.STOP_TRANSCRIPT_RETRY_DELAY_MS = 500;
  * were saved short had *tool* records still arriving, and a single 500 ms retry
  * lands inside that run rather than after it.
  *
- * Three and not a loop, because the poller's own trigger is still behind this:
- * if the turn is still open after the third ask, the next poll is the right
- * place to notice — it runs when the pane returns to the composer, by which time
- * the transcript is written — and a hook handler that waits on a file is a hook
+ * Three and not a loop, because a hook handler that waits on a file is a hook
  * handler that can hang a turn. The worst case this bounds is 1 s of the agent's
  * stop path, spent only on an instance that has a transcript and an open turn.
+ *
+ * #2264's own comment here used to add that "if the turn is still open after the
+ * third ask, the next poll is the right place to notice". Issue #2398 measured
+ * that sentence and found two claims of which only the first held: the poller
+ * does run again when the pane returns to the composer, but on the measured
+ * codex incident it never reached the gate — its content dedup returned before
+ * the capture call. Issue #2399 fixed that half. A poll that skips a duplicate
+ * frame now re-asks the reader from inside the skip, throttled to one ask every
+ * three ticks, so the sentence is true again and the third attempt does have a
+ * second chance behind it.
+ *
+ * Which is a reason to leave this ceiling where it is, not to raise it. The
+ * recheck is what makes three enough: a fourth awaited ask would spend another
+ * 500 ms of the agent's stop path buying what a tick of the poller now provides
+ * for nothing. And it is still no answer for a tool that cannot close its turn
+ * while this handler is running, because there the first thing that has to
+ * happen is this handler returning — a backstop measured in poll ticks cannot
+ * bring that forward. That case leaves the awaited path entirely:
+ * {@link STOP_TRANSCRIPT_DEFERRED_DELAYS_MS}.
  */
 exports.STOP_TRANSCRIPT_MAX_ATTEMPTS = 3;
+/**
+ * When the detached reads happen, once the receiver has answered (Issue #2398).
+ *
+ * Each entry is the wait *before* that read, measured from the previous one, so
+ * the reads land roughly 150 ms, 650 ms, 2.65 s and 7.65 s after the hook was
+ * answered. Two facts set the shape:
+ *
+ *  - **The first entry is the one that matters.** codex appended
+ *    `task_complete` 3, 16, 59, 61 and 63 ms after the response on the five
+ *    turns that were timed, so a first read at 150 ms is past all of them with
+ *    room to spare. Anything shorter starts betting on the scheduler.
+ *  - **The tail is for the turn that was never going to close.** A turn
+ *    interrupted, or a codex that exits before flushing, never appends anything,
+ *    and the reads after the first exist so that a slow flush is caught rather
+ *    than for the common case. They are cheap — a `false` from the gate is a
+ *    tail read and a parse — and they cost the agent nothing at all, because by
+ *    then the agent has its answer and this promise is detached.
+ *
+ * Finite, and short of the 30 min the poller runs for, because this is a
+ * best-effort second trigger and not a queue: a turn nobody could read stays the
+ * scraper's, which is the fail-open every one of these Issues asks for.
+ */
+exports.STOP_TRANSCRIPT_DEFERRED_DELAYS_MS = [150, 500, 2_000, 5_000];
+/**
+ * Tools whose transcript cannot close while this handler is still running
+ * (Issue #2398).
+ *
+ * A tool id table, which this layer otherwise refuses to keep — the gate's own
+ * comment on `PULL_TRANSCRIPT_READERS` argues the case, and the rule there is
+ * that a table is allowed when it dispatches on a fact and forbidden when it
+ * *decides* one. The fact here is an ordering, and it was measured per tool:
+ *
+ * | tool | stop hook vs. the transcript's last record | captured on the first ask |
+ * |---|---|---|
+ * | claude | hook runs **after** the record is written | 506 / 508 |
+ * | antigravity | after | 9 / 9 |
+ * | command-code | after | 1 / 1 |
+ * | codex | hook runs **before**, and the record waits for it | **0 / 105** |
+ *
+ * Membership therefore says one thing only: for this tool, a `false` from the
+ * synchronous ask means "the agent is waiting for me", so the answer is to
+ * answer and read afterwards. A tool that is *not* here keeps #2264's behaviour
+ * exactly — the awaited retries — because for it the append really is in flight
+ * and waiting really does win.
+ *
+ * Where this belongs eventually is `AgentSourceCapabilities`, beside
+ * `transcriptHistory`: a source declaring `stopBlocksTranscriptClose` would let
+ * this module stop naming anybody. It is not there yet because the ordering has
+ * only been measured for four tools and only one of them needs it, and a
+ * capability every source has to answer is a claim every source has to have
+ * measured. The second member is the right moment to move it.
+ */
+exports.STOP_HOOK_BLOCKS_TRANSCRIPT_CLOSE = new Set([
+    tool_id_1.CODEX_CLI_TOOL_ID,
+]);
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
     });
 }
 /**
- * Ask the pull-mode reader to record this instance's turn, now.
+ * Read again, after the receiver has already answered (Issue #2398).
+ *
+ * Detached: nothing awaits the returned promise in production, which is the
+ * whole point — for codex this loop only gets to see a closed turn *because*
+ * the hook it was posted by has returned. Each read goes through the gate, so a
+ * poll that beats it to the same turn is serialised behind it and the write
+ * stays idempotent either way.
+ *
+ * Stops at the first success and never throws.
+ */
+async function readAfterResponding(gate, worktree, cliToolId, instanceId, capture, delaysMs) {
+    const startedAt = Date.now();
+    try {
+        for (const [index, delayMs] of delaysMs.entries()) {
+            await sleep(delayMs);
+            const captured = await gate.captureStructuredHistoryTurn(worktree.id, cliToolId, instanceId, capture);
+            if (captured) {
+                // The line an operator greps when a codex reply did reach the chat
+                // surface: the receiver's own `agent-event-stop-applied` cannot carry
+                // it, because it was written before this read existed.
+                logger.info('stop-history-capture-deferred-captured', {
+                    worktreeId: worktree.id,
+                    cliToolId,
+                    instanceId,
+                    attempt: index + 1,
+                    attempts: delaysMs.length,
+                    elapsedMs: Date.now() - startedAt,
+                });
+                return true;
+            }
+            logger.debug('stop-history-capture-deferred-open', {
+                worktreeId: worktree.id,
+                cliToolId,
+                instanceId,
+                attempt: index + 1,
+                attempts: delaysMs.length,
+                elapsedMs: Date.now() - startedAt,
+            });
+        }
+        logger.info('stop-history-capture-deferred-exhausted', {
+            worktreeId: worktree.id,
+            cliToolId,
+            instanceId,
+            attempts: delaysMs.length,
+            elapsedMs: Date.now() - startedAt,
+        });
+        return false;
+    }
+    catch (error) {
+        logger.warn('stop-history-capture-deferred-failed', {
+            worktreeId: worktree.id,
+            cliToolId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Ask the pull-mode reader to record this instance's turn, and say what happened.
  *
  * The tool question is asked first and without doing any work
  * (`isPullTranscriptHistory`), so a `stop` from gemini, copilot or opencode
@@ -129,6 +300,11 @@ function sleep(ms) {
  * retry delay. opencode has a second writer too, but a *push* one: its
  * subscription has already received the reply and there is nothing to pull.
  *
+ * Exactly **one** capture is awaited, whichever path is taken. What happens on a
+ * `false` is the fork: a tool whose transcript is waiting on this hook gets the
+ * detached reads and an immediate answer, and every other tool keeps #2264's
+ * awaited retries. See {@link STOP_HOOK_BLOCKS_TRANSCRIPT_CLOSE}.
+ *
  * The import is dynamic so that the poller's module graph — which reaches every
  * transcript reader and the whole opencode client — does not become a static
  * dependency of the hook receiver.
@@ -136,39 +312,52 @@ function sleep(ms) {
  * @param worktree - The worktree the event resolved to
  * @param cliToolId - The tool that sent the event
  * @param instanceId - The already-resolved instance id
- * @returns Whether History now holds this instance's newest turn as Markdown
+ * @returns What was written, or scheduled; see {@link StopTranscriptCaptureStatus}
  */
-async function captureTranscriptTurnOnStop(worktree, cliToolId, instanceId, options = {}) {
+async function resolveStopTranscriptCapture(worktree, cliToolId, instanceId, options = {}) {
     try {
-        const { captureStructuredHistoryTurn, hasStructuredHistoryTranscript, isPullTranscriptHistory } = await Promise.resolve().then(() => __importStar(require('../../lib/polling/structured-history-gate')));
-        if (!isPullTranscriptHistory(cliToolId))
-            return false;
+        const gate = await Promise.resolve().then(() => __importStar(require('../../lib/polling/structured-history-gate')));
+        if (!gate.isPullTranscriptHistory(cliToolId))
+            return { status: 'unavailable' };
         // No `transcriptPathHint`: that value is a line the *pane* printed, and the
         // hook receiver has not read the pane. A tool whose transcript can only be
         // found that way has no session pointer either, and therefore sends no stop
         // event this path could act on.
         const capture = { worktreePath: worktree.path, transcriptPathHint: null };
-        if (await captureStructuredHistoryTurn(worktree.id, cliToolId, instanceId, capture)) {
-            return true;
+        if (await gate.captureStructuredHistoryTurn(worktree.id, cliToolId, instanceId, capture)) {
+            return { status: 'captured' };
+        }
+        // Asked once, before any waiting, on either path: every failure other than
+        // "the turn is not closed yet" — no session pointer, no transcript, hooks
+        // the operator never wired up for this tool — is a reason neither waiting
+        // nor deferring can fix, and an instance with no transcript will not have
+        // one in 150 ms either. A transcript that exists does not stop existing
+        // between attempts, so this is not re-asked.
+        const hasTranscript = () => gate.hasStructuredHistoryTranscript(worktree.id, cliToolId, instanceId, capture);
+        if (exports.STOP_HOOK_BLOCKS_TRANSCRIPT_CLOSE.has(cliToolId)) {
+            const delaysMs = options.deferredDelaysMs ?? exports.STOP_TRANSCRIPT_DEFERRED_DELAYS_MS;
+            if (delaysMs.length === 0)
+                return { status: 'unavailable' };
+            if (!(await hasTranscript()))
+                return { status: 'unavailable' };
+            const deferred = readAfterResponding(gate, worktree, cliToolId, instanceId, capture, delaysMs);
+            logger.info('stop-history-capture-deferred', {
+                worktreeId: worktree.id,
+                cliToolId,
+                instanceId,
+                delaysMs,
+            });
+            return { status: 'deferred', deferred };
         }
         const retryDelayMs = options.retryDelayMs ?? exports.STOP_TRANSCRIPT_RETRY_DELAY_MS;
         if (retryDelayMs <= 0)
-            return false;
-        // The retry is for one failure and one only: the turn is not closed yet
-        // because its remaining assistant records have not been appended. Every
-        // other reason the capture answers false — no session pointer, no
-        // transcript, the operator never wired hooks for this tool — is a reason
-        // waiting cannot fix, and this handler is on the agent's own stop path, so
-        // half a second spent for nothing is half a second added to every turn it is
-        // spent on. Asked once, before the first sleep: a transcript that exists
-        // does not stop existing between attempts.
-        if (!(await hasStructuredHistoryTranscript(worktree.id, cliToolId, instanceId, capture))) {
-            return false;
-        }
+            return { status: 'unavailable' };
+        if (!(await hasTranscript()))
+            return { status: 'unavailable' };
         const maxAttempts = Math.max(1, options.maxAttempts ?? exports.STOP_TRANSCRIPT_MAX_ATTEMPTS);
         for (let attempt = 2; attempt <= maxAttempts; attempt += 1) {
             await sleep(retryDelayMs);
-            const captured = await captureStructuredHistoryTurn(worktree.id, cliToolId, instanceId, capture);
+            const captured = await gate.captureStructuredHistoryTurn(worktree.id, cliToolId, instanceId, capture);
             logger.debug('stop-history-capture-retried', {
                 worktreeId: worktree.id,
                 cliToolId,
@@ -178,9 +367,9 @@ async function captureTranscriptTurnOnStop(worktree, cliToolId, instanceId, opti
                 captured,
             });
             if (captured)
-                return true;
+                return { status: 'captured' };
         }
-        return false;
+        return { status: 'unavailable' };
     }
     catch (error) {
         logger.warn('stop-history-capture-failed', {
@@ -189,6 +378,19 @@ async function captureTranscriptTurnOnStop(worktree, cliToolId, instanceId, opti
             instanceId,
             error: error instanceof Error ? error.message : String(error),
         });
-        return false;
+        return { status: 'unavailable' };
     }
 }
+/**
+ * Whether History now holds this instance's newest turn as Markdown.
+ *
+ * The boolean face of {@link resolveStopTranscriptCapture}, and the shape #2246
+ * and #2264 pinned: `true` means the row is written *now*. A scheduled read is
+ * not one, so codex answers false here on the turns it later captures — which is
+ * why the receiver reads the status word instead (`AgentStopOutcome`), and why
+ * the deferred outcome is logged rather than returned.
+ */
+async function captureTranscriptTurnOnStop(worktree, cliToolId, instanceId, options = {}) {
+    const { status } = await resolveStopTranscriptCapture(worktree, cliToolId, instanceId, options);
+    return status === 'captured';
+}