commandmate 0.29.0 → 0.29.2

package/dist/lib/updates/agent-versions.d.ts

@@ -0,0 +1,77 @@
+/**
+ * "Which agent CLIs are installed, and is codex behind?" (Issue #2069)
+ *
+ * One row per tool for the two update surfaces — the More screen's card and the
+ * agent pane's — and the split in what a row carries is deliberate:
+ *
+ *  - **every tool reports `installed` only.** That is this Issue's 実装内容 2:
+ *    the probe table already exists, it answers without a network, and
+ *    "installed 1.0.80" is the whole truth CommandMate has about a copilot.
+ *  - **codex additionally reports `latestVersion` / `updateAvailable`**, because
+ *    codex is the one tool that writes its own release check to disk. See
+ *    `./codex-version`.
+ *
+ * Nothing here queries a registry. A row that says `updateAvailable: false` is
+ * saying "nothing on this machine claims otherwise", never "I checked online".
+ *
+ * ## Why not `getDetectorFreshness()`
+ *
+ * It answers a different question (are the *detector's rules* stale?) and — the
+ * reason that matters here — it caches for the life of the process. This module
+ * is read immediately after an update completes, so a permanent memo would show
+ * the old version forever and make the acceptance criterion 「完了後に
+ * `codex --version` が上がる」 unobservable from the UI. So the probes are run
+ * through the same `runDetectorVersionProbe` (same absolute-path resolution,
+ * same sanitized env, same timeout) behind a **TTL** instead, on the reasoning
+ * `config/installed-agents-cache` already wrote down: the user's loop is
+ * "install something, come back, look again".
+ *
+ * @module lib/updates/agent-versions
+ */
+/**
+ * How long one fan-out of `--version` probes is reused.
+ *
+ * Same 30s as `config/installed-agents-cache`, and for the same reason: opening
+ * a screen twice in a row costs one fan-out, while a version that changed under
+ * the server shows up without a restart. An update finishing calls
+ * {@link clearAgentVersionsCache} rather than waiting this out.
+ */
+export declare const AGENT_VERSIONS_CACHE_TTL_MS = 30000;
+/** One tool's version row, as the API publishes it. */
+export interface AgentVersionRow {
+    /** Catalog / `CLIToolType` id. */
+    tool: string;
+    /** What `--version` reported, or null when the tool is not on PATH. */
+    installed: string | null;
+    /** codex only: its own `latest_version`. Null for every other tool. */
+    latestVersion: string | null;
+    /** codex only: its own `dismissed_version`. Null for every other tool. */
+    dismissedVersion: string | null;
+    /** True only when a newer version is known AND the tool is installed. */
+    updateAvailable: boolean;
+    /** True when the available update is one the user dismissed inside codex. */
+    dismissedInCodex: boolean;
+    /** Whether CommandMate has an update flow for this tool at all. */
+    updatable: boolean;
+    /** Where `latestVersion` came from, or null when nothing said. */
+    source: 'version.json' | null;
+}
+/**
+ * Every tool's version row, cached for {@link AGENT_VERSIONS_CACHE_TTL_MS}.
+ *
+ * Single-flight: two concurrent callers share one fan-out rather than doubling
+ * the child processes.
+ *
+ * @param options.force - Skip the cache and re-probe. What the UI passes right
+ *   after an update, so the new version is visible without a 30s wait.
+ * @param options.now - Injectable clock, used for BOTH the expiry comparison
+ *   and the expiry that is written. Honouring it on only one side would leave
+ *   the TTL untestable — see {@link expiryFrom}.
+ */
+export declare function getAgentVersions(options?: {
+    force?: boolean;
+    now?: number;
+}): Promise<AgentVersionRow[]>;
+/** Drop the cached probe. Tests, and every surface that just ran an update. */
+export declare function clearAgentVersionsCache(): void;
+//# sourceMappingURL=agent-versions.d.ts.map

