commandmate 0.30.0 → 0.30.2

package/dist/server/src/lib/hooks/sources/claude/transcript.js

@@ -36,9 +36,12 @@
  *     is therefore keyed on the *prompt* record, never on a `requestId`.
  *  3. **`type: "user"` is mostly not the user.** Of 19 user records in the
  *     sampled session, 18 were `tool_result` payloads. Tool results, `isMeta`
- *     placeholders (`[Image: original 1440x2170…]`), and the slash-command
+ *     placeholders (`[Image: original 1440x2170…]`), and the built-in command
  *     bookkeeping records (`<command-name>`, `<local-command-stdout>`) all have
- *     `type: "user"` and none of them is a prompt. See {@link isClaudePromptRecord}.
+ *     `type: "user"` and none of them is a prompt. The one `<command-…>` shape
+ *     that *is* a prompt — a project command, recorded `<command-message>` first
+ *     — is Issue #2265; see {@link CLAUDE_SLASH_COMMAND_PREFIX} and
+ *     {@link isClaudePromptRecord}.
  *  4. **`thinking` blocks can be empty.** The block arrives with a `signature`
  *     and `thinking: ""` when the text is not retained, so an empty one is
  *     skipped rather than rendered as a blank quote.
@@ -53,13 +56,16 @@
  * @module lib/hooks/sources/claude/transcript
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAUDE_HUMAN_PROMPT_SOURCES = exports.CLAUDE_HUMAN_ORIGIN_KIND = exports.CLAUDE_THINKING_LABEL = exports.MAX_CLAUDE_TOOL_DETAIL_LENGTH = exports.MAX_CLAUDE_TURN_BLOCKS = exports.CLAUDE_TURN_TRUNCATION_MARKER = exports.MAX_CLAUDE_TURN_BODY_LENGTH = exports.CLAUDE_PROJECTS_DIR_SEGMENTS = void 0;
+exports.CLAUDE_END_TURN_STOP_REASON = exports.CLAUDE_HUMAN_PROMPT_SOURCES = exports.CLAUDE_HUMAN_ORIGIN_KIND = exports.CLAUDE_SLASH_COMMAND_PREFIX = exports.CLAUDE_THINKING_LABEL = exports.MAX_CLAUDE_TOOL_DETAIL_LENGTH = exports.MAX_CLAUDE_TURN_BLOCKS = exports.CLAUDE_TURN_TRUNCATION_MARKER = exports.MAX_CLAUDE_TURN_BODY_LENGTH = exports.CLAUDE_PROJECTS_DIR_SEGMENTS = void 0;
 exports.claudeProjectSlug = claudeProjectSlug;
+exports.claudeSlashCommandPrompt = claudeSlashCommandPrompt;
 exports.readClaudeContentBlock = readClaudeContentBlock;
 exports.readClaudeTranscriptRecord = readClaudeTranscriptRecord;
 exports.parseClaudeTranscript = parseClaudeTranscript;
 exports.isClaudePromptRecord = isClaudePromptRecord;
 exports.isClaudeOperatorPromptRecord = isClaudeOperatorPromptRecord;
+exports.isClaudeTurnClosingRecord = isClaudeTurnClosingRecord;
+exports.isClaudeTurnWritable = isClaudeTurnWritable;
 exports.createClaudeTurn = createClaudeTurn;
 exports.buildClaudeTurns = buildClaudeTurns;
 exports.renderClaudeTurn = renderClaudeTurn;
