commandmate 0.29.1 → 0.30.0

package/dist/server/src/lib/realtime/types.js

@@ -9,8 +9,9 @@
  * the canonical {@link RealtimeEvent}.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
+exports.MESSAGES_INVALIDATED_EVENT_TYPE = exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH = exports.CHAT_TURN_PROGRESS_MIN_INTERVAL_MS = exports.CHAT_TURN_PROGRESS_EVENT_TYPE = exports.VERSION_MISMATCH_EVENT_TYPE = exports.CLIENT_VERSION_MESSAGE_TYPE = void 0;
 exports.isVersionMismatch = isVersionMismatch;
+exports.truncateChatTurnProgressBody = truncateChatTurnProgressBody;
 exports.parseRealtimeEvent = parseRealtimeEvent;
 /**
  * Client → server hello carrying the client bundle version, sent on every
@@ -38,6 +39,100 @@ function isVersionMismatch(serverVersion, clientVersion) {
         return false;
     return serverVersion !== clientVersion;
 }
+/**
+ * The body of the turn that is being generated **right now** (Issue #2199).
+ *
+ * The chat surface has no partial assistant text of its own: a reply reaches
+ * `chat_messages` only once the turn is over, so a long turn leaves the surface
+ * saying "Responding…" for minutes while the terminal surface next to it is
+ * filling up. This frame is that missing text, and everything about its shape
+ * follows from one decision — **it is never persisted**.
+ *
+ * Not persisted means the row this becomes is written by somebody else: the
+ * existing `message` broadcast, from `sources/<tool>/history`, whose `requestId`
+ * is exactly {@link ChatTurnProgressEvent.turnKey}. So a client replaces the
+ * progress body with the confirmed row by matching that one string, and a
+ * missed frame costs a moment of staleness rather than a lost reply. It is also
+ * why there is no replay on reconnect and no `done: true` member: the settled
+ * state of a turn is a `chat_messages` row, and this event has nothing to say
+ * about it.
+ *
+ * `version` is monotonic per (worktreeId, cliToolId, instanceId) — the same
+ * discipline {@link TerminalSnapshotEvent} carries, and for a sharper reason
+ * here: opencode's SSE re-sends its boundary frames, so a client that trusted
+ * arrival order would redraw an older body over a newer one.
+ */
+exports.CHAT_TURN_PROGRESS_EVENT_TYPE = 'chat_turn_progress';
+/**
+ * Smallest gap between two progress frames for one instance.
+ *
+ * The producers are a 2 s poller tick (claude) and an SSE part stream that
+ * measured 88 delta frames for a single 967-character paragraph (opencode), so
+ * the second one needs a brake and the first one does not. One brake for both,
+ * because the expensive half of the claude path — a 4 MiB tail read and a parse
+ * — happens *behind* this gate too, and a surface polled over HTTP at ~1 s
+ * would otherwise pay for it on every request.
+ */
+exports.CHAT_TURN_PROGRESS_MIN_INTERVAL_MS = 1000;
+/**
+ * Longest body one progress frame carries, in UTF-16 code units.
+ *
+ * Two orders of magnitude below `MAX_CLAUDE_TURN_BODY_LENGTH` /
+ * `MAX_OPENCODE_TURN_BODY_LENGTH`, which bound the body that gets *saved*. This
+ * one is re-sent every second while a turn runs, so its cost is per frame
+ * rather than per turn.
+ */
+exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH = 64 * 1024;
+/**
+ * Cut an over-long progress body, **keeping the tail**.
+ *
+ * The head is what goes, and that is the opposite of what the two turn writers
+ * do. They are recording a reply and the reply reads from the top; this is
+ * showing a reply being written, and the interesting end is the one the model
+ * is still adding to. A reader who needs the head has the terminal surface and,
+ * a moment later, the settled row.
+ *
+ * The cut is reported rather than hidden — see `partial` on
+ * {@link ChatTurnProgressEvent}. Silently showing the middle of a reply as if it
+ * were the whole of one is the failure this signature exists to prevent.
+ */
+function truncateChatTurnProgressBody(body, maxLength = exports.MAX_CHAT_TURN_PROGRESS_BODY_LENGTH) {
+    if (maxLength <= 0)
+        return { body: '', truncated: body.length > 0 };
+    if (body.length <= maxLength)
+        return { body, truncated: false };
+    return { body: body.slice(body.length - maxLength), truncated: true };
+}
+/**
+ * "This instance's history changed in a way no row-level frame can express —
+ * re-read it" (Issue #2219).
+ *
+ * The one mutation that has no row to publish is a **delete**:
+ * `sendUserMessage` removes the previous, identical user row after the retry is
+ * persisted (#379's duplicate guard), and `message` / `message_updated` can only
+ * ever say "this row now looks like this". A second device therefore kept the
+ * deleted row until its own poll came round — 15s while a socket is up, since
+ * #2195 demoted that poll to a fallback — showing the same sentence twice.
+ *
+ * It carries a **scope, not a payload**, and that is the whole design:
+ *
+ *  - the receiver re-fetches, so it lands on the DB's settled state rather than
+ *    on a diff it has to merge — a `message` frame that was dropped on the way
+ *    is repaired by the same round trip;
+ *  - the re-fetch bumps `useSplitMessages`' request id, which retires any fetch
+ *    that started *before* the delete and would otherwise resolve with the row
+ *    still in it;
+ *  - no tombstone has to be kept anywhere, and `archived` — which means "a
+ *    previous session's history" — keeps meaning only that.
+ *
+ * The cost is one extra GET per orphan cleanup, on an event that fires only when
+ * someone re-sends the exact text of their last unanswered message.
+ *
+ * {@link instanceId} is always resolved (`instanceId ?? cliToolId`), like
+ * {@link TerminalSnapshotEvent}'s: a client matches it against its own pane and
+ * an omitted field would simply never match.
+ */
+exports.MESSAGES_INVALIDATED_EVENT_TYPE = 'messages_invalidated';
 /**
  * Parse a raw WebSocket frame into the inner realtime event.
  *

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

package/dist/server/src/lib/selected-agents-validator.js

@@ -5,12 +5,14 @@
  *
  * Provides:
  * - validateAgentsPair(): Core validation logic (R1-001)
+ * - resolveSelectedAgents(): the ONE place the fallback order lives (Issue #2065)
  * - parseSelectedAgents(): DB read with fallback + console.warn (R4-005 log sanitization)
  * - validateSelectedAgentsInput(): API input validation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SELECTED_AGENTS = exports.MAX_SELECTED_AGENTS = exports.MIN_SELECTED_AGENTS = void 0;
+exports.SELECTED_AGENTS_LAYERS = exports.DEFAULT_SELECTED_AGENTS = exports.MAX_SELECTED_AGENTS = exports.MIN_SELECTED_AGENTS = void 0;
 exports.validateAgentsPair = validateAgentsPair;
+exports.resolveSelectedAgents = resolveSelectedAgents;
 exports.parseSelectedAgents = parseSelectedAgents;
 exports.validateSelectedAgentsInput = validateSelectedAgentsInput;
 const types_1 = require("./cli-tools/types");
@@ -19,14 +21,19 @@ exports.MIN_SELECTED_AGENTS = 2;
 /** Maximum number of selected agents (PC can select up to 6, Issue #989) */
 exports.MAX_SELECTED_AGENTS = 6;
 /**
- * Default selected agents when DB value is missing or invalid.
+ * Compiled-in last resort for a worktree's agent list.
  * Issue #1516: narrowed to the 3 agents in routine use (claude/codex/antigravity).
  * The others stay selectable via CLI_TOOL_IDS — they are just not preselected.
+ *
+ * Issue #2065: this is no longer the only answer. It is the LOWEST layer of
+ * `resolveSelectedAgents()` — the value a fresh install with no `app_settings`
+ * row still gets, which is why the acceptance criterion "an environment with no
+ * setting behaves exactly as before" reduces to "this constant is unchanged".
  */
 exports.DEFAULT_SELECTED_AGENTS = ['claude', 'codex', 'antigravity'];
 /**
  * Core validation function for CLI tool ID arrays (R1-001)
- * Accepts 2-5 unique valid CLI tool IDs (Issue #836).
+ * Accepts 2-6 unique valid CLI tool IDs (Issue #836 raised it to 5, #989 to 6).
  * Shared between parseSelectedAgents() and validateSelectedAgentsInput()
  *
  * @param input - Array of values to validate
@@ -44,36 +51,99 @@ function validateAgentsPair(input) {
     }
     return { valid: true, value: input };
 }
+/**
+ * The layers that can answer "which agents does this worktree show", highest
+ * priority first (Issue #2065).
+ *
+ * This array IS the priority order — `resolveSelectedAgents()` walks it in
+ * sequence and nothing else encodes it. The final shape the Epic is heading for
+ * is `worktree -> repo file -> app_settings -> constant`; #2065 populated the
+ * `worktree` and `appSettings` layers and declared `repo` without ever passing
+ * it a value.
+ *
+ * Issue #2066 filled `repo` in, exactly as that comment foresaw: by supplying a
+ * value at the call sites, and NOT by re-deriving an order. This array is still
+ * the only place the order is written down, and the function below is unchanged.
+ *
+ * There are exactly TWO such call sites, both in `@/lib/db/worktree-db`:
+ * `getWorktrees()` and `getWorktreeById()`, each reading
+ * `getRepoDefaultSelectedAgents()` from `@/lib/repo-config/agents-config`.
+ * `resolveAgentInstances()` is NOT one of them — it receives the already
+ * resolved value as its `selectedAgents` argument, and giving it a second entry
+ * point would have been an argument no production caller passes.
+ *
+ * A layer whose value is absent, malformed, or fails `validateAgentsPair()` is
+ * skipped rather than fatal: a hand-edited `app_settings` row must not be able
+ * to make every worktree in the sidebar render an empty tab strip.
+ */
+exports.SELECTED_AGENTS_LAYERS = ['worktree', 'repo', 'appSettings'];
+/**
+ * Resolve a worktree's agent list from the layers, in priority order.
+ *
+ * The ONE place the fallback order lives (Issue #2065). Every fallback — server
+ * or client, roster seed or tab seed — goes through this function so a new layer
+ * is a change to `SELECTED_AGENTS_LAYERS` plus a value at the call sites, and
+ * never a second copy of the order.
+ *
+ * @param layers - Candidate values keyed by layer; omit a layer you cannot answer for
+ * @returns The first layer that validates, else {@link DEFAULT_SELECTED_AGENTS}
+ */
+function resolveSelectedAgents(layers = {}) {
+    for (const layer of exports.SELECTED_AGENTS_LAYERS) {
+        const candidate = layers[layer];
+        if (candidate == null)
+            continue;
+        const result = validateAgentsPair([...candidate]);
+        if (result.valid)
+            return result.value;
+    }
+    return exports.DEFAULT_SELECTED_AGENTS;
+}
 /**
  * Parse selected_agents JSON from DB with safe fallback
- * Returns default value for any invalid input (never throws)
+ * Returns the resolved default for any invalid input (never throws)
  *
- * Logs a warning when fallback is triggered to help detect DB data issues.
  * Log output is sanitized (R4-005): ANSI stripped, newlines removed, truncated.
  *
+ * Issue #2065: the fallback is no longer the constant but
+ * `resolveSelectedAgents()`, so a row with no `selected_agents` (every worktree
+ * created by scan/sync — `upsertWorktree` never writes the column) picks up the
+ * `app_settings` default. Callers that have a `db` handle pass
+ * `appSettingsDefault`; callers that do not (unit fixtures, pure helpers) omit
+ * it and get exactly the pre-#2065 behaviour.
+ *
+ * Issue #2066 adds `repoDefault`, the repository's own `.commandmate/agents.yaml`
+ * declaration. It is LAST in the parameter list and SECOND in priority — the
+ * order the layers resolve in lives in {@link SELECTED_AGENTS_LAYERS} and
+ * nowhere else, so an argument position is free to be chosen for what it is
+ * good for: every existing two-argument call keeps its meaning unchanged, which
+ * is what makes "an environment with no file behaves exactly as before" a
+ * property of the signature rather than of a review.
+ *
  * @param raw - Raw JSON string from DB (or null)
- * @returns Validated array of 2-5 CLIToolType values
+ * @param appSettingsDefault - Server-wide default from `app_settings`, or null/undefined when unset
+ * @param repoDefault - Repository declaration from `.commandmate/agents.yaml`, or null/undefined when absent/invalid
+ * @returns Validated array of 2-6 CLIToolType values
  */
-function parseSelectedAgents(raw) {
-    if (!raw)
-        return exports.DEFAULT_SELECTED_AGENTS;
-    try {
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed)) {
-            // invalid format - return default silently
-            return exports.DEFAULT_SELECTED_AGENTS;
+function parseSelectedAgents(raw, appSettingsDefault, repoDefault) {
+    let fromRow = null;
+    if (raw) {
+        try {
+            const parsed = JSON.parse(raw);
+            // A non-array (or a JSON parse error) is treated the same as an absent
+            // column: skip the layer silently and let the lower ones answer.
+            if (Array.isArray(parsed))
+                fromRow = parsed;
         }
-        const result = validateAgentsPair(parsed);
-        if (!result.valid) {
-            // validation failed - return default silently
-            return exports.DEFAULT_SELECTED_AGENTS;
+        catch {
+            // JSON parse error - fall through to the lower layers
         }
-        return result.value;
-    }
-    catch {
-        // JSON parse error - return default silently
-        return exports.DEFAULT_SELECTED_AGENTS;
     }
+    return resolveSelectedAgents({
+        worktree: fromRow,
+        repo: repoDefault,
+        appSettings: appSettingsDefault,
+    });
 }
 /**
  * Validate selectedAgents input from API request body