commandmate 0.29.1 → 0.30.0

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,
+    };
+}

package/dist/lib/verification/verify-config.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Loader and validator for `.commandmate/verify.yaml`.
+ *
+ * Canonical spec: docs/design/verification-config.md
+ * Phase 0 reference implementation: .claude/skills/cmate-verify/scripts/verify-run.sh
+ *
+ * Server-only: reads from disk, so import this from API routes / CLI only.
+ */
+export interface VerifyGate {
+    id: string;
+    command: string;
+    timeoutSec: number;
+    /**
+     * Name of a machine-wide lock this gate must hold while it runs (Issue #1771).
+     *
+     * Declares "only one of these may run on this machine at a time", which a
+     * gate owning a fixed port, database or emulator needs and which command and
+     * timeout cannot express. Two parallel worktrees running such a gate at once
+     * make the second fail on the resource, and `GATE e2e FAIL exit=1` reads
+     * exactly like the change being broken.
+     *
+     * Optional rather than `string | null`: contracts store their gate list as
+     * JSON in `tasks.contract_json` and are read back with `JSON.parse`, never
+     * re-validated, so every row written before this field existed simply has no
+     * key — and `undefined` is the honest reading of that.
+     */
+    mutex?: string;
+    /**
+     * Re-run this gate once, in the same tree, when its command exits non-zero
+     * (Issue #1772). `1` opts in; `0` (the default) is the behaviour every gate
+     * had before this field existed.
+     *
+     * Only 0 and 1 are accepted. A gate allowed three or four attempts stops
+     * being a gate: enough re-runs turn any red into a green, and the value of
+     * this field is precisely that it cannot. One retry answers the one question
+     * worth asking — "does this reproduce in the same tree?" — and nothing more.
+     *
+     * Optional for the same reason {@link VerifyGate.mutex} is: contracts store
+     * their gate list as JSON in `tasks.contract_json` and read it back with
+     * `JSON.parse` without re-validating, so a row written before this field
+     * existed simply has no key.
+     */
+    retryOnFail?: number;
+    /**
+     * Whether a FLAKY outcome — failed, then passed on the retry — counts as a
+     * pass (Issue #1772). Default false: the gate does not get weaker by opting
+     * into a retry, it only gets a name for what happened.
+     *
+     * Declared per gate rather than per repository because it is a statement
+     * about *this* gate's failure mode. `unit` failing on a random UUID that
+     * happens to contain a forbidden substring is noise; `e2e` failing once and
+     * passing once is usually a real race in the product. An `options`-level flag
+     * would force those two into one answer, and would also be declarable for
+     * gates that never opted into a retry, where it can never fire.
+     *
+     * `true` without `retryOnFail: 1` is a config error rather than a no-op: no
+     * retry means no FLAKY, so the declaration could never take effect.
+     */
+    flakyIsPass?: boolean;
+}
+export interface VerifyOptions {
+    /** null when unset; the caller resolves the repository default branch. */
+    baseRef: string | null;
+    skipInPrimaryCheckout: boolean;
+    maxLogTailBytes: number;
+    /**
+     * Whether `work-evidence` demands a COMMIT rather than any change at all
+     * (Issue #1628, D-4). Default false — the gate's job has always been "is
+     * there work here to verify", and a dirty tree answers that.
+     *
+     * Turn it on in a repository whose delegations end in a commit (the task
+     * contract preamble tells agents "未 commit の作業は未完了とみなされる", and
+     * without this the gate happily passes `commits=0 uncommitted=1`, so
+     * `RESULT passed` proved nothing about the commit). Repository-wide by
+     * design: it is a property of how the repository is worked, not of one run.
+     */
+    requireCommit: boolean;
+    /**
+     * Whether the built-in `env-clean` gate judges this repository's runs
+     * (Issue #1740). Default false — every contract written before the gate
+     * existed must keep its verdict, and a gate that starts failing runs the day
+     * it lands is a gate that gets switched off again.
+     *
+     * Turning it on has a second effect: baselines are only recorded (at task
+     * creation) while it is on, because a snapshot of the machine is a side effect
+     * and the off state must have none. A run without a baseline reports UNKNOWN,
+     * never a pass.
+     */
+    requireEnvClean: boolean;
+}
+export interface VerifyConfig {
+    version: 1;
+    gates: VerifyGate[];
+    options: VerifyOptions;
+}
+/**
+ * Built-in gate that answers "is there any work here to verify?".
+ *
+ * Declared here rather than in the runner so modules that only reason *about*
+ * gate selection (task contracts) can name it without importing the engine.
+ */
+export declare const WORK_EVIDENCE_GATE_ID = "work-evidence";
+/**
+ * Built-in gate that reconciles the changed files against the contract's
+ * `scope.allow` / `scope.deny` (#1546). Declared alongside work-evidence for the
+ * same reason: `lib/tasks/contract-message.ts` has to name it while resolving a
+ * contract's gate list, and must not pull the engine in to do so.
+ */
+export declare const SCOPE_GATE_ID = "scope";
+/**
+ * Built-in gate that reconciles the *machine* against the snapshot taken when
+ * the task was created (#1740): listening CommandMate servers, `mcbd-*` tmux
+ * sessions, `$HOME` and `~/.commandmate`. `scope` answers what a delegation
+ * changed inside the repository; this answers what it changed outside one.
+ */
+export declare const ENV_CLEAN_GATE_ID = "env-clean";
+/** Gate IDs reserved for built-in gates; using one in `gates` is a config error. */
+export declare const RESERVED_GATE_IDS: readonly ["work-evidence", "scope", "env-clean"];
+export declare const VERIFY_CONFIG_RELATIVE_PATH = ".commandmate/verify.yaml";
+/**
+ * Gate ids a default full run executes, in the order the runner records them
+ * (Issue #2061).
+ *
+ * The Verification pane needs a denominator while a run is in flight — gate
+ * rows are created as each gate starts, so "3 gates recorded" is progress, not
+ * a total. Declared here rather than in the pane because the composition is the
+ * runner's: `work-evidence`, then `scope`, then `env-clean` only when a
+ * declaration switched it on, then verify.yaml's own gates in file order.
+ *
+ * A *default* run, which is what the pane's "run verification" button starts.
+ * A run narrowed with `--gates` / `gateIds` executes a subset of this.
+ *
+ * @param contractGates gate definitions the worktree's execution contract
+ *        carries (#1791). They run after verify.yaml's, exactly as
+ *        `declaredGates()` orders them, and leaving them out understated both
+ *        the pane's progress denominator and — since #2063 made the list
+ *        selectable — which gates an operator is allowed to re-run: a run whose
+ *        only failure was a contract gate offered nothing to re-run at all.
+ */
+export declare function defaultPlannedGateIds(config: VerifyConfig, contractGates?: readonly VerifyGate[]): string[];
+export declare const DEFAULT_TIMEOUT_SEC = 600;
+export declare const DEFAULT_MAX_LOG_TAIL_BYTES = 8192;
+/**
+ * Shape a gate id may take, wherever a gate is declared.
+ *
+ * Exported because the task contract declares gates too (#1791) and names them
+ * in `verify.gates`. A second copy of this expression would let the two
+ * declaration sites drift into accepting different ids, and a contract gate the
+ * runner refuses to resolve is a completion criterion nothing can evaluate.
+ */
+export declare const GATE_ID_PATTERN: RegExp;
+/**
+ * Shape a `mutex` name may take (Issue #1771).
+ *
+ * Wider than {@link GATE_ID_PATTERN} because a mutex names a *resource*, not a
+ * gate: two repositories that both bind port 60303 should be able to agree on
+ * `port.60303` and be serialized against each other. Narrow enough that the
+ * name is safe as a path segment — no separator, no whitespace, nothing a shell
+ * re-interprets — because both runners turn it into
+ * `~/.commandmate/locks/<name>.lock`.
+ */
+export declare const GATE_MUTEX_PATTERN: RegExp;
+/** Keeps the lock directory name inside every filesystem's limit. */
+export declare const MAX_GATE_MUTEX_LENGTH = 64;
+/**
+ * Largest `retryOnFail` a gate may declare (Issue #1772).
+ *
+ * Deliberately 1, and deliberately a named constant rather than a literal in
+ * one `if`: the ceiling is the feature. A gate that may re-run until it passes
+ * reports the machine's luck, not the work.
+ */
+export declare const MAX_RETRY_ON_FAIL = 1;
+export declare class VerifyConfigError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/**
+ * Validate a list of `{ id, command, timeoutSec }` entries.
+ *
+ * Shared with the task contract's `verify.gateDefinitions` (#1791), which
+ * declares gates in the same shape and must be held to the same constraints —
+ * id pattern, reserved ids, duplicates, integer timeout in range. Calling this
+ * is what makes "the same constraints" a fact rather than a comment: a contract
+ * gate accepted here is one the runner can execute and the report can name.
+ *
+ * Deliberately does *not* decide whether the list may be absent or empty. That
+ * is the caller's rule: verify.yaml requires at least one gate, a contract that
+ * declares none is the normal case.
+ *
+ * @param at path prefix for issue messages (`gates`, `verify.gateDefinitions`)
+ * @returns the accepted entries; an entry that produced an issue is dropped so
+ *          the result never carries a value that failed validation
+ */
+export declare function validateGateEntries(value: unknown, at: string, issues: string[]): VerifyGate[];
+/**
+ * Read and validate `<repoPath>/.commandmate/verify.yaml`.
+ *
+ * @returns the validated config, or null when the file does not exist
+ * @throws VerifyConfigError with every violation collected in `issues`
+ */
+export declare function loadVerifyConfig(repoPath: string): VerifyConfig | null;
+//# sourceMappingURL=verify-config.d.ts.map

package/dist/lib/verification/verify-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-config.d.ts","sourceRoot":"","sources":["../../../src/lib/verification/verify-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;OAUG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,kDAIpB,CAAC;AAEX,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,aAAa,GAAE,SAAS,UAAU,EAAO,GACxC,MAAM,EAAE,CAWV;AAED,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAM/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAA8B,CAAC;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAYnC,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE;CAK7B;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAe9F;AA2OD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAYtE"}