@@ -111,18 +117,97 @@ exports.CLAUDE_THINKING_LABEL = 'Thinking';
 /**
  * Prefixes that mark a `type: "user"` record as bookkeeping rather than a prompt.
  *
- * All four were observed on real transcripts. `<local-command-caveat>` and the
- * `<command-…>` trio are how a slash command is recorded; `<local-command-stdout>`
- * is its output. Treating any of them as a prompt would open a turn that the
- * operator never typed, and the reply to the *next* real prompt would be filed
- * under it.
+ * Three since Issue #2265, which took `<command-message>` off the list — see
+ * {@link CLAUDE_SLASH_COMMAND_PREFIX} for the census that separated the two
+ * shapes the `<command-…>` trio is written in. What is left is the bookkeeping
+ * of a **built-in** command: `<command-name>` first is how Claude records
+ * `/model`, `/compact`, `/clear`, `/login` and `/plan`, `<local-command-stdout>`
+ * is that command's output, and `<local-command-caveat>` is the preamble in
+ * front of it. Treating any of them as a prompt would open a turn that the agent
+ * never answers, and the reply to the *next* real prompt would be filed under it.
  */
 const CLAUDE_SYNTHETIC_PROMPT_PREFIXES = [
     '<local-command-caveat>',
     '<local-command-stdout>',
     '<command-name>',
-    '<command-message>',
 ];