package/dist/lib/updates/agent-versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-versions.d.ts","sourceRoot":"","sources":["../../../src/lib/updates/agent-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAMH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uEAAuE;IACvE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,yEAAyE;IACzE,eAAe,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AA2DD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,eAAe,EAAE,CAAC,CA2B5B;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/dist/lib/updates/agent-versions.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * "Which agent CLIs are installed, and is codex behind?" (Issue #2069)
+ *
+ * One row per tool for the two update surfaces — the More screen's card and the
+ * agent pane's — and the split in what a row carries is deliberate:
+ *
+ *  - **every tool reports `installed` only.** That is this Issue's 実装内容 2:
+ *    the probe table already exists, it answers without a network, and
+ *    "installed 1.0.80" is the whole truth CommandMate has about a copilot.
+ *  - **codex additionally reports `latestVersion` / `updateAvailable`**, because
+ *    codex is the one tool that writes its own release check to disk. See
+ *    `./codex-version`.
+ *
+ * Nothing here queries a registry. A row that says `updateAvailable: false` is
+ * saying "nothing on this machine claims otherwise", never "I checked online".
+ *
+ * ## Why not `getDetectorFreshness()`
+ *
+ * It answers a different question (are the *detector's rules* stale?) and — the
+ * reason that matters here — it caches for the life of the process. This module
+ * is read immediately after an update completes, so a permanent memo would show
+ * the old version forever and make the acceptance criterion 「完了後に
+ * `codex --version` が上がる」 unobservable from the UI. So the probes are run
+ * through the same `runDetectorVersionProbe` (same absolute-path resolution,
+ * same sanitized env, same timeout) behind a **TTL** instead, on the reasoning
+ * `config/installed-agents-cache` already wrote down: the user's loop is
+ * "install something, come back, look again".
+ *
+ * @module lib/updates/agent-versions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_VERSIONS_CACHE_TTL_MS = void 0;
+exports.getAgentVersions = getAgentVersions;
+exports.clearAgentVersionsCache = clearAgentVersionsCache;
+const version_probes_1 = require("../detection/version-probes");
+const codex_version_1 = require("./codex-version");
+const agent_updater_1 = require("./agent-updater");
+/**
+ * How long one fan-out of `--version` probes is reused.
+ *
+ * Same 30s as `config/installed-agents-cache`, and for the same reason: opening
+ * a screen twice in a row costs one fan-out, while a version that changed under
+ * the server shows up without a restart. An update finishing calls
+ * {@link clearAgentVersionsCache} rather than waiting this out.
+ */
+exports.AGENT_VERSIONS_CACHE_TTL_MS = 30_000;
+let cache = null;
+let inFlight = null;
+/** Probe one tool and build its row. codex gets the extra half. */
+async function buildRow(tool) {
+    const installed = await (0, version_probes_1.runDetectorVersionProbe)(version_probes_1.DETECTOR_VERSION_PROBES[tool]);
+    const updatable = (0, agent_updater_1.isUpdatableAgentTool)(tool);
+    if (tool !== 'codex') {
+        return {
+            tool,
+            installed,
+            latestVersion: null,
+            dismissedVersion: null,
+            updateAvailable: false,
+            dismissedInCodex: false,
+            updatable,
+            source: null,
+        };
+    }
+    const status = (0, codex_version_1.evaluateCodexUpdate)(installed, (0, codex_version_1.readCodexVersionFile)());
+    return {
+        tool,
+        installed: status.installed,
+        latestVersion: status.latestVersion,
+        dismissedVersion: status.dismissedVersion,
+        updateAvailable: status.updateAvailable,
+        dismissedInCodex: status.dismissedInCodex,
+        updatable,
+        source: status.source,
+    };
+}
+async function computeRows() {
+    const tools = Object.keys(version_probes_1.DETECTOR_VERSION_PROBES).sort();
+    return Promise.all(tools.map(buildRow));
+}
+/**
+ * When a fan-out started at `startedAt` should stop being reused.
+ *
+ * Takes the caller's clock rather than reading `Date.now()` again, and that is
+ * the whole point of the helper: an injected `now` that is honoured on the READ
+ * side but ignored on the WRITE side makes every TTL assertion vacuous — the
+ * cache is stamped with a real epoch, a test's `now: 2_000` is smaller than it
+ * whatever the TTL is, and `AGENT_VERSIONS_CACHE_TTL_MS = 0` still passes.
+ */
+function expiryFrom(startedAt) {
+    return startedAt + exports.AGENT_VERSIONS_CACHE_TTL_MS;
+}
+/**
+ * Every tool's version row, cached for {@link AGENT_VERSIONS_CACHE_TTL_MS}.
+ *
+ * Single-flight: two concurrent callers share one fan-out rather than doubling
+ * the child processes.
+ *
+ * @param options.force - Skip the cache and re-probe. What the UI passes right
+ *   after an update, so the new version is visible without a 30s wait.
+ * @param options.now - Injectable clock, used for BOTH the expiry comparison
+ *   and the expiry that is written. Honouring it on only one side would leave
+ *   the TTL untestable — see {@link expiryFrom}.
+ */
+async function getAgentVersions(options = {}) {
+    const now = options.now ?? Date.now();
+    if (options.force) {
+        cache = null;
+    }
+    else if (cache && cache.expiresAt > now) {
+        return cache.rows;
+    }
+    if (inFlight)
+        return inFlight;
+    inFlight = (async () => {
+        try {
+            const rows = await computeRows();
+            cache = { rows, expiresAt: expiryFrom(now) };
+            return rows;
+        }
+        catch {
+            // A probe fan-out that throws must not fail the surface that asked: the
+            // versions are an annotation, and an empty list renders as "unknown".
+            cache = { rows: [], expiresAt: expiryFrom(now) };
+            return [];
+        }
+        finally {
+            inFlight = null;
+        }
+    })();
+    return inFlight;
+}
+/** Drop the cached probe. Tests, and every surface that just ran an update. */
+function clearAgentVersionsCache() {
+    cache = null;
+    inFlight = null;
+}

package/dist/lib/updates/codex-version.d.ts

@@ -0,0 +1,184 @@
+/**
+ * `~/.codex/version.json` — what codex itself already knows about its updates
+ * (Issue #2069).
+ *
+ * ## Why a file rather than a request
+ *
+ * codex runs its own release check and writes the answer next to its config:
+ *
+ * ```json
+ * {"latest_version":"0.151.0","last_checked_at":"2026-08-30T15:12:18.082219Z","dismissed_version":null}
+ * ```
+ *
+ * So "is there a newer codex?" is answerable with a `readFileSync` and no
+ * network at all. That is the whole reason this module exists rather than a
+ * registry query: `GET /api/agents/versions` is rendered on a settings screen
+ * and inside the agent pane, and #1913's rule — do not put a network round trip
+ * on a surface that renders a list — applies to a fetch exactly as it applies to
+ * a child process. The trade is that the answer is only as fresh as the last
+ * time codex itself looked, which is the correct freshness: it is codex's own
+ * notion of "you are behind", the same one its TUI banner uses.
+ *
+ * ## Fail-open, in every direction
+ *
+ * The file is written by another program, on its own schedule, in a format it
+ * owns. It is legitimately **absent** (a fresh install, a codex that has never
+ * run), legitimately **null-valued** (`dismissed_version` is null until the user
+ * dismisses a banner), and it can be a half-written temp file caught mid-rename.
+ * None of those is an error here: every failure resolves to
+ * {@link EMPTY_CODEX_VERSION_FILE} and the caller reports "no update known",
+ * which is exactly what the surfaces render when codex is not installed either.
+ * The acceptance criterion for this Issue names that behaviour directly —
+ * 「`version.json` が無い / 壊れている環境で落ちない」— and
+ * `tests/unit/updates/codex-version-2069.test.ts` pins it case by case.
+ *
+ * ## `$CODEX_HOME`: why it is resolved here, and where the two rules diverge
+ *
+ * `lib/hooks/sources/codex/hooks-config.getCodexHome()` answers the same
+ * question, and this module cannot call it: that function reaches `@/lib/logger`
+ * through `config/safe-directory`, and `tsconfig.cli.json` resets `"paths"` to
+ * `{}` — so one alias import anywhere in this module's transitive closure breaks
+ * `npm run build:cli` with TS2307 (the #1933 defect PR #1991 fixed), and
+ * `commandmate agents update` puts this file in the CLI's closure. The variable
+ * NAME therefore exists in two files, and
+ * `tests/unit/updates/codex-home-parity-2069.test.ts` is the join: it imports
+ * both and fails if the spellings or the shared rules ever drift.
+ *
+ * The rules are deliberately identical except for one case, and that case is a
+ * correctness fix rather than a divergence for its own sake:
+ *
+ * | `$CODEX_HOME`            | hooks-config                        | here                |
+ * |--------------------------|-------------------------------------|---------------------|
+ * | unset                    | `~/.codex`                          | `~/.codex`          |
+ * | absolute                 | that path                           | that path           |
+ * | inside `/proc`/`/sys`/`/dev` | `~/.codex` (#1774)              | `~/.codex`          |
+ * | **relative**             | passed through **verbatim**         | **null = unknown**  |
+ *
+ * `resolveSafeDirectory` returns a relative candidate unchanged, and
+ * `hooks-config` puts that value on codex's own launch line — so codex resolves
+ * it against **the agent's worktree cwd**, and `CODEX_HOME=.codex-shared` means
+ * codex writes `<worktree>/.codex-shared/version.json`. This process is not in
+ * that worktree and, with several worktrees open, cannot say which one was
+ * meant. Falling back to `~/.codex` there is the one genuinely bad answer: it
+ * is not "no data", it is an unrelated install's version, reported with the
+ * same confidence as a real reading. So a relative value resolves to null and
+ * every surface renders "no update information", which is what they already
+ * render when codex has never run.
+ *
+ * @module lib/updates/codex-version
+ */
+/**
+ * The one thing this module reads out of the environment.
+ *
+ * Narrower than `NodeJS.ProcessEnv` on purpose: vitest's type augmentation
+ * makes `NODE_ENV` REQUIRED on that interface, so a test could not hand these
+ * functions a two-key literal without also declaring a `NODE_ENV` that has
+ * nothing to do with what is being tested.
+ */
+export type CodexVersionEnv = Readonly<Record<string, string | undefined>>;
+/** The file codex writes its release check into, inside `$CODEX_HOME`. */
+export declare const CODEX_VERSION_FILENAME = "version.json";
+/**
+ * Largest `version.json` this module will parse.
+ *
+ * Three short fields; anything past this is not the file we mean. A cap rather
+ * than trust because the read happens on a request path and the file is written
+ * by another process — an oversized file is discarded, not truncated and parsed.
+ */
+export declare const CODEX_VERSION_FILE_MAX_BYTES: number;
+/** What {@link readCodexVersionFile} could recover from the file. */
+export interface CodexVersionFile {
+    /** `latest_version`, normalized to `major.minor.patch`, or null. */
+    latestVersion: string | null;
+    /** `dismissed_version`, normalized, or null (the ordinary value). */
+    dismissedVersion: string | null;
+    /** `last_checked_at` verbatim — an opaque timestamp string, or null. */
+    lastCheckedAt: string | null;
+    /**
+     * Absolute path that was read, or null when `$CODEX_HOME` is relative and the
+     * file's location therefore depends on a worktree this process cannot name.
+     */
+    path: string | null;
+    /** False when the file was missing, oversized, unreadable or malformed. */
+    readable: boolean;
+}
+/** The answer for every failure: "codex has told us nothing". */
+export declare const EMPTY_CODEX_VERSION_FILE: Omit<CodexVersionFile, 'path'>;
+/**
+ * The directory codex keeps its state in, as seen from THIS process.
+ *
+ * See the table in the module header for the four cases. The one that returns
+ * null is a relative `$CODEX_HOME`: `hooks-config` forwards such a value to
+ * codex verbatim, codex resolves it against the agent's worktree cwd, and this
+ * process has no worktree — so the honest answer is "cannot tell", not
+ * `~/.codex`.
+ *
+ * @param env - Environment to read. Injectable so tests need no `process.env`
+ *   mutation.
+ * @returns An absolute directory path, or null when it cannot be determined.
+ */
+export declare function getCodexHomeForVersionRead(env?: CodexVersionEnv): string | null;
+/**
+ * Absolute path of the file codex writes its release check into, or null when
+ * {@link getCodexHomeForVersionRead} cannot determine the directory.
+ */
+export declare function getCodexVersionFilePath(env?: CodexVersionEnv): string | null;
+/**
+ * Read `$CODEX_HOME/version.json`.
+ *
+ * Never throws and never rejects: see the module header. A file that parses but
+ * carries junk in a field yields null for **that field only**, so a codex build
+ * that adds or renames a key still gives up whatever the rest of it says.
+ *
+ * @param options.path - Read this file instead of the resolved default (tests,
+ *   and an isolated-HOME verification run).
+ * @param options.env - Environment used to resolve the default path.
+ */
+export declare function readCodexVersionFile(options?: {
+    path?: string;
+    env?: CodexVersionEnv;
+}): CodexVersionFile;
+/** What the two update surfaces render for codex. */
+export interface CodexUpdateStatus {
+    /** What `codex --version` reported, or null when it is not installed. */
+    installed: string | null;
+    /** codex's own `latest_version`, or null when it has not looked. */
+    latestVersion: string | null;
+    /** codex's own `dismissed_version`, or null. */
+    dismissedVersion: string | null;
+    /** True only when BOTH versions are known AND latest is strictly newer. */
+    updateAvailable: boolean;
+    /**
+     * True when `dismissed_version` names the update that is available — i.e.
+     * **something** answered codex's update banner with "not this version".
+     *
+     * **Not necessarily the user.** The digit that writes `dismissed_version` is
+     * the same one CommandMate can be configured to send for codex's in-pane
+     * update dialog (#2068, `CM_CODEX_UPDATE_DIALOG`), and on the default policy
+     * CommandMate sends it on every codex launch. So on a stock install this flag
+     * goes true without anybody having decided anything, and wording that says
+     * "you dismissed this" would be blaming the user for the server's own
+     * automatic answer.
+     *
+     * That is why it is reported and never acted on: it does not hide the update,
+     * it does not disable the button, and the copy beside it
+     * (`common.agentUpdates.dismissed`) says only that the version was dismissed
+     * in codex — without naming who did it.
+     */
+    dismissedInCodex: boolean;
+    /** Where the "latest" half came from, or null when nothing was readable. */
+    source: 'version.json' | null;
+}
+/**
+ * Combine the installed version with codex's own release check.
+ *
+ * Both halves are "no answer"-tolerant, and every kind of no-answer resolves to
+ * `updateAvailable: false` — not installed, never checked, unparseable. That is
+ * the same posture `DetectorFreshnessRow.stale` takes, and for the same reason:
+ * an update prompt the user cannot act on is worse than no prompt.
+ *
+ * @param installed - Output of the `codex --version` probe, or null.
+ * @param file - What {@link readCodexVersionFile} recovered.
+ */
+export declare function evaluateCodexUpdate(installed: string | null, file: CodexVersionFile): CodexUpdateStatus;
+//# sourceMappingURL=codex-version.d.ts.map

package/dist/lib/updates/codex-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-version.d.ts","sourceRoot":"","sources":["../../../src/lib/updates/codex-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAQH;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAa3E,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,QAAY,CAAC;AAEtD,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wEAAwE;IACxE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,iEAAiE;AACjE,eAAO,MAAM,wBAAwB,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAKnE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,eAA6B,GAAG,MAAM,GAAG,IAAI,CAS5F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,eAA6B,GAAG,MAAM,GAAG,IAAI,CAGzF;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,eAAe,CAAA;CAAO,GACrD,gBAAgB,CA2BlB;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oEAAoE;IACpE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2EAA2E;IAC3E,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,4EAA4E;IAC5E,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,EAAE,gBAAgB,GACrB,iBAAiB,CAiBnB"}

package/dist/lib/updates/codex-version.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * `~/.codex/version.json` — what codex itself already knows about its updates
+ * (Issue #2069).
+ *
+ * ## Why a file rather than a request
+ *
+ * codex runs its own release check and writes the answer next to its config:
+ *
+ * ```json
+ * {"latest_version":"0.151.0","last_checked_at":"2026-08-30T15:12:18.082219Z","dismissed_version":null}
+ * ```
+ *
+ * So "is there a newer codex?" is answerable with a `readFileSync` and no
+ * network at all. That is the whole reason this module exists rather than a
+ * registry query: `GET /api/agents/versions` is rendered on a settings screen
+ * and inside the agent pane, and #1913's rule — do not put a network round trip
+ * on a surface that renders a list — applies to a fetch exactly as it applies to
+ * a child process. The trade is that the answer is only as fresh as the last
+ * time codex itself looked, which is the correct freshness: it is codex's own
+ * notion of "you are behind", the same one its TUI banner uses.
+ *
+ * ## Fail-open, in every direction
+ *
+ * The file is written by another program, on its own schedule, in a format it
+ * owns. It is legitimately **absent** (a fresh install, a codex that has never
+ * run), legitimately **null-valued** (`dismissed_version` is null until the user
+ * dismisses a banner), and it can be a half-written temp file caught mid-rename.
+ * None of those is an error here: every failure resolves to
+ * {@link EMPTY_CODEX_VERSION_FILE} and the caller reports "no update known",
+ * which is exactly what the surfaces render when codex is not installed either.
+ * The acceptance criterion for this Issue names that behaviour directly —
+ * 「`version.json` が無い / 壊れている環境で落ちない」— and
+ * `tests/unit/updates/codex-version-2069.test.ts` pins it case by case.
+ *
+ * ## `$CODEX_HOME`: why it is resolved here, and where the two rules diverge
+ *
+ * `lib/hooks/sources/codex/hooks-config.getCodexHome()` answers the same
+ * question, and this module cannot call it: that function reaches `@/lib/logger`
+ * through `config/safe-directory`, and `tsconfig.cli.json` resets `"paths"` to
+ * `{}` — so one alias import anywhere in this module's transitive closure breaks
+ * `npm run build:cli` with TS2307 (the #1933 defect PR #1991 fixed), and
+ * `commandmate agents update` puts this file in the CLI's closure. The variable
+ * NAME therefore exists in two files, and
+ * `tests/unit/updates/codex-home-parity-2069.test.ts` is the join: it imports
+ * both and fails if the spellings or the shared rules ever drift.
+ *
+ * The rules are deliberately identical except for one case, and that case is a
+ * correctness fix rather than a divergence for its own sake:
+ *
+ * | `$CODEX_HOME`            | hooks-config                        | here                |
+ * |--------------------------|-------------------------------------|---------------------|
+ * | unset                    | `~/.codex`                          | `~/.codex`          |
+ * | absolute                 | that path                           | that path           |
+ * | inside `/proc`/`/sys`/`/dev` | `~/.codex` (#1774)              | `~/.codex`          |
+ * | **relative**             | passed through **verbatim**         | **null = unknown**  |
+ *
+ * `resolveSafeDirectory` returns a relative candidate unchanged, and
+ * `hooks-config` puts that value on codex's own launch line — so codex resolves
+ * it against **the agent's worktree cwd**, and `CODEX_HOME=.codex-shared` means
+ * codex writes `<worktree>/.codex-shared/version.json`. This process is not in
+ * that worktree and, with several worktrees open, cannot say which one was
+ * meant. Falling back to `~/.codex` there is the one genuinely bad answer: it
+ * is not "no data", it is an unrelated install's version, reported with the
+ * same confidence as a real reading. So a relative value resolves to null and
+ * every surface renders "no update information", which is what they already
+ * render when codex has never run.
+ *
+ * @module lib/updates/codex-version
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_CODEX_VERSION_FILE = exports.CODEX_VERSION_FILE_MAX_BYTES = exports.CODEX_VERSION_FILENAME = void 0;
+exports.getCodexHomeForVersionRead = getCodexHomeForVersionRead;
+exports.getCodexVersionFilePath = getCodexVersionFilePath;
+exports.readCodexVersionFile = readCodexVersionFile;
+exports.evaluateCodexUpdate = evaluateCodexUpdate;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const system_directories_1 = require("../../config/system-directories");
+const version_probes_1 = require("../detection/version-probes");
+/**
+ * codex's own config-directory override.
+ *
+ * NOT exported: `lib/hooks/sources/codex/hooks-config` already exports this name
+ * and that one is the repository's single public spelling. A second exported
+ * `CODEX_HOME_ENV_VAR` is how two modules end up disagreeing about it, and the
+ * `@/`-import rule above is the only reason the literal exists twice at all.
+ * `tests/unit/updates/codex-home-parity-2069.test.ts` pins the two together.
+ */
+const CODEX_HOME_ENV_VAR = 'CODEX_HOME';
+/** The file codex writes its release check into, inside `$CODEX_HOME`. */
+exports.CODEX_VERSION_FILENAME = 'version.json';
+/**
+ * Largest `version.json` this module will parse.
+ *
+ * Three short fields; anything past this is not the file we mean. A cap rather
+ * than trust because the read happens on a request path and the file is written
+ * by another process — an oversized file is discarded, not truncated and parsed.
+ */
+exports.CODEX_VERSION_FILE_MAX_BYTES = 64 * 1024;
+/** The answer for every failure: "codex has told us nothing". */
+exports.EMPTY_CODEX_VERSION_FILE = {
+    latestVersion: null,
+    dismissedVersion: null,
+    lastCheckedAt: null,
+    readable: false,
+};
+/**
+ * The directory codex keeps its state in, as seen from THIS process.
+ *
+ * See the table in the module header for the four cases. The one that returns
+ * null is a relative `$CODEX_HOME`: `hooks-config` forwards such a value to
+ * codex verbatim, codex resolves it against the agent's worktree cwd, and this
+ * process has no worktree — so the honest answer is "cannot tell", not
+ * `~/.codex`.
+ *
+ * @param env - Environment to read. Injectable so tests need no `process.env`
+ *   mutation.
+ * @returns An absolute directory path, or null when it cannot be determined.
+ */
+function getCodexHomeForVersionRead(env = process.env) {
+    const fallback = (0, path_1.join)((0, os_1.homedir)(), '.codex');
+    const configured = env[CODEX_HOME_ENV_VAR];
+    if (!configured)
+        return fallback;
+    // Matches `resolveSafeDirectory`: a /proc, /sys or /dev path is refused and
+    // the built-in default is used, on both sides of the join.
+    if ((0, system_directories_1.isVirtualFilesystemPath)(configured))
+        return fallback;
+    if (!(0, path_1.isAbsolute)(configured))
+        return null;
+    return configured;
+}
+/**
+ * Absolute path of the file codex writes its release check into, or null when
+ * {@link getCodexHomeForVersionRead} cannot determine the directory.
+ */
+function getCodexVersionFilePath(env = process.env) {
+    const home = getCodexHomeForVersionRead(env);
+    return home === null ? null : (0, path_1.join)(home, exports.CODEX_VERSION_FILENAME);
+}
+/** Read one field as a normalized version, tolerating null / wrong types. */
+function readVersionField(raw, key) {
+    const value = raw[key];
+    if (typeof value !== 'string')
+        return null;
+    return (0, version_probes_1.parseCliVersion)(value);
+}
+/**
+ * Read `$CODEX_HOME/version.json`.
+ *
+ * Never throws and never rejects: see the module header. A file that parses but
+ * carries junk in a field yields null for **that field only**, so a codex build
+ * that adds or renames a key still gives up whatever the rest of it says.
+ *
+ * @param options.path - Read this file instead of the resolved default (tests,
+ *   and an isolated-HOME verification run).
+ * @param options.env - Environment used to resolve the default path.
+ */
+function readCodexVersionFile(options = {}) {
+    const path = options.path ?? getCodexVersionFilePath(options.env);
+    const empty = { ...exports.EMPTY_CODEX_VERSION_FILE, path };
+    // Unknown directory (a relative `$CODEX_HOME`): read nothing rather than read
+    // the wrong install's file. See the table in the module header.
+    if (path === null)
+        return empty;
+    try {
+        const stat = (0, fs_1.statSync)(path);
+        if (!stat.isFile())
+            return empty;
+        if (stat.size > exports.CODEX_VERSION_FILE_MAX_BYTES)
+            return empty;
+        const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return empty;
+        const raw = parsed;
+        return {
+            latestVersion: readVersionField(raw, 'latest_version'),
+            dismissedVersion: readVersionField(raw, 'dismissed_version'),
+            lastCheckedAt: typeof raw.last_checked_at === 'string' ? raw.last_checked_at : null,
+            path,
+            readable: true,
+        };
+    }
+    catch {
+        return empty;
+    }
+}
+/**
+ * Combine the installed version with codex's own release check.
+ *
+ * Both halves are "no answer"-tolerant, and every kind of no-answer resolves to
+ * `updateAvailable: false` — not installed, never checked, unparseable. That is
+ * the same posture `DetectorFreshnessRow.stale` takes, and for the same reason:
+ * an update prompt the user cannot act on is worse than no prompt.
+ *
+ * @param installed - Output of the `codex --version` probe, or null.
+ * @param file - What {@link readCodexVersionFile} recovered.
+ */
+function evaluateCodexUpdate(installed, file) {
+    const updateAvailable = installed !== null &&
+        file.latestVersion !== null &&
+        (0, version_probes_1.compareCliVersions)(file.latestVersion, installed) > 0;
+    return {
+        installed,
+        latestVersion: file.latestVersion,
+        dismissedVersion: file.dismissedVersion,
+        updateAvailable,
+        dismissedInCodex: updateAvailable &&
+            file.dismissedVersion !== null &&
+            file.dismissedVersion === file.latestVersion,
+        source: file.readable ? 'version.json' : null,
+    };
+}