commandmate 0.29.0 → 0.29.2

package/dist/server/src/lib/detection/version-probes.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * `DETECTOR_VERSION_PROBES` — are the detector's rules still describing the CLI
+ * that is installed? (Issue #1929, 方針書 §4 D2 / §7 / §10.11 / §13.2 S17)
+ *
+ * Every rule in `src/lib/detection/tools/` was read off a capture of one build
+ * of one CLI. `tools/verified-against.ts` records which build. This module reads
+ * the other half of the comparison — the version that is installed right now —
+ * so `capture --json` and `commandmate status` can say "these rules were
+ * measured against copilot 1.0.80 and you are running 1.2.0" instead of leaving
+ * a reader to guess whether a misdetection is a bug or a version skew.
+ *
+ * ## The cost rules, and why they are not optional
+ *
+ * `capture --json` and `GET /current-output` are the **5-second polling path** —
+ * the monitor skills run them with no iteration cap. A probe table that spawns
+ * six children cannot sit on that path, so (DR3-013):
+ *
+ *  - probes run **once per process**, concurrent first callers share the same
+ *    in-flight promise, and the result is cached;
+ *  - {@link getDetectorStalenessSnapshot} **never awaits a child process**. It
+ *    answers from the cache or answers `undefined` and starts the probe in the
+ *    background. `undefined` means "not known yet", never "nothing is stale":
+ *    the hint is additive, so a poll that lands cold simply shows nothing and
+ *    the next one shows the banner;
+ *  - {@link getDetectorFreshness} is the awaiting form, for the two callers that
+ *    genuinely want the answer (`commandmate status`, `check:detector-freshness`)
+ *    and are operator-initiated one-offs.
+ *
+ * ## The execution rules (DR4-010 / §10.11)
+ *
+ * `PATH` is untrusted input: the server's `PATH` comes from the shell that
+ * started it, and a repo-local `node_modules/.bin` on it would let opening a
+ * worktree decide which binary a cold probe runs. So every `execFile` probe
+ * resolves its command to an **absolute path** through
+ * {@link findExecutableOnPath} first and **skips entirely** — spawning nothing —
+ * when that resolves to nothing; children run with `sanitizeEnvForChildProcess()`
+ * so no probe ever sees CommandMate's auth token or DB path; and both `timeout`
+ * and `maxBuffer` are explicit.
+ *
+ * ## copilot is delegated, and must stay delegated (S17)
+ *
+ * The design policy's first draft probed `gh copilot -- --version`. It cannot be
+ * used: `copilot` is not a gh extension but a preview command built into gh
+ * 2.86.0, and gh's own help says that when `PATH` has no copilot it
+ * **downloads** the CLI into `~/.local/share/gh/copilot`. A version hint that
+ * installs software is not a version hint. #1907 measured this and built
+ * {@link resolveCopilotExecutable}; #1913 wired it into the catalog's
+ * `VERSION_PROBES` as `kind: 'delegated'`; this table reuses the same shape.
+ *
+ * Delegating is not an exception to DR4-010 (1) — it satisfies it more strongly
+ * than an `execFile` row could, because `CopilotTool.isInstalled()` and
+ * `startSession()` decide what to launch from **the same function's same return
+ * value**, so probe and launch cannot disagree.
+ *
+ * ## What "probes must not modify the environment" can actually mean (measured)
+ *
+ * DR4-010 (5) says a probe must not change the environment ("installation,
+ * download, or config-file generation"). Measured on 2026-08-23 (macOS
+ * darwin 25.6.0) by running each `--version` under a **disposable** `HOME` /
+ * `XDG_DATA_HOME` / `XDG_CONFIG_HOME` and listing what appeared:
+ *
+ * | probe                | version   | warm ms | wrote into a pristine HOME              |
+ * |----------------------|-----------|---------|------------------------------------------|
+ * | `claude --version`   | 2.1.240   | 199     | nothing                                   |
+ * | `agy --version`      | 1.1.18    | 176     | nothing                                   |
+ * | `codex --version`    | 0.148.0   | 172     | `~/.codex/tmp/arg0`                       |
+ * | `opencode --version` | 1.18.21   | 404     | `~/.config/opencode`, `~/.cache/opencode`, `~/.local/{state,share}/opencode` |
+ * | `copilot --version`  | 1.0.80    | 436     | `~/Library/Caches/copilot`                |
+ * | `gemini --version`   | 0.55.1    | 929     | `~/.gemini/projects.json.<uuid>.tmp` ×2 (leaked, not cleaned up) |
+ *
+ * So the literal reading of (5) is satisfied by **two** of the six probes, and
+ * four of the rows the policy already approved fail it. The rule that the D2
+ * premise actually rests on is the narrower one #1979 was defending: a probe
+ * must not **install or download software, or change which binary would be
+ * launched**. Every row above satisfies that; none of them fetches anything.
+ * The gemini row is the weakest — it leaks two temp files into a `~/.gemini`
+ * that does not exist yet — and it is kept because it is the same class of
+ * side effect as codex/opencode/copilot, which are already in the table, and
+ * because dropping gemini would leave the one tool with **no** measured
+ * detector rules also with no way to notice that.
+ *
+ * `~/.config/gh` and `~/.local/share/gh` were checksummed before and after the
+ * whole measurement and neither changed (`~/.local/share/gh` still does not
+ * exist), which is the receipt #1979 asked for.
+ *
+ * ## Why this module imports nothing through `@/`
+ *
+ * `commandmate status` is one of the two exposure surfaces §4 D2 names, and
+ * `tsconfig.cli.json` compiles the CLI with `"paths": {}`. See the same
+ * constraint spelled out in `src/cli/types/api-responses.ts`.
+ *
+ * @module lib/detection/version-probes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DETECTOR_VERSION_PROBES = exports.DETECTOR_VERSION_PROBE_TIMEOUT_MS = void 0;
+exports.parseCliVersion = parseCliVersion;
+exports.parseVerifiedAgainstVersion = parseVerifiedAgainstVersion;
+exports.compareCliVersions = compareCliVersions;
+exports.runDetectorVersionProbe = runDetectorVersionProbe;
+exports.getDetectorFreshness = getDetectorFreshness;
+exports.toDetectorStaleness = toDetectorStaleness;
+exports.getDetectorStalenessSnapshot = getDetectorStalenessSnapshot;
+exports.clearDetectorVersionProbeCache = clearDetectorVersionProbeCache;
+const child_process_1 = require("child_process");
+const copilot_executable_1 = require("../cli-tools/copilot-executable");
+const env_sanitizer_1 = require("../security/env-sanitizer");
+const verified_against_1 = require("./tools/verified-against");
+/** Budget for one `<cli> --version`. Matches the catalog probe and copilot-executable. */
+exports.DETECTOR_VERSION_PROBE_TIMEOUT_MS = 5000;
+/**
+ * Cap on `--version` output kept in memory (DR4-010 (4)).
+ *
+ * `execFile` defaults to 1MB. A `--version` that answers with a megabyte is
+ * already misbehaving, so the buffer is sized to a version banner and the child
+ * is killed past it; the over-long answer is discarded rather than parsed.
+ */
+const DETECTOR_VERSION_PROBE_MAX_BUFFER_BYTES = 64 * 1024;
+/** Extracts a `major.minor.patch` triple from arbitrary `--version` output. */
+const VERSION_REGEX = /(\d+)\.(\d+)\.(\d+)/;
+/** Extract a normalized `major.minor.patch` version from `--version` output. */
+function parseCliVersion(output) {
+    const match = VERSION_REGEX.exec(output);
+    return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+/**
+ * A `verifiedAgainst` stamp written as a minor-series wildcard: `0.4.x`.
+ *
+ * Only ever applied to the stamp, never to a probe's own output — one side of
+ * this comparison is a string a human typed into a tool module, the other is
+ * what a binary printed about itself, and only the first is allowed to be vague.
+ */
+const VERIFIED_AGAINST_WILDCARD_REGEX = /^(\d+)\.(\d+)\.(?:x|\*)$/i;
+/**
+ * The comparable form of a `verifiedAgainst` stamp, or null when there is none.
+ *
+ * `'unmeasured'` is null — a tool nobody has captured frames for cannot be
+ * fresh or stale. `'0.4.x'` becomes `0.4.0`: antigravity's stamp is a minor
+ * series rather than a build (Issue #995 measured a range), and reading it as
+ * "no version" would silently exempt the one tool whose rules are furthest
+ * behind. Widening to `.0` is the safe direction — it can only ever call a
+ * newer install stale, never call a stale one current.
+ */
+function parseVerifiedAgainstVersion(stamp) {
+    const wildcard = VERIFIED_AGAINST_WILDCARD_REGEX.exec(stamp);
+    if (wildcard)
+        return `${wildcard[1]}.${wildcard[2]}.0`;
+    return parseCliVersion(stamp);
+}
+/**
+ * Compare two `major.minor.patch` versions numerically.
+ * @returns 1 if a > b, -1 if a < b, 0 if equal.
+ */
+function compareCliVersions(a, b) {
+    const pa = a.split('.').map((n) => Number(n) || 0);
+    const pb = b.split('.').map((n) => Number(n) || 0);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0 ? 1 : -1;
+    }
+    return 0;
+}
+/**
+ * Detector staleness probes: tool id → how to read its installed version.
+ *
+ * Deliberately the same shape as `VERSION_PROBES` in `slash-command-catalog.ts`
+ * (§4 D2: 「`VERSION_PROBES` と同型」), and deliberately a separate table: the
+ * catalog's question is "is the bundled slash-command list behind?" and this
+ * one's is "were these detection rules read off the build that is installed?".
+ * They happen to agree today; nothing requires them to.
+ *
+ * The binary for antigravity is `agy` — tool id and executable name differ
+ * (DR2-023). `gemini`'s row is `gemini --version`, measured for this Issue (the
+ * policy left it unconfirmed); its `verifiedAgainst` is `unmeasured`, so it is
+ * reported as "installed, rules never measured" rather than compared.
+ * `vibe-local` has no row: it is not an external CLI.
+ */
+exports.DETECTOR_VERSION_PROBES = {
+    claude: { kind: 'execFile', command: 'claude', args: ['--version'] },
+    codex: { kind: 'execFile', command: 'codex', args: ['--version'] },
+    antigravity: { kind: 'execFile', command: 'agy', args: ['--version'] },
+    opencode: { kind: 'execFile', command: 'opencode', args: ['--version'] },
+    gemini: { kind: 'execFile', command: 'gemini', args: ['--version'] },
+    copilot: {
+        kind: 'delegated',
+        probe: async () => (await (0, copilot_executable_1.resolveCopilotExecutable)())?.version ?? null,
+    },
+};
+let freshnessCache = null;
+let freshnessInFlight = null;
+/**
+ * Run one probe. Resolves null on any failure, and **without spawning anything**
+ * when the command does not resolve to an absolute path (DR4-010 (2)).
+ */
+function runDetectorVersionProbe(probe) {
+    if (probe.kind === 'delegated') {
+        return probe.probe().catch(() => null);
+    }
+    const executable = (0, copilot_executable_1.findExecutableOnPath)(probe.command);
+    // Skip, do not fall back to the bare name: handing an unresolved command to
+    // execFile is exactly the PATH-decides-the-binary case DR4-010 removes.
+    if (!executable)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)(executable, [...probe.args], {
+            timeout: exports.DETECTOR_VERSION_PROBE_TIMEOUT_MS,
+            maxBuffer: DETECTOR_VERSION_PROBE_MAX_BUFFER_BYTES,
+            env: (0, env_sanitizer_1.sanitizeEnvForChildProcess)(),
+        }, (error, stdout, stderr) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            resolve(parseCliVersion(`${stdout ?? ''}\n${stderr ?? ''}`));
+        });
+    });
+}
+async function computeDetectorFreshness() {
+    const tools = Object.keys(exports.DETECTOR_VERSION_PROBES).sort();
+    return Promise.all(tools.map(async (tool) => {
+        const verifiedAgainst = verified_against_1.DETECTOR_VERIFIED_AGAINST[tool]?.version ?? 'unmeasured';
+        const installed = await runDetectorVersionProbe(exports.DETECTOR_VERSION_PROBES[tool]);
+        const baseline = parseVerifiedAgainstVersion(verifiedAgainst);
+        return {
+            tool,
+            installed,
+            verifiedAgainst,
+            stale: installed !== null && baseline !== null && compareCliVersions(installed, baseline) > 0,
+        };
+    }));
+}
+/**
+ * The full freshness report, computed once per process and cached. Concurrent
+ * first callers share one probe.
+ *
+ * **This awaits child processes — never call it from a request path.** Use
+ * {@link getDetectorStalenessSnapshot} there. Kept for `commandmate status`,
+ * `npm run check:detector-freshness` and tests, and as the single implementation
+ * both entry points share.
+ */
+async function getDetectorFreshness() {
+    if (freshnessCache !== null)
+        return freshnessCache;
+    if (freshnessInFlight)
+        return freshnessInFlight;
+    freshnessInFlight = computeDetectorFreshness();
+    try {
+        freshnessCache = await freshnessInFlight;
+        return freshnessCache;
+    }
+    finally {
+        freshnessInFlight = null;
+    }
+}
+/** Reduce a report to the wire shape: stale tools only. */
+function toDetectorStaleness(rows) {
+    const staleness = {};
+    for (const row of rows) {
+        if (!row.stale || row.installed === null)
+            continue;
+        staleness[row.tool] = { installed: row.installed, verifiedAgainst: row.verifiedAgainst };
+    }
+    return staleness;
+}
+/**
+ * The staleness this process already knows, or `undefined` plus a background
+ * probe when it knows nothing yet. **Never awaits a child process** (§4 D2,
+ * DR3-013 (a)(b)(c)).
+ *
+ * `undefined` is "not known yet", not "nothing is stale" — see the module doc.
+ * The returned object is `{}` once the cache is warm and nothing is stale, which
+ * is how a caller tells the two apart.
+ */
+function getDetectorStalenessSnapshot() {
+    if (freshnessCache !== null)
+        return toDetectorStaleness(freshnessCache);
+    // Fire and forget. No in-flight check here on purpose: getDetectorFreshness
+    // owns that slot and hands a concurrent caller the promise that is already
+    // running, so a second guard would be a copy of an invariant that lives one
+    // function down — and a copy is what goes stale. It swallows its own failures,
+    // so nothing here needs the result.
+    void getDetectorFreshness().catch(() => []);
+    return undefined;
+}
+/** Clear the process-level probe cache (tests, and any future cache-control wiring). */
+function clearDetectorVersionProbeCache() {
+    freshnessCache = null;
+    freshnessInFlight = null;
+}