+/**
+ * The tag a slash command the operator typed opens with (Issue #2265).
+ *
+ * ## The two shapes, and why the leading tag is the discriminator
+ *
+ * Claude writes the same three tags for two quite different events, and it
+ * writes them in a different **order** for each. Measured over every
+ * `type: "user"` record under `~/.claude/projects` on 2026-09-03 whose text
+ * opens with one of the `<command-…>` tags — 222 records:
+ *
+ * | leading tag | count | `<command-name>` values |
+ * |---|---|---|
+ * | `<command-message>` | 118 | `/orchestrate`, `/release`, `/uat`, `/worktree-cleanup`, `/worktree-new`, `/multi-stage-design-review`, `/cmate-*` |
+ * | `<command-name>` | 104 | `/model`, `/compact`, `/clear`, `/login`, `/plan` |
+ *
+ * The split is exact and it is the split that matters here. The 118 are
+ * *project and user commands* — a `.claude/commands/*.md` or a skill, expanded
+ * into instructions the agent then works through, which is a turn with a reply
+ * in it. The 104 are commands Claude Code executes itself; their whole output is
+ * the `<local-command-stdout>` record that follows and the agent never answers
+ * them.
+ *
+ * Before #2265 both were excluded, on the reading that a slash command is not
+ * "the operator's text". That cost the 118 their entire turn: the reply was
+ * folded into whichever turn came before — already saved, so
+ * `selectUnwrittenClaudeTurns` answered "nothing to write", and the answer *this*
+ * reader gives is also what suppresses the scraper's copy. The measured loss was
+ * a `/release v0.30.1` turn of 7 text blocks and an `/orchestrate` turn of 8,
+ * neither of which reached History by any path at all.
+ *
+ * ## `origin`, and the versions that carry it
+ *
+ * The 118 also answer {@link isClaudeOperatorPromptRecord}, but only on recent
+ * Claude Code: of them, every record from 2.1.238 onwards (46) carries
+ * `origin: {"kind": "human"}` and every record before it (72, versions 2.1.220
+ * … 2.1.235) carries neither marker — those predate the field. On an old
+ * version the turn is still opened and its reply still written; only the `user`
+ * row is skipped, which is #2196's stated degradation and not a new one.
+ */
+exports.CLAUDE_SLASH_COMMAND_PREFIX = '<command-message>';
+/** `<command-name>/release</command-name>` — the command itself. */
+const CLAUDE_COMMAND_NAME_PATTERN = /<command-name>([\s\S]*?)<\/command-name>/;
+/** `<command-args>v0.30.1</command-args>` — absent on a bare invocation. */
+const CLAUDE_COMMAND_ARGS_PATTERN = /<command-args>([\s\S]*?)<\/command-args>/;
+/**
+ * The line the operator typed, rebuilt from a slash-command record (Issue #2265).
+ *
+ * `<command-name>` and `<command-args>` back into `/release v0.30.1`, which is
+ * the string that was in the composer and — for a command CommandMate sent — the
+ * string `sendUserMessage` already wrote to `chat_messages`. That equality is
+ * what makes the `/send` row *adoptable* instead of duplicated: `recordUserTurn`
+ * compares on normalised content, and the raw record text
+ * (`<command-message>release</command-message>\n<command-name>…`) matches nothing
+ * a person ever sent.
+ *
+ * Returns null for anything that is not this shape, including a
+ * `<command-message>` record with no `<command-name>` in it. Null is what keeps
+ * {@link isClaudePromptRecord} from opening a turn it could not name: a record
+ * whose command cannot be read would otherwise reach History as its own XML,
+ * which is exactly the class of mistake #2196's positive-evidence rule exists to
+ * avoid. No such record was observed — all 118 carried both tags.
+ *
+ * @param text - The record's text, as {@link ClaudeTranscriptRecord.text} holds it
+ * @returns `/name args`, `/name` when there are no arguments, or null
+ */
+function claudeSlashCommandPrompt(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith(exports.CLAUDE_SLASH_COMMAND_PREFIX))
+        return null;
+    const name = CLAUDE_COMMAND_NAME_PATTERN.exec(trimmed)?.[1].trim() ?? '';
+    if (name.length === 0)
+        return null;
+    // Absent on a bare invocation, and empty on a command invoked with no
+    // arguments; both mean the prompt is the command name on its own.
+    const args = CLAUDE_COMMAND_ARGS_PATTERN.exec(trimmed)?.[1].trim() ?? '';
+    return args.length === 0 ? name : `${name} ${args}`;
+}
 /**
  * Read one `message.content` element.
  *
@@ -235,6 +320,7 @@ function readClaudeTranscriptRecord(value) {
         isCompactSummary: value.isCompactSummary === true,
         isInterruption: (0, event_mapper_1.readStringField)(value, 'interruptedMessageId') !== null,
         timestampMs: Number.isFinite(parsed) ? parsed : null,
+        stopReason: message ? (0, event_mapper_1.readStringField)(message, 'stop_reason') : null,
         blocks,
         text,
     };
@@ -279,11 +365,19 @@ function parseClaudeTranscript(text) {
  *
  *  - it carries a `tool_result` block — 18 of the 19 user records in the sampled
  *    session were these;
- *  - `isMeta` is true — the image placeholders and the local-command caveat;
- *  - its text opens with one of {@link CLAUDE_SYNTHETIC_PROMPT_PREFIXES} — the
- *    slash-command bookkeeping;
+ *  - `isMeta` is true — the image placeholders, the local-command caveat, and
+ *    the body of the `.claude/commands/*.md` or skill a slash command expands
+ *    to, which arrives on its own record right behind the one below;
+ *  - its text opens with one of {@link CLAUDE_SYNTHETIC_PROMPT_PREFIXES} — a
+ *    built-in command and its output;
  *  - it has no text at all, or no `uuid` to name the turn with.
  *
+ * A record opening with {@link CLAUDE_SLASH_COMMAND_PREFIX} is the fifth case
+ * and the one Issue #2265 changed: it **is** a prompt, because the operator
+ * typed `/release v0.30.1` and the agent answers it at length. It qualifies only
+ * when {@link claudeSlashCommandPrompt} can actually read the command out of it,
+ * so a shape this reader could not name never opens a turn.
+ *
  * Everything else is treated as a prompt, including `[Request interrupted by
  * user]`. That is deliberate: an interruption really does end the turn, and the
  * records after it really do belong to whatever came next.
@@ -300,6 +394,8 @@ function isClaudePromptRecord(record) {
     const text = record.text.trim();
     if (text.length === 0)
         return false;
+    if (text.startsWith(exports.CLAUDE_SLASH_COMMAND_PREFIX))
+        return claudeSlashCommandPrompt(text) !== null;
     return !CLAUDE_SYNTHETIC_PROMPT_PREFIXES.some((prefix) => text.startsWith(prefix));
 }
 /**
@@ -345,6 +441,14 @@ exports.CLAUDE_HUMAN_PROMPT_SOURCES = ['typed', 'queued'];
  * is the pre-#2196 behaviour — an orphaned assistant pair, which is untidy, and
  * not a fabricated user message, which is wrong.
  *
+ * Issue #2265 widened what reaches here by one shape — the project-command
+ * record `isClaudePromptRecord` now accepts — and the rule holds on it without
+ * change: of the 118 such records under `~/.claude/projects` on 2026-09-03, the
+ * 46 written by Claude Code 2.1.238 and later carry `origin: {"kind": "human"}`
+ * and answer true, and the 72 written before the field existed carry no marker
+ * and answer false. The second group loses its `user` row and keeps its reply,
+ * which is this function's designed degradation rather than a new gap.
+ *
  * `isCompactSummary` and `isInterruption` are then checked explicitly even
  * though nothing observed carries a human marker *and* either flag. They are not
  * redundant by construction: compaction and interruption are both things the
@@ -362,16 +466,62 @@ function isClaudeOperatorPromptRecord(record) {
         return record.originKind === exports.CLAUDE_HUMAN_ORIGIN_KIND;
     return record.promptSource !== null && exports.CLAUDE_HUMAN_PROMPT_SOURCES.includes(record.promptSource);
 }
+/**
+ * `message.stop_reason` on the record that ends a reply (Issue #2264).
+ *
+ * The other value this reader cares about is `tool_use`, which is not named as
+ * a constant because nothing branches on it: everything that is not `end_turn`
+ * leaves the turn open.
+ */
+exports.CLAUDE_END_TURN_STOP_REASON = 'end_turn';
+/**
+ * Whether this assistant record is the one that ended the reply (Issue #2264).
+ *
+ * `end_turn` **and** prose on the same record. See
+ * {@link ClaudeTurnAccumulator.closed} for why neither half alone is the rule,
+ * and note that the emptiness test here is the one `renderClaudeTurn` applies to
+ * a text block — a block whose `text` trims to nothing is not rendered, so it
+ * cannot be what makes a turn look finished either.
+ */
+function isClaudeTurnClosingRecord(record) {
+    if (record.type !== 'assistant')
+        return false;
+    if (record.stopReason !== exports.CLAUDE_END_TURN_STOP_REASON)
+        return false;
+    return record.blocks.some((block) => block.type === 'text' && (block.text ?? '').trim().length > 0);
+}
+/**
+ * Whether a writer may record this turn (Issue #2264).
+ *
+ * Either proof that nothing more is coming: the agent said so
+ * ({@link ClaudeTurnAccumulator.closed}), or it has moved on to another prompt
+ * ({@link ClaudeTurnAccumulator.superseded}).
+ */
+function isClaudeTurnWritable(turn) {
+    if (turn.closed || turn.superseded)
+        return true;
+    // No record of this turn said why it stopped, so there is no evidence to
+    // refuse it on. See {@link ClaudeTurnAccumulator.stopReasonObserved}: this is
+    // unreachable against every Claude version measured, and it is what keeps a
+    // version that stops writing the field from silently disabling the reader.
+    return !turn.stopReasonObserved;
+}
 /** A brand-new accumulator for one turn. */
 function createClaudeTurn(record, sessionId) {
     return {
         sessionId: record.sessionId ?? sessionId,
         promptUuid: record.uuid,
         startedAt: record.timestampMs ?? 0,
-        promptText: record.text,
+        // A slash command's record is XML and the operator typed a line; #2265 puts
+        // the line on the turn so that the `user` row reads `/release v0.30.1` and
+        // the `/send` row holding those same bytes is adopted rather than doubled.
+        promptText: claudeSlashCommandPrompt(record.text) ?? record.text,
         promptIsOperatorInput: isClaudeOperatorPromptRecord(record),
         blocks: [],
         assistantRecords: 0,
+        closed: false,
+        superseded: false,
+        stopReasonObserved: false,
         overflowed: false,
     };
 }
