commandmate 0.30.1 → 0.31.0

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

@@ -400,12 +400,22 @@ async function captureCodexTranscriptTurn(target, capture = {}) {
                 anchored: pending.anchored,
             });
         }
+        // Every prompt row first, then every reply (Issue #2273). The two passes are
+        // what let a reply be dated at its turn's END without overtaking the NEXT
+        // turn's prompt: a queued `/send` row is written while this turn is still
+        // running, so its instant is only knowable once that row has been recorded.
+        // With one turn pending — the ordinary case — this is the single call it
+        // always was.
+        const userRows = [];
+        for (let index = 0; index < pending.turns.length; index += 1) {
+            const previousStartedAt = index === 0 ? pending.previousStartedAt : pending.turns[index - 1].startedAt;
+            userRows.push(await recordCodexUserTurns(target, pending.turns[index], previousStartedAt));
+        }
+        const lastRecordAt = lastCodexRecordAt(parsed.records);
         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);
+            captured = await writeCodexTurn(target, turn, (0, transcript_1.renderCodexTurn)(turn), resolveAssistantTimestampMs(turn, userRows[index], lastRecordAt.get(turn.turnId) ?? 0, nextTurnOpensAt(pending.turns, userRows, index)), path);
         }
         return captured;
     }
@@ -544,20 +554,79 @@ async function recordCodexUserTurns(target, turn, previousStartedAt = 0) {
 /**
  * When the assistant row for this turn is dated.
  *
- * The turn's own clock, from the first record bearing its `turn_id`, so a row
- * written a poll late still sorts where the conversation put it.
+ * **The turn's LAST record, not its first (Issue #2273).** #2197 dated the reply
+ * by the first record bearing the `turn_id` so that a row written a poll late
+ * still sorted where the conversation put it, and #2196 moved it one millisecond
+ * past the last prompt so that `groupMessagesIntoPairs` — which orders by
+ * timestamp and nothing else — could never return the answer above the question.
+ * Both properties survive: `earliest` is a floor this never goes under, and for
+ * codex it is the floor that matters most, because a turn can carry SEVERAL
+ * prompts (measured at more than one on 23 of 326 archived turns) and the reply
+ * has to sort past all of them.
+ *
+ * What neither accounted for is the row that lands BETWEEN the prompt and the
+ * reply. A tool approval is written when the dialog appears, seconds into the
+ * turn, and the chat surface orders its rows by timestamp — so a reply dated at
+ * the turn's start draws ABOVE an approval that really happened before it. The
+ * turn's last record — for codex, the `task_complete` that closes it — is the
+ * moment the turn ended, so everything it produced on the way sorts before it.
+ *
+ * `nextTurnOpensAt` is the ceiling. The next turn's prompt row may be a `/send`
+ * row written while THIS turn was still running — a queued prompt — and a reply
+ * that overtook it would be paired with the wrong question.
+ *
+ * @param lastRecordAt - Epoch ms of the turn's last record, or 0 when unknown
+ * @param nextTurnOpensAt - Epoch ms of the next turn's user row, or null when
+ *   this is the newest turn in the window
+ */
+function resolveAssistantTimestampMs(turn, userRow, lastRecordAt = 0, nextTurnOpensAt = null) {
+    const earliest = userRow.timestampMs === null
+        ? turn.startedAt
+        : Math.max(turn.startedAt, userRow.timestampMs + 1);
+    const latest = nextTurnOpensAt === null ? Number.POSITIVE_INFINITY : nextTurnOpensAt - 1;
+    return Math.max(earliest, Math.min(lastRecordAt, latest));
+}
+/**
+ * When each turn's last record was written (Issue #2273).
+ *
+ * Keyed by `turn_id` and walked over the same records {@link buildCodexTurns}
+ * walks, with the same `response_item` exclusion — that stream is codex's
+ * duplicate of the same events and counting it would be counting each record
+ * twice. It is a second pass rather than a field on the accumulator because
+ * `./transcript` is not this Issue's to change.
+ *
+ * Every record of the turn counts, `task_complete` included: that one IS the
+ * turn's end and is exactly the instant the reply should be dated by.
  *
- * When there is a user row it sits on the same instant or later, and
- * `groupMessagesIntoPairs` orders by timestamp and nothing else — a tie there is
- * decided by whichever row the database returned first, and the losing
- * arrangement (assistant, then user) is exactly the `orphan` pair #2196 exists
- * to remove. So the reply is moved to the first millisecond after the last
- * prompt: the smallest change that makes the order a property of the data.
+ * @returns `turn_id` → epoch ms; absent for a turn with no timestamped record
  */
-function resolveAssistantTimestampMs(turn, userRow) {
-    if (userRow.timestampMs === null)
-        return turn.startedAt;
-    return Math.max(turn.startedAt, userRow.timestampMs + 1);
+function lastCodexRecordAt(records) {
+    const at = new Map();
+    for (const record of records) {
+        if (record.type === 'response_item')
+            continue;
+        const turnId = record.turnId;
+        if (!turnId || record.timestampMs === null)
+            continue;
+        if (record.timestampMs > (at.get(turnId) ?? 0))
+            at.set(turnId, record.timestampMs);
+    }
+    return at;
+}
+/**
+ * The instant the next pending turn's prompt row carries, or null (Issue #2273).
+ *
+ * The user row's own timestamp when there is one, because that is what History
+ * sorts on and it can be EARLIER than the turn's start — an adopted `/send` row
+ * was written when CommandMate handed the text to the pane, which for a queued
+ * prompt is while the previous turn was still running. The turn's start is the
+ * fallback for a turn that produced no row at all.
+ */
+function nextTurnOpensAt(turns, userRows, index) {
+    const next = turns[index + 1];
+    if (!next)
+        return null;
+    return userRows[index + 1]?.timestampMs ?? next.startedAt;
 }
 /**
  * Write one rendered turn, unless it is already there.

package/dist/server/src/lib/hooks/sources/codex/hooks-config.js

@@ -27,12 +27,26 @@
  *     launch line, so `codex` and `codex-2` in one worktree report as
  *     themselves. Verified live — a session launched with
  *     `CM_AGENT_INSTANCE_ID=codex-2` posted `instanceId: "codex-2"`.
- *  4. **Hooks do not run until a human trusts them.** Trust is recorded in the
+ *  4. **Hooks do not run until they are trusted.** Trust is recorded in the
  *     user's own `~/.codex/config.toml` as
  *     `[hooks.state."<file>:<event>:0:0"] trusted_hash`, and an untrusted hook
- *     is skipped in complete silence (#1757 P4). CommandMate does not write
- *     that file — see {@link isCodexHookTrustBypassEnabled} for the whole of
- *     the reasoning, and `docs/design/agent-event-source-interface.md`.
+ *     is skipped in complete silence (#1757 P4). Issue #1760 declined that
+ *     dialog on every launch; Issue #2315 measured what that cost — the decline
+ *     is not remembered, so the dialog returned forever and the hooks never ran
+ *     — and now answers it with *trust* for a worktree that ships no
+ *     `.codex/hooks.json` of its own. codex writes the hash; this server only
+ *     presses the key. See {@link shouldTrustCodexHooks} for the security
+ *     argument, {@link isCodexHookTrustBypassEnabled} for the flag that is
+ *     still off, and `docs/design/agent-event-source-interface.md`.
+ *
+ * ## What keeps the trust once it is granted (Issue #2315)
+ *
+ * codex keys trust by the hash of the handler, so the generated file has to be
+ * byte-identical whoever wrote it. It was not: the hook command named
+ * `process.cwd()/scripts/hooks/cmate-agent-event.sh`, so each of the machine's
+ * worktree servers rewrote the one shared file with its own checkout and undid
+ * the last one's grant. `./relay-install` is the fix — the command now names a
+ * copy under `$CODEX_HOME`, and the file is a function of `$CODEX_HOME` alone.
  *
  * ## Why `$CODEX_HOME/hooks.json` and not `<worktree>/.codex/hooks.json`
  *
@@ -54,10 +68,13 @@
  * @module lib/hooks/sources/codex/hooks-config
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CODEX_SUPPORTED_EVENTS = exports.CODEX_PERMISSION_REQUEST_EVENT = exports.CODEX_REGISTERED_EVENTS = exports.CODEX_SESSION_END_TIMEOUT_SECONDS = exports.CODEX_HOOK_TRUST_BYPASS_FLAG = exports.CODEX_HOOK_TRUST_ENV_VAR = exports.CODEX_PERMISSION_URL_ENV_VAR = exports.CODEX_EVENT_URL_ENV_VAR = exports.CODEX_INSTANCE_ID_ENV_VAR = exports.CODEX_WORKTREE_ID_ENV_VAR = exports.CODEX_TOOL_ENV_VAR = exports.CODEX_HOME_ENV_VAR = exports.CODEX_HOOK_MARKER = void 0;
+exports.CODEX_HOOK_TRUST_POLICY_DEFAULT = exports.CODEX_SUPPORTED_EVENTS = exports.CODEX_PERMISSION_REQUEST_EVENT = exports.CODEX_REGISTERED_EVENTS = exports.CODEX_SESSION_END_TIMEOUT_SECONDS = exports.CODEX_HOOK_TRUST_BYPASS_FLAG = exports.CODEX_HOOK_TRUST_ENV_VAR = exports.CODEX_PERMISSION_URL_ENV_VAR = exports.CODEX_EVENT_URL_ENV_VAR = exports.CODEX_INSTANCE_ID_ENV_VAR = exports.CODEX_WORKTREE_ID_ENV_VAR = exports.CODEX_TOOL_ENV_VAR = exports.CODEX_HOME_ENV_VAR = exports.CODEX_HOOK_MARKER = void 0;
+exports.resolveCodexHookTrustPolicy = resolveCodexHookTrustPolicy;
 exports.isCodexHookTrustBypassEnabled = isCodexHookTrustBypassEnabled;
+exports.shouldTrustCodexHooks = shouldTrustCodexHooks;
 exports.getCodexHome = getCodexHome;
 exports.getCodexHooksPath = getCodexHooksPath;
+exports.resolveCodexRelayCommandPath = resolveCodexRelayCommandPath;
 exports.buildCodexEventHookCommand = buildCodexEventHookCommand;
 exports.buildCodexPermissionHookCommand = buildCodexPermissionHookCommand;
 exports.buildCodexHookSettings = buildCodexHookSettings;
@@ -74,6 +91,7 @@ const hook_settings_generator_1 = require("../../../../lib/hooks/hook-settings-g
 const logger_1 = require("../../../../lib/logger");
 const path_validator_1 = require("../../../../lib/security/path-validator");
 const event_mapper_1 = require("../event-mapper");
+const relay_install_1 = require("./relay-install");
 const tool_id_1 = require("./tool-id");
 const logger = (0, logger_1.createLogger)('lib/hooks/sources/codex/hooks-config');
 /** Loopback: the agent runs on the machine the server runs on. */
@@ -107,7 +125,12 @@ exports.CODEX_INSTANCE_ID_ENV_VAR = 'CM_AGENT_INSTANCE_ID';
 exports.CODEX_EVENT_URL_ENV_VAR = 'CM_HOOK_URL';
 /** Auto-Yes v2 receiver URL, with the correlation keys already in its query. */
 exports.CODEX_PERMISSION_URL_ENV_VAR = 'CM_PERMISSION_HOOK_URL';
-/** Opt-in switch for {@link CODEX_HOOK_TRUST_BYPASS_FLAG}; `bypass` is the only value that acts. */
+/**
+ * How this server answers codex's hook trust question.
+ *
+ * See {@link resolveCodexHookTrustPolicy} for what each value does; anything
+ * else, including unset, is {@link CODEX_HOOK_TRUST_POLICY_DEFAULT}.
+ */
 exports.CODEX_HOOK_TRUST_ENV_VAR = 'CM_CODEX_HOOK_TRUST';
 /** codex's own flag for running unreviewed hooks, for one invocation. */
 exports.CODEX_HOOK_TRUST_BYPASS_FLAG = '--dangerously-bypass-hook-trust';
@@ -150,6 +173,15 @@ exports.CODEX_REGISTERED_EVENTS = {
 exports.CODEX_PERMISSION_REQUEST_EVENT = 'PermissionRequest';
 /** The four words a codex session can actually produce, given the config above. */
 exports.CODEX_SUPPORTED_EVENTS = Object.values(exports.CODEX_REGISTERED_EVENTS);
+/** What an unset or unrecognised {@link CODEX_HOOK_TRUST_ENV_VAR} means. */
+exports.CODEX_HOOK_TRUST_POLICY_DEFAULT = 'auto';
+/** Read {@link CODEX_HOOK_TRUST_ENV_VAR}, defaulting anything unrecognised. */
+function resolveCodexHookTrustPolicy() {
+    const raw = process.env[exports.CODEX_HOOK_TRUST_ENV_VAR];
+    if (raw === 'bypass' || raw === 'never' || raw === 'auto')
+        return raw;
+    return exports.CODEX_HOOK_TRUST_POLICY_DEFAULT;
+}
 /**
  * Whether to launch codex with {@link CODEX_HOOK_TRUST_BYPASS_FLAG}.
  *
@@ -161,19 +193,72 @@ exports.CODEX_SUPPORTED_EVENTS = Object.values(exports.CODEX_REGISTERED_EVENTS);
  * `.codex/hooks.json`, with no dialog, defeating the exact mechanism codex
  * built to prevent it. A structured `Stop` event is not worth that.
  *
- * So the default posture is: CommandMate writes the config and never grants the
- * trust. The human grants it once, through codex's own review screen, which is
- * also the only thing that may write `~/.codex/config.toml` — a file this
- * server never touches (it holds, among other things, the `notify` entry a
- * user's Computer Use integration depends on). Until then the hooks are inert,
- * the screen scraper keeps doing what it did before this Issue, and
- * `cli-tools/codex` dismisses the review dialog so a session still starts.
- *
  * `CM_CODEX_HOOK_TRUST=bypass` exists for headless and CI operators who have
- * weighed that trade for themselves.
+ * weighed that trade for themselves. It is NOT what {@link shouldTrustCodexHooks}
+ * does — that answers one dialog, about hooks it has checked the provenance of.
  */
 function isCodexHookTrustBypassEnabled() {
-    return process.env[exports.CODEX_HOOK_TRUST_ENV_VAR] === 'bypass';
+    return resolveCodexHookTrustPolicy() === 'bypass';
+}
+/**
+ * Whether the server may answer codex's review dialog with *trust* for a
+ * session about to start in `worktreePath` (Issue #2315).
+ *
+ * ## Why this reverses Issue #1760's answer
+ *
+ * #1760 declined the dialog on the operator's behalf — option 3, *Continue
+ * without trusting* — because granting trust writes `[hooks.state…]` into their
+ * own `~/.codex/config.toml`. Two years of that measured badly, and the Issue
+ * this function exists for is the bill:
+ *
+ *  - **Declining is not remembered.** codex records a *grant*; there is no
+ *    "asked and refused" state. So the dialog came back on every single launch,
+ *    which is what made `waitForReady`'s one-shot handling the only thing
+ *    standing between a session and a pane parked three screens deep.
+ *  - **The hooks never ran.** CommandMate writes `hooks.json` in order to
+ *    receive `session_start` / `stop` — the structured events the whole of
+ *    #1760 exists for. Declining every launch meant the default installation
+ *    got the dialog and none of the benefit; the means and the end pointed in
+ *    opposite directions.
+ *
+ * ## Why this is not `--dangerously-bypass-hook-trust` by another name
+ *
+ * The objection #1760 raised is real and this function answers it rather than
+ * dropping it: a hostile repository can ship `.codex/hooks.json`, codex reads
+ * it from `<cwd>`, and *Trust all and continue* would trust that too. So the
+ * grant is withheld from exactly that case — a worktree carrying its own
+ * `.codex/hooks.json` gets the pre-#2315 decline-and-escape path, and the human
+ * answers its dialog themselves.
+ *
+ * What remains trustable is `$CODEX_HOME/hooks.json`: the operator's own file,
+ * holding the operator's own hooks plus the ones this server wrote and marked.
+ * Trusting a file the human already owns is a materially different act from
+ * trusting one that arrived with a `git clone`.
+ *
+ * The grant is still a write to `~/.codex/config.toml`, which this server
+ * otherwise never touches — it is a documented consequence of the default, not
+ * a hidden one, and `CM_CODEX_HOOK_TRUST=never` restores the old behaviour.
+ *
+ * @param worktreePath - Working directory of the session about to start
+ * @returns True when the dialog may be answered with trust
+ */
+function shouldTrustCodexHooks(worktreePath) {
+    if (resolveCodexHookTrustPolicy() === 'never')
+        return false;
+    try {
+        // codex reads `<cwd>/.codex/hooks.json` as well as the home one, and a
+        // review that includes a hook from the repository is a review this server
+        // must not answer.
+        if ((0, fs_1.existsSync)((0, path_1.join)(worktreePath, '.codex', 'hooks.json'))) {
+            logger.info('codex-hooks-trust-withheld-repo-hooks', { worktreePath });
+            return false;
+        }
+    }
+    catch {
+        // An unreadable worktree is not one to grant trust for.
+        return false;
+    }
+    return true;
 }
 /**
  * `$CODEX_HOME`, or `~/.codex`.
@@ -205,6 +290,25 @@ function getCodexHooksPath(options = {}) {
 function fallbackUrlExpression(path, query) {
     return `http://${CODEX_HOOK_HOST}:\${CM_PORT:-3000}${path}${query}`;
 }
+/**
+ * The relay path `hooks.json` may name — never a checkout (Issue #2315).
+ *
+ * `resolveRelayScriptPath()` answers with `process.cwd()/scripts/hooks/…`, which
+ * is the checkout of whichever server wrote the file. On a machine running
+ * several worktree servers against one `$CODEX_HOME/hooks.json` that value is
+ * the only part of the generated file that moves, and every time it moves codex
+ * throws away the trust the human granted and opens on
+ * `Modified since last trusted - review required`. See `./relay-install`.
+ *
+ * So the auto path is the INSTALLED copy, which is a function of `$CODEX_HOME`
+ * alone. An explicit `relayScriptPath` (including `null`) is still honoured
+ * verbatim — that is how the suites drive the two command shapes.
+ */
+function resolveCodexRelayCommandPath(options = {}) {
+    if (options.relayScriptPath !== undefined)
+        return options.relayScriptPath;
+    return (0, relay_install_1.getInstalledCodexRelayPath)(getCodexHome(options));
+}
 /**
  * The command for one lifecycle event.
  *
@@ -215,7 +319,7 @@ function fallbackUrlExpression(path, query) {
  */
 function buildCodexEventHookCommand(event, options = {}) {
     const marker = ` # ${exports.CODEX_HOOK_MARKER}`;
-    const relay = options.relayScriptPath === undefined ? (0, hook_settings_generator_1.resolveRelayScriptPath)() : options.relayScriptPath;
+    const relay = resolveCodexRelayCommandPath(options);
     if (relay) {
         return ([
             (0, hook_settings_generator_1.shellQuote)(relay),
@@ -371,6 +475,15 @@ function mergeCodexHookSettings(existing, generated) {
  */
 function writeCodexHookSettings(options = {}) {
     const settingsPath = getCodexHooksPath(options);
+    // Issue #2315: put the relay where the generated file can name it without
+    // naming a checkout, BEFORE the content is built — `buildCodexHookSettings`
+    // only reads what is installed, so an install that had not happened yet would
+    // emit the inline `curl` shape and give the shared file a third form to drift
+    // between. Best-effort by construction: the installer never throws, and a
+    // machine where it cannot write simply keeps whatever copy is already there.
+    if (options.relayScriptPath === undefined) {
+        (0, relay_install_1.installCodexRelayScript)(getCodexHome(options), (0, hook_settings_generator_1.resolveRelayScriptPath)());
+    }
     let existing = null;
     let previous = null;
     if ((0, fs_1.existsSync)(settingsPath)) {

package/dist/server/src/lib/hooks/sources/codex/relay-install.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * The one path `$CODEX_HOME/hooks.json` is allowed to name (Issue #2315).
+ *
+ * ## The bug this module exists for
+ *
+ * `hooks-config` writes ONE file — `$CODEX_HOME/hooks.json` — shared by every
+ * codex session on the machine, and its whole design rests on that file being
+ * byte-identical whoever wrote it: codex keys hook trust by the hash of the
+ * handler, so a file whose bytes move puts the review dialog back in front of
+ * the next launch. `writeCodexHookSettings` already refuses to rewrite matching
+ * content, and `buildCodexHookSettings` already keeps the port, the worktree and
+ * the instance out of the file.
+ *
+ * One value got through anyway, and it is the one that moves most: the absolute
+ * path of the relay script, which `resolveRelayScriptPath()` resolves against
+ * `process.cwd()` — the checkout of the server that happened to write the file.
+ * Measured on the reporting machine on 2026-09-04, with 22 worktrees registered
+ * and several dev servers running:
+ *
+ * ```
+ * $ grep -o "'[^']*cmate-agent-event.sh'" ~/.codex/hooks.json
+ * '/Users/…/MyCodeBranchDesk/scripts/hooks/cmate-agent-event.sh'
+ * $ pwd   # a worktree server, which would rewrite it as its own
+ * /Users/…/commandmate-issue-2315
+ * ```
+ *
+ * So each server rewrites the shared file with its own checkout, every rewrite
+ * invalidates the hash the human trusted, and the next codex opens on
+ * `Trust  Modified since last trusted - review required`. The servers eat each
+ * other's trust, forever, which is the "度々" in the Issue.
+ *
+ * ## The fix
+ *
+ * Put the script where every server agrees it is: beside the hooks file it is
+ * named from, under `$CODEX_HOME/commandmate/`. Each server copies its shipped
+ * relay there (a no-op when the bytes already match) and `hooks.json` names the
+ * installed copy, so the generated file no longer contains a checkout at all —
+ * it is a function of `$CODEX_HOME` alone, which is the same directory codex
+ * reads the hooks from by construction.
+ *
+ * A server whose own copy of the script is unreachable — a global install whose
+ * `process.cwd()` is the user's shell directory — installs nothing and uses the
+ * copy that is already there, rather than falling back to the inline `curl`
+ * form and rewriting the file into a third shape.
+ *
+ * Copying the SCRIPT rather than hashing it is deliberate. codex trusts a
+ * command *string*; it cannot see what that string executes, so two servers on
+ * different versions of the script still share one trusted `hooks.json`. The
+ * newest server to start wins the script content, which is the same rule the
+ * hooks file itself has always had.
+ *
+ * @module lib/hooks/sources/codex/relay-install
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODEX_RELAY_INSTALL_BASENAME = exports.CODEX_RELAY_INSTALL_DIRNAME = void 0;
+exports.getCodexRelayInstallPath = getCodexRelayInstallPath;
+exports.getInstalledCodexRelayPath = getInstalledCodexRelayPath;
+exports.installCodexRelayScript = installCodexRelayScript;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logger_1 = require("../../../../lib/logger");
+const logger = (0, logger_1.createLogger)('lib/hooks/sources/codex/relay-install');
+/**
+ * Subdirectory of `$CODEX_HOME` this server owns.
+ *
+ * Namespaced rather than dropped beside `hooks.json` because the directory is
+ * the operator's: everything CommandMate puts there is under one name they can
+ * delete in one command, and nothing it writes can collide with a file codex
+ * itself introduces later.
+ */
+exports.CODEX_RELAY_INSTALL_DIRNAME = 'commandmate';
+/** Basename kept identical to the shipped script, so the two are recognisably one file. */
+exports.CODEX_RELAY_INSTALL_BASENAME = 'cmate-agent-event.sh';
+/** Where {@link installCodexRelayScript} puts the relay, for a given codex home. */
+function getCodexRelayInstallPath(codexHome) {
+    return (0, path_1.join)(codexHome, exports.CODEX_RELAY_INSTALL_DIRNAME, exports.CODEX_RELAY_INSTALL_BASENAME);
+}
+/**
+ * The installed relay, or null when nothing has installed one yet.
+ *
+ * Read-only, so the command builders stay free of side effects: the install
+ * itself is done once by {@link installCodexRelayScript}, from the one function
+ * that was going to touch the disk anyway.
+ */
+function getInstalledCodexRelayPath(codexHome) {
+    const target = getCodexRelayInstallPath(codexHome);
+    return (0, fs_1.existsSync)(target) ? target : null;
+}
+/**
+ * Copy the shipped relay to the stable path, and answer where codex should look.
+ *
+ * Never throws and never fails a launch: hooks are an enhancement to a session
+ * that has to start regardless, so every error path here degrades to "use
+ * whatever copy is already installed", and then to "no relay", which
+ * `buildCodexEventHookCommand` answers with its inline `curl`.
+ *
+ * Idempotent: the file is opened for writing only when the bytes differ, so the
+ * ordinary launch does not touch it. The write itself goes through a temporary
+ * file and a rename, because the file being replaced is one a *running* codex
+ * session may be executing at that moment — truncating it in place would hand
+ * that session half a script.
+ *
+ * @param codexHome - The directory `hooks.json` lives in
+ * @param sourcePath - The shipped script, or null when this process cannot find its own
+ * @returns The path to name in `hooks.json`, or null when there is none
+ */
+function installCodexRelayScript(codexHome, sourcePath) {
+    const target = getCodexRelayInstallPath(codexHome);
+    if (sourcePath && sourcePath !== target) {
+        try {
+            const desired = (0, fs_1.readFileSync)(sourcePath, 'utf8');
+            const current = (0, fs_1.existsSync)(target) ? (0, fs_1.readFileSync)(target, 'utf8') : null;
+            if (current !== desired) {
+                (0, fs_1.mkdirSync)((0, path_1.dirname)(target), { recursive: true, mode: 0o700 });
+                // `.tmp` beside the target so the rename cannot cross a filesystem.
+                const staging = `${target}.tmp`;
+                try {
+                    (0, fs_1.writeFileSync)(staging, desired, { mode: 0o700 });
+                    (0, fs_1.renameSync)(staging, target);
+                }
+                catch (error) {
+                    try {
+                        (0, fs_1.unlinkSync)(staging);
+                    }
+                    catch {
+                        // Nothing to clean up, or nothing that can be.
+                    }
+                    throw error;
+                }
+                logger.info('codex-relay-installed', { target });
+            }
+        }
+        catch (error) {
+            // An install that failed is not a launch that failed. If a previous
+            // server already put a copy there, that copy is still the right path to
+            // name — and naming it is what keeps this file byte-identical.
+            logger.warn('codex-relay-install-failed', {
+                target,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return (0, fs_1.existsSync)(target) ? target : null;
+}