package/dist/server/src/lib/git/worktrees.js

@@ -24,6 +24,7 @@ const path_1 = __importDefault(require("path"));
 const worktree_id_1 = require("./worktree-id");
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
+const agents_config_1 = require("../../lib/repo-config/agents-config");
 const logger = (0, logger_1.createLogger)('worktrees');
 /**
  * ID minting lives in `worktree-id.ts` — a module that imports nothing but
@@ -186,6 +187,15 @@ async function scanWorktrees(rootDir) {
         // Get repository name from path
         const repositoryPath = path_1.default.resolve(rootDir);
         const repositoryName = path_1.default.basename(repositoryPath);
+        // Issue #2066: this is the "read it at sync" the repository-level agent
+        // declaration is specified against. Doing it here rather than lazily in
+        // `getWorktrees()` is what keeps the file off the sidebar's polled path
+        // (#1913's no-filesystem-probe-on-a-hot-path rule), and it is also what
+        // makes a broken `.commandmate/agents.yaml` warn once per sync instead of
+        // once per poll — the refusal is cached alongside an accepted value.
+        // Deliberately after the `git worktree list` above succeeded: a directory
+        // that is not a repository has no declaration worth reading.
+        (0, agents_config_1.refreshRepoAgentsConfig)(repositoryPath);
         // Filter and validate worktree paths
         return parsed
             .map((wt) => {

package/dist/server/src/lib/repo-config/agents-config.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * Loader for `.commandmate/agents.yaml` — a repository's own declaration of
+ * which agents its worktrees start with (Issue #2066).
+ *
+ * ## Why a file, and why not a key in `CMATE.md`
+ *
+ * `CMATE.md` already carries per-worktree schedule rows, so it was the obvious
+ * alternative. It is the wrong home for this one:
+ *
+ *  - **Scope.** `CMATE.md` is read from a *worktree* root (`cmate-parser.ts`
+ *    resolves it under the worktree directory and refuses paths outside it).
+ *    This declaration is a property of the **repository**, and it has to be
+ *    readable *before* a worktree's roster exists — that is the whole point.
+ *  - **Grammar.** `CMATE.md` is a Markdown *table* parser: every value is a
+ *    cell, and an ordered list with an optional primary would have to be
+ *    encoded into one. `.commandmate/verify.yaml` and `.commandmate/tasks/*.yaml`
+ *    already establish YAML as the shape for machine-read declarations, and
+ *    `validateAgentsPair()` wants a real list.
+ *  - **Blast radius.** `parseCmateConfig()` is on the schedule execution path.
+ *    Adding a key there means every schedule read re-validates agent ids, and a
+ *    malformed agents key becomes a way to disturb scheduling.
+ *
+ * So: a new file, next to the two declarations that already live in
+ * `.commandmate/`, following `verify.yaml`'s closed-key-set conventions.
+ *
+ * ## Shape
+ *
+ * ```yaml
+ * version: 1        # optional; must be 1 when present
+ * agents: [codex, claude]
+ * primary: claude   # optional; must be one of `agents`
+ * ```
+ *
+ * ## Fail-open
+ *
+ * Nothing here throws. A file that does not parse, declares an unknown key, or
+ * carries a list `validateAgentsPair()` rejects produces a WARNING and `null`,
+ * and `resolveSelectedAgents()` then falls through to `app_settings` and finally
+ * to the compiled-in constant. A repository must not be able to blank every
+ * sidebar tab strip by committing a typo.
+ *
+ * ## Why the read is cached, and why the cache is not optional
+ *
+ * `getWorktrees()` runs on every sidebar poll. Issue #1913 made "no filesystem
+ * probe on a hot path" a rule, restated by #2065 in
+ * `src/config/installed-agents-cache.ts` as "getWorktrees() must not grow a
+ * filesystem probe". This layer is inherently file-backed, so the rule is
+ * honoured the way the Issue asks for — **read at sync** — plus a TTL so the
+ * answer is still self-healing:
+ *
+ *  - {@link refreshRepoAgentsConfig} is called from `scanWorktrees()`, i.e. once
+ *    per repository per sync. That is the read the Issue specifies.
+ *  - {@link getRepoDefaultSelectedAgents} serves memory. It touches the disk
+ *    only on a cold miss (a server restarted since the last sync — the rows in
+ *    SQLite outlive the process, so "scanned at least once in this process" is
+ *    not a fact one may assume) or after {@link REPO_AGENTS_CACHE_TTL_MS}.
+ *
+ * The resulting worst case is one small `readFileSync` per repository per
+ * minute, bounded by the number of configured repositories — not per worktree,
+ * and not per poll.
+ *
+ * Server-only: reads from disk, so import this from API routes / CLI / DB
+ * helpers, never from a client component.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_REPO_AGENTS_CONFIG_BYTES = exports.REPO_AGENTS_CACHE_TTL_MS = exports.REPO_AGENTS_CONFIG_KEYS = exports.REPO_AGENTS_CONFIG_RELATIVE_PATH = void 0;
+exports.parseRepoAgentsConfig = parseRepoAgentsConfig;
+exports.loadRepoAgentsConfig = loadRepoAgentsConfig;
+exports.refreshRepoAgentsConfig = refreshRepoAgentsConfig;
+exports.getRepoDefaultSelectedAgents = getRepoDefaultSelectedAgents;
+exports.clearRepoAgentsConfigCache = clearRepoAgentsConfigCache;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+const logger_1 = require("../../lib/logger");
+const selected_agents_validator_1 = require("../../lib/selected-agents-validator");
+const logger = (0, logger_1.createLogger)('repo-agents-config');
+/** Path of the declaration, relative to the repository root. */
+exports.REPO_AGENTS_CONFIG_RELATIVE_PATH = '.commandmate/agents.yaml';
+/**
+ * Top-level keys v1 accepts. Closed, like `verify.yaml`'s: a key nobody reads is
+ * indistinguishable from a misspelled key that was meant to be read, and the
+ * misspelling is the case worth catching.
+ */
+exports.REPO_AGENTS_CONFIG_KEYS = ['version', 'agents', 'primary'];
+/**
+ * How long one parsed declaration is reused before the disk is consulted again.
+ *
+ * 60s is chosen against the user's loop: edit `agents.yaml`, switch back to the
+ * browser, look at a worktree that has no roster yet. Pressing the sync button
+ * (which calls {@link refreshRepoAgentsConfig}) makes it immediate; this is the
+ * floor for someone who does not.
+ */
+exports.REPO_AGENTS_CACHE_TTL_MS = 60_000;
+/** Largest declaration read into memory. A declaration is a few hundred bytes. */
+exports.MAX_REPO_AGENTS_CONFIG_BYTES = 64 * 1024;
+const cache = new Map();
+/**
+ * Render an untrusted value for a log line (R4-005, the same concern
+ * `parseSelectedAgents()` documents).
+ *
+ * A repository file is attacker-adjacent input on a shared machine: ANSI escapes
+ * and newlines in it would otherwise reach a terminal that is tailing the server
+ * log and forge log lines there.
+ */
+function forLog(value, limit = 120) {
+    const text = typeof value === 'string'
+        ? value
+        : Array.isArray(value)
+            ? 'a list'
+            : value === null
+                ? 'null'
+                : typeof value === 'object'
+                    ? 'a mapping'
+                    : String(value);
+    const stripped = text.replace(/[\u0000-\u001F\u007F-\u009F]/g, ' ');
+    return stripped.length > limit ? `${stripped.slice(0, limit)}...` : stripped;
+}
+function isMapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse a declaration's text into an ordered agent list.
+ *
+ * Exported so the rules can be tested without a filesystem, and so a future
+ * surface that already holds the text (a repository settings screen previewing
+ * an upload) can validate it the same way.
+ *
+ * @param raw - File contents
+ * @param source - Path used in warning messages
+ * @returns Ordered agents (`[0]` is the primary), or null when unusable
+ */
+function parseRepoAgentsConfig(raw, source) {
+    let document;
+    try {
+        document = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        logger.warn('repo-agents:yaml-parse-failed', {
+            source,
+            error: forLog(error.message),
+        });
+        return null;
+    }
+    // An empty file parses to null. Treat it as "this repository declares
+    // nothing", which is the same answer as having no file at all — and say so at
+    // debug level rather than warn, because it is not a mistake worth shouting at.
+    if (document === null || document === undefined) {
+        logger.debug('repo-agents:empty', { source });
+        return null;
+    }
+    if (!isMapping(document)) {
+        logger.warn('repo-agents:not-a-mapping', { source, got: forLog(document) });
+        return null;
+    }
+    const unknownKeys = Object.keys(document).filter((key) => !exports.REPO_AGENTS_CONFIG_KEYS.includes(key));
+    if (unknownKeys.length > 0) {
+        logger.warn('repo-agents:unknown-keys', {
+            source,
+            keys: unknownKeys.map((key) => forLog(key, 40)),
+        });
+        return null;
+    }
+    if (document.version !== undefined && document.version !== null) {
+        const version = typeof document.version === 'number'
+            ? document.version
+            : typeof document.version === 'string' && /^\d+$/.test(document.version)
+                ? Number(document.version)
+                : null;
+        if (version !== 1) {
+            logger.warn('repo-agents:unsupported-version', {
+                source,
+                got: forLog(document.version),
+            });
+            return null;
+        }
+    }
+    if (!Array.isArray(document.agents)) {
+        logger.warn('repo-agents:agents-not-a-list', {
+            source,
+            got: forLog(document.agents),
+        });
+        return null;
+    }
+    // The shared validator (Issue #2066 requirement 3): 2-6 unique ids drawn from
+    // CLI_TOOL_IDS, exactly what `app_settings` and the API input are held to.
+    const validated = (0, selected_agents_validator_1.validateAgentsPair)(document.agents);
+    if (!validated.valid) {
+        logger.warn('repo-agents:invalid-agents', {
+            source,
+            error: validated.error,
+            got: document.agents.map((entry) => forLog(entry, 40)),
+        });
+        return null;
+    }
+    const agents = validated.value;
+    if (document.primary === undefined || document.primary === null) {
+        return agents;
+    }
+    if (typeof document.primary !== 'string' || !agents.includes(document.primary)) {
+        // Deliberately falls through rather than ignoring the key: `primary` exists
+        // to say which tab opens first, and quietly opening a different one is worse
+        // than falling back to a default the user can see is a default.
+        logger.warn('repo-agents:primary-not-in-agents', {
+            source,
+            got: forLog(document.primary, 40),
+            agents,
+        });
+        return null;
+    }
+    const primary = document.primary;
+    return [primary, ...agents.filter((id) => id !== primary)];
+}
+/**
+ * Read and parse `<repoPath>/.commandmate/agents.yaml`, bypassing the cache.
+ *
+ * @param repoPath - Repository root
+ * @returns Ordered agents, or null when the file is absent, unreadable or unusable
+ */
+function loadRepoAgentsConfig(repoPath) {
+    const configPath = (0, path_1.join)(repoPath, exports.REPO_AGENTS_CONFIG_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(configPath, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        // The overwhelmingly common case: the repository has no declaration.
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        logger.warn('repo-agents:read-failed', {
+            source: configPath,
+            code,
+            error: forLog(error.message),
+        });
+        return null;
+    }
+    const bytes = Buffer.byteLength(raw, 'utf8');
+    if (bytes > exports.MAX_REPO_AGENTS_CONFIG_BYTES) {
+        logger.warn('repo-agents:too-large', {
+            source: configPath,
+            bytes,
+            limit: exports.MAX_REPO_AGENTS_CONFIG_BYTES,
+        });
+        return null;
+    }
+    return parseRepoAgentsConfig(raw, configPath);
+}
+/**
+ * Read the declaration from disk and store the answer, replacing whatever the
+ * cache held.
+ *
+ * This is the "read it at sync" the Issue asks for: `scanWorktrees()` calls it
+ * once per repository, so a broken file warns once per sync rather than once per
+ * sidebar poll (the negative answer is cached too, which is what keeps the
+ * warning from repeating).
+ *
+ * @param repoPath - Repository root
+ * @param now - Injectable clock (tests)
+ * @returns Ordered agents, or null when there is no usable declaration
+ */
+function refreshRepoAgentsConfig(repoPath, now = Date.now()) {
+    const value = loadRepoAgentsConfig(repoPath);
+    cache.set(repoPath, { value, expiresAt: now + exports.REPO_AGENTS_CACHE_TTL_MS });
+    return value;
+}
+/**
+ * The `repo` layer of `resolveSelectedAgents()` for one repository.
+ *
+ * Serves memory; see the module header for why, and for the two cases that do
+ * reach the disk. Never throws.
+ *
+ * @param repoPath - Repository root; a falsy path (a worktree row with no
+ *   `repository_path`) has no repository to ask and answers null
+ * @param now - Injectable clock (tests)
+ * @returns Ordered agents (`[0]` is the primary), or null when unset/invalid
+ */
+function getRepoDefaultSelectedAgents(repoPath, now = Date.now()) {
+    if (!repoPath)
+        return null;
+    const entry = cache.get(repoPath);
+    if (entry && entry.expiresAt > now)
+        return entry.value;
+    return refreshRepoAgentsConfig(repoPath, now);
+}
+/**
+ * Drop cached declarations. Tests, and any surface that just rewrote one.
+ *
+ * @param repoPath - Only this repository when given; the whole cache otherwise
+ */
+function clearRepoAgentsConfigCache(repoPath) {
+    if (repoPath === undefined) {
+        cache.clear();
+        return;
+    }
+    cache.delete(repoPath);
+}