@@ -416,6 +566,13 @@ function buildClaudeTurns(records, sessionId) {
             continue;
         }
         current.assistantRecords += 1;
+        // Assigned rather than or-ed, so the value left standing is the *last*
+        // assistant record's answer. A turn that ends on a `tool_use` record after
+        // an earlier `end_turn` — which is what a turn Claude resumed looks like —
+        // is open again, and that is the reading the Issue's census supports.
+        current.closed = isClaudeTurnClosingRecord(record);
+        if (record.stopReason !== null)
+            current.stopReasonObserved = true;
         for (const block of record.blocks) {
             if (current.blocks.length >= exports.MAX_CLAUDE_TURN_BLOCKS) {
                 current.overflowed = true;
@@ -424,6 +581,11 @@ function buildClaudeTurns(records, sessionId) {
             current.blocks.push(block);
         }
     }
+    // Every turn but the last one has a later prompt behind it, and a prompt is
+    // proof the agent moved on. See {@link ClaudeTurnAccumulator.superseded}.
+    for (let index = 0; index < turns.length - 1; index += 1) {
+        turns[index].superseded = true;
+    }
     return { turns, orphanedAssistantRecords, sidechainRecords };
 }
 /**

package/dist/server/src/lib/hooks/sources/codex/history.js

@@ -94,6 +94,7 @@ exports.acceptCodexRolloutPath = acceptCodexRolloutPath;
 exports.isCodexRolloutFileFor = isCodexRolloutFileFor;
 exports.findCodexRolloutPath = findCodexRolloutPath;
 exports.captureCodexTranscriptTurn = captureCodexTranscriptTurn;
+exports.resolveCodexTranscriptPath = resolveCodexTranscriptPath;
 const promises_1 = require("fs/promises");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -296,15 +297,21 @@ async function scanForRollout(dir, sessionId, depth) {
     return null;
 }
 /**
- * Read the newest turn out of this instance's rollout and write it.
+ * Read this instance's unwritten turns out of its rollout and write them.
  *
- * **Only the newest turn**, and that is the same deliberate difference from
- * opencode's backfill that #2121 documents: every earlier turn already has a
- * `chat_messages` row the *scraper* wrote, and writing a Markdown row for it too
- * would put the same reply in History twice. One row per turn from the scraper,
- * one row per turn from here, so the swap is one-for-one.
+ * **Every turn in the window that is not already a row**, oldest first, which is
+ * the shape Issue #2246 gave all three pull readers and the reasoning for it is
+ * written out once on `../claude/history`'s
+ * {@link captureClaudeTranscriptTurn}. The short version: this reader only runs
+ * when the poller judges a turn finished, so a missed judgement used to lose a
+ * turn permanently — by the next judgement "the newest turn" had moved on.
  *
- * The return value is the poller's instruction. **True** means History holds
+ * #2121's one-row-per-turn argument is preserved by the **anchor**: the newest
+ * turn in the window this reader has already written is where the backfill
+ * starts, and a window with no anchor falls back to the newest turn alone.
+ *
+ * The return value is the poller's instruction, and it is about the **newest**
+ * turn whatever else was written on the way. **True** means History holds
  * this turn as the agent's own Markdown and the scrape must be dropped. **False**
  * means it does not, for any reason at all — no session pointer, no file, an
  * unreadable file, a turn codex has not closed yet — and the scrape must be
@@ -350,8 +357,7 @@ async function captureCodexTranscriptTurn(target, capture = {}) {
             return false;
         const parsed = (0, transcript_1.parseCodexRollout)(text);
         const built = (0, transcript_1.buildCodexTurns)(parsed.records, sessionId);
-        const turn = built.turns.at(-1);
-        if (!turn) {
+        if (built.turns.length === 0) {
             logger.info('codex-transcript-no-turn', {
                 worktreeId: target.worktreeId,
                 instanceId,
@@ -375,8 +381,33 @@ async function captureCodexTranscriptTurn(target, capture = {}) {
                 duplicateStreamRecords: built.duplicateStreamRecords,
             });
         }
-        const lastUserRow = await recordCodexUserTurns(target, turn);
-        return await writeCodexTurn(target, turn, (0, transcript_1.renderCodexTurn)(turn), resolveAssistantTimestampMs(turn, lastUserRow), path);
+        const pending = await selectUnwrittenCodexTurns(target, built.turns);
+        if (pending.turns.length === 0) {
+            logger.debug('codex-transcript-turns-already-saved', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                turnsInWindow: built.turns.length,
+            });
+            return true;
+        }
+        if (pending.turns.length > 1) {
+            logger.info('codex-transcript-backfilling-turns', {
+                worktreeId: target.worktreeId,
+                instanceId,
+                path,
+                pendingTurns: pending.turns.length,
+                turnsInWindow: built.turns.length,
+                anchored: pending.anchored,
+            });
+        }
+        let captured = false;
+        for (let index = 0; index < pending.turns.length; index += 1) {
+            const turn = pending.turns[index];
+            const previousStartedAt = index === 0 ? pending.previousStartedAt : pending.turns[index - 1].startedAt;
+            const lastUserRow = await recordCodexUserTurns(target, turn, previousStartedAt);
+            captured = await writeCodexTurn(target, turn, (0, transcript_1.renderCodexTurn)(turn), resolveAssistantTimestampMs(turn, lastUserRow), path);
+        }
+        return captured;
     }
     catch (error) {
         logger.error('codex-transcript-capture-failed', {
@@ -387,6 +418,58 @@ async function captureCodexTranscriptTurn(target, capture = {}) {
         return false;
     }
 }
+/**
+ * The rollout file this instance would be read from, or null (Issue #2246).
+ *
+ * The same two steps {@link captureCodexTranscriptTurn} opens with, asked
+ * without reading or writing anything; see `../claude/history`'s
+ * {@link resolveClaudeTranscriptPath} for what the Stop receiver does with it.
+ *
+ * Never throws.
+ */
+async function resolveCodexTranscriptPath(target, capture = {}) {
+    try {
+        const sessionId = await resolveCodexSessionId(target);
+        if (!sessionId)
+            return null;
+        return await locateCodexRollout(capture.codexHome ?? resolveCodexHome(), sessionId);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The turns {@link captureCodexTranscriptTurn} still has to write (Issue #2246).
+ *
+ * The same rule as `../claude/history`'s, on codex's own key: search backwards
+ * from the newest turn for one that is already a row, and take everything after
+ * it. Record order and never a timestamp, and bounded by the window — a turn
+ * whose records fell outside {@link CODEX_TRANSCRIPT_TAIL_BYTES} is not in `turns`.
+ *
+ * @param turns - Every turn in the window, oldest first
+ */
+async function selectUnwrittenCodexTurns(target, turns) {
+    const [{ getDbInstance }, { findMessageByRequestId }] = await Promise.all([
+        Promise.resolve().then(() => __importStar(require('../../../../lib/db/db-instance'))),
+        Promise.resolve().then(() => __importStar(require('../../../../lib/db'))),
+    ]);
+    const db = getDbInstance();
+    for (let index = turns.length - 1; index >= 0; index -= 1) {
+        const requestId = (0, agent_transcript_1.codexTurnRequestId)(turns[index].turnId);
+        if (!findMessageByRequestId(db, target.worktreeId, requestId))
+            continue;
+        return {
+            turns: turns.slice(index + 1),
+            previousStartedAt: turns[index].startedAt,
+            anchored: true,
+        };
+    }
+    return {
+        turns: turns.slice(-1),
+        previousStartedAt: turns.length > 1 ? turns[turns.length - 2].startedAt : 0,
+        anchored: false,
+    };
+}
 /**
  * The rollout file for this session, or null.
  *
@@ -435,11 +518,15 @@ async function isReadableFile(path) {
  *
  * @returns The last row written or found, for the timestamp
  */
-async function recordCodexUserTurns(target, turn) {
+async function recordCodexUserTurns(target, turn, previousStartedAt = 0) {
     const instanceId = target.instanceId ?? target.cliToolId;
     let last = { outcome: 'skipped', messageId: null, timestampMs: null };
+    // Issue #2246: a turn read late is a turn whose `/send` row may be older than
+    // #2196's symmetric window reaches. The previous turn's start is the tightest
+    // honest bound, and it only ever widens the search.
+    const adoption = previousStartedAt > 0 ? { adoptionFromMs: previousStartedAt } : {};
     for (const prompt of turn.prompts) {
-        const recorded = await (0, user_turn_recorder_1.recordUserTurn)(target, (0, agent_transcript_1.codexPromptRequestId)(prompt.itemId), prompt.text, prompt.timestampMs);
+        const recorded = await (0, user_turn_recorder_1.recordUserTurn)(target, (0, agent_transcript_1.codexPromptRequestId)(prompt.itemId), prompt.text, prompt.timestampMs, adoption);
         if (recorded.outcome === 'failed') {
             logger.warn('codex-transcript-user-turn-failed', {
                 worktreeId: target.worktreeId,

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

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Reading the transcript when the agent says it stopped (Issue #2246).
+ *
+ * ## 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.
+ *
+ * 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
+ * the reader wrote only that, so the missed turn belonged to nobody and stayed
+ * missing. One misjudged frame, one turn gone (measured 2026-09-02: a reply the
+ * transcript held in full and History never showed).
+ *
+ * The agent itself knows the boundary exactly, and has been telling us: the
+ * `stop` hook. This module is that second trigger.
+ *
+ * ## 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.
+ *
+ * ## What it does not do
+ *
+ * **It does not replace the poller's call.** A session with no hooks — or with
+ * hooks the operator never wired up — sends no `stop`, and for it the poller is
+ * still the only trigger there is. Two triggers for one turn cost nothing
+ * because the readers are idempotent and the gate serialises them per instance;
+ * one trigger that is sometimes absent costs a reply.
+ *
+ * **It does not decide anything about the turn.** The whole judgement stays in
+ * the gate and the readers, so the two entry points cannot drift.
+ *
+ * Never throws: a hook post is fire-and-forget from a CLI's stop handler, and a
+ * failure here must not become the agent's problem.
+ *
+ * @module lib/hooks/stop-history-capture
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_TRANSCRIPT_MAX_ATTEMPTS = exports.STOP_TRANSCRIPT_RETRY_DELAY_MS = void 0;
+exports.captureTranscriptTurnOnStop = captureTranscriptTurnOnStop;
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/hooks/stop-history-capture');
+/**
+ * How long to wait before asking again.
+ *
+ * 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.
+ *
+ * Half a second is chosen against what the gap actually is — a file append that
+ * has already been issued — rather than against a timeout.
+ */
+exports.STOP_TRANSCRIPT_RETRY_DELAY_MS = 500;
+/**
+ * How many times the reader is asked in total (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
+ * that is not always one append: the measured gap between the `stop` post and
+ * the last `text` record was around 100 ms in the fast case, but the turns that
+ * 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
+ * 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.
+ */
+exports.STOP_TRANSCRIPT_MAX_ATTEMPTS = 3;
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Ask the pull-mode reader to record this instance's turn, now.
+ *
+ * The tool question is asked first and without doing any work
+ * (`isPullTranscriptHistory`), so a `stop` from gemini, copilot or opencode
+ * costs one map lookup and returns — in particular it never waits out the
+ * 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.
+ *
+ * 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.
+ *
+ * @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
+ */
+async function captureTranscriptTurnOnStop(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;
+        // 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;
+        }
+        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;
+        }
+        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);
+            logger.debug('stop-history-capture-retried', {
+                worktreeId: worktree.id,
+                cliToolId,
+                instanceId,
+                attempt,
+                maxAttempts,
+                captured,
+            });
+            if (captured)
+                return true;
+        }
+        return false;
+    }
+    catch (error) {
+        logger.warn('stop-history-capture-failed', {
+            worktreeId: worktree.id,
+            cliToolId,
+            instanceId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}