tumwater 0.4.0 → 0.4.2

package/dist/src/config/config-request.js

@@ -1,8 +1,9 @@
-/** The director's staged config-write request — one verb split out of config-write.ts (the
+/** The role's staged config-write request — one verb split out of config-write.ts (the
  * operator-editor mutators stay there, addressed by key through config-keys.ts). The director
- * stages a JSON request file in its worktree; this module consumes it: parse the request,
- * keep only its `customRoles` array, apply it as a whole-config write, and delete the file on
- * every path. A request is shaped and lives differently from the interactive `config set` /
+ * (and, for a declared project check, the feature role) stages a JSON request file in its
+ * worktree; this module consumes it: parse the request, keep only its `customRoles` array and
+ * a declared `check.command`, apply it as a whole-config write, and delete the file on every
+ * path. A request is shaped and lives differently from the interactive `config set` /
  * `unset` verbs (a staged file that must never reach a diff, not direct CLI text), so the
  * runtime (run-verdict.ts) imports this module rather than the whole editor. It
  * still shares the write machinery with the editor — withConfigLock and rawConfigObject from
@@ -10,9 +11,10 @@
  * config-validation.ts, writeJsonAtomic from json-files.js — because a request is a
  * whole-config write too. */
 import fs from "node:fs";
+import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { configPath, configRequestPath } from "../paths.js";
-import { errorMessage } from "../text/text.js";
+import { errorMessage, isNonBlankString } from "../text/text.js";
 import { readTextOrNull } from "../files/files.js";
 import { writeJsonAtomic } from "../files/json-files.js";
 import { isJsonObject } from "../files/json-object.js";
@@ -21,21 +23,124 @@ import { show } from "./config-field-checks.js";
 import { validateConfig } from "./config-validation.js";
 import { normalizeConfigKeys } from "./config-aliases.js";
 import { collapseBackendAliases, loadConfig } from "./config.js";
-/** Consume the director's config-write request file (plans/portability.md §3/7). After its pi
+import { BUILD_CHECK_TIMEOUT_MS, gateCommandOf, } from "../build/build-check-detect.js";
+import { runBuildCheck } from "../build/build-check.js";
+import { CHECK_TIER, withCheckPermit } from "../concurrency/check-permit.js";
+async function defaultCheckGuard(wt, check, config) {
+    // Take the same process-wide check permit every full-suite runner takes (runScopedBuildCheck's
+    // gate/merge/batch scopes and checkMainBaseline), so a declaration burst cannot stack suites
+    // on the host beside the authors' own runs. runBuildCheck's own arguments stand: the same
+    // install-first step and upward PATH resolution the gate's run uses; the candidate BuildCheck
+    // carries the config-resolved timeout, so checkTimeoutMs enforces it here exactly as the
+    // pre-check would.
+    return withCheckPermit(config, CHECK_TIER.other, () => runBuildCheck(wt, check));
+}
+/** The candidates the guard verifies before a declared `check.command` is written: the
+ * declared command itself (the feature's fail-closed guarantee — a request whose own command
+ * fails must not be written), plus, when a `check.gateCommand` is set and differs, that gate
+ * command too (the gate scope's pre-check — runScopedBuildCheck — swaps in `check.gateCommand`
+ * at scope "gate", so the guard must not read green on a command the gate never runs). Each is
+ * run at `check.cwd` resolved against the worktree (default `.`), under the config-resolved
+ * timeout. A preserved cwd must be honored or the guard runs in the wrong tree — a false green
+ * or false red that defeats the fail-closed purpose. */
+function guardChecks(current, wt, declared) {
+    const c = current.check;
+    const configuredMs = typeof c?.timeoutSeconds === "number" && c.timeoutSeconds > 0 ? c.timeoutSeconds * 1000 : undefined;
+    const base = {
+        kind: "command",
+        cwd: path.resolve(wt, isNonBlankString(c?.cwd) ? c.cwd : "."),
+        timeoutMs: configuredMs ?? BUILD_CHECK_TIMEOUT_MS,
+    };
+    const gate = gateCommandOf(current);
+    if (gate !== undefined && gate !== declared) {
+        return [{ ...base, command: gate }, { ...base, command: declared }];
+    }
+    return [{ ...base, command: declared }];
+}
+/** How a non-passed guard outcome is named in the rejection error. */
+function describeGuardFailure(o) {
+    if (o.status === "failed")
+        return "failed";
+    if (o.skipReason === "timeout")
+        return "timed out";
+    if (o.skipReason === "install")
+        return "could not install dependencies";
+    return "could not run";
+}
+/** Build the whole-config write candidate a request would produce from a given `current`
+ * config — the request's customRoles array (or the live one when absent) and, when a
+ * check.command is declared, the check section with only `command` replaced — and return
+ * whether that candidate differs from `current` at all. Shared by the pre-write validation
+ * (which must reject an invalid request BEFORE the declared check runs, so a request pairing a
+ * valid check.command with an invalid customRoles entry never spawns the check) and the locked
+ * write, so the two can never build different candidates. Roles stripping is folded in: the
+ * standalone validation has to reject what the write would reject, and the write has to strip
+ * what the validation sees. */
+function buildCandidate(root, current, entries, checkCommand) {
+    const customRoles = entries === undefined ? current.customRoles : entries;
+    const checkChanged = checkCommand !== undefined && (current.check?.command ?? "") !== checkCommand;
+    const unchanged = !checkChanged && isDeepStrictEqual(customRoles, current.customRoles);
+    // Strip roles.<id> entries for custom roles this request removes (see applyConfigRequest's
+    // docstring): structurally valid names only; anything else stays for validateConfig to
+    // reject — never dereference a request entry before validation.
+    const requestedNames = new Set();
+    for (const entry of customRoles) {
+        if (isJsonObject(entry) && typeof entry.name === "string")
+            requestedNames.add(entry.name);
+    }
+    // Base the roles rewrite on the FILE's own section, not the loaded (catalog-merged) map:
+    // this whole-config write must not re-expand a partial section to every built-in
+    // (preserveFileRoles' rule). Only the removed custom roles' entries are stripped, and only
+    // from what the file actually holds.
+    const rawRolesCandidate = rawConfigObject(root).roles;
+    const roles = isJsonObject(rawRolesCandidate) ? { ...(rawRolesCandidate) } : {};
+    for (const c of current.customRoles) {
+        if (!requestedNames.has(c.name))
+            delete roles[c.name];
+    }
+    const candidate = { ...current, customRoles };
+    if (checkChanged && checkCommand !== undefined) {
+        // Preserve the rest of the check section (gateCommand/mergeCommand/timeoutSeconds);
+        // only `command` is declared by the request.
+        candidate.check = { ...current.check, command: checkCommand };
+    }
+    if (rawRolesCandidate === undefined)
+        delete candidate.roles;
+    else
+        candidate.roles = roles;
+    return { candidate: candidate, changed: !unchanged };
+}
+/** Consume the role's config-write request file (plans/portability.md §3/7). After its pi
  * run the director may leave `.tumwater-config-request.json` at its worktree root:
- * `{ "customRoles": [ { "name", "task" }, … ] }` — the whole array, replacing the current one.
+ * `{ "customRoles": [ { "name", "task" }, … ] }` — the whole array, replacing the current one;
+ * the feature role (only) may leave the same file carrying a `check.command` to declare the
+ * project's verification command, which is observed green in the worktree before it is written.
  * Applied atomically to the live config, sharing the editor's trap (fresh loadConfig that
  * bypasses the stat cache, validateConfig, then writeJsonAtomic — readers poll every ~2 s), so
  * the orchestrator's live reload starts the new role with no commit, no review
  * gate, and no merge, and the request file never enters a diff.
  *
- * The permitted key set is enforced here, not in prose: `customRoles` is accepted and every
- * other top-level key is collected into `ignored` and dropped (the caller logs the warning that
- * names them). Validation runs BEFORE any write and nothing here dereferences a request entry
- * first — a structurally malformed entry (`[null]`, a non-string name) is left for
- * validateConfig to reject, so on failure nothing is written and the previous config stays
- * live. The request file is deleted on EVERY path (including every failure), so a malformed
- * request cannot retry forever and the file cannot survive into `git add -A`.
+ * The permitted key set is enforced here, not in prose: `customRoles` and a `check` object are
+ * accepted and every other top-level key is collected into `ignored` and dropped (the caller
+ * logs the warning that names them). Inside `check` only `command` is read — a non-blank
+ * string that declares the project's check; every other sub-key (and a blank `command`) is
+ * collected into `ignored` and dropped, so a role can declare a check but never turn the
+ * safety gates off (`gateCommand: ""`, `mergeCommand: ""`, `timeoutSeconds`). Validation runs
+ * BEFORE any write and nothing here dereferences a request entry first — a structurally
+ * malformed entry (`[null]`, a non-string name) is left for validateConfig to reject, so on
+ * failure nothing is written and the previous config stays live. The request file is deleted
+ * on EVERY path (including every failure), so a malformed request cannot retry forever and the
+ * file cannot survive into `git add -A`.
+ *
+ * A declared `check.command` is verified before it is written: the declared command is run
+ * through runBuildCheck in the requesting worktree — and, when a `check.gateCommand` is set
+ * and differs, that gate command (which the gate scope runs) is verified first too — each at
+ * `check.cwd` resolved against it (default `.`), under the config-resolved timeout, the same
+ * install-first step, and the same process-wide check permit (`maxConcurrentChecks`) the gate's
+ * pre-check takes — and only a `passed` outcome for every candidate writes. A failed, timed-out,
+ * or skipped run writes nothing and returns an error naming what was observed — the role's own
+ * claim is not the evidence, because a command that could never pass would park the whole queue
+ * behind a red main no role can repair (part 1/2).
  *
  * Roles entries for custom roles the request removes are stripped before validation, from the
  * FILE's own `roles` section rather than the catalog-merged map (the rule every other
@@ -46,11 +151,11 @@ import { collapseBackendAliases, loadConfig } from "./config.js";
  * validateConfig to reject.
  *
  * Returns null when no request file exists. `applied` names the custom roles now live (empty
- * unless the write happened); `ignored` lists the discarded top-level keys; `error`, when set,
- * names why nothing (or only part of the work) was done — the caller turns it and `ignored`
- * into warning events. `unchanged` is set when the request's array equals the live one;
- * nothing is written. */
-export function applyConfigRequest(root, wt) {
+ * unless the write happened); `ignored` lists the discarded keys (top-level keys and, named
+ * `check.<key>`, the check sub-keys that were dropped); `error`, when set, names why nothing
+ * (or only part of the work) was done — the caller turns it and `ignored` into warning events.
+ * `unchanged` is set when the request changes nothing; nothing is written. */
+export async function applyConfigRequest(root, wt, runCheck = defaultCheckGuard) {
     const requestFile = configRequestPath(wt);
     const raw = readTextOrNull(requestFile);
     if (raw === null)
@@ -69,48 +174,68 @@ export function applyConfigRequest(root, wt) {
             throw new Error(normalized.problems.join("; "));
         const parsed = normalized.raw;
         for (const key of Object.keys(parsed)) {
-            if (key !== "customRoles")
+            if (key !== "customRoles" && key !== "check")
                 ignored.push(key);
         }
-        const entries = parsed.customRoles;
-        if (!Array.isArray(entries))
-            throw new Error(`config request's customRoles must be an array (got ${show(entries)})`);
+        // A check request is read only for its `command` (a non-blank string). Every other
+        // sub-key — and a blank `command` — is dropped into `ignored`, so it can never turn the
+        // safety gates off; a blank/absent command simply declares nothing.
+        let checkCommand;
+        if (parsed.check !== undefined) {
+            const checkReq = parsed.check;
+            if (!isJsonObject(checkReq))
+                throw new Error(`config request's check must be an object (got ${show(checkReq)})`);
+            for (const key of Object.keys(checkReq)) {
+                if (key !== "command")
+                    ignored.push(`check.${key}`);
+            }
+            if (isNonBlankString(checkReq.command))
+                checkCommand = checkReq.command;
+            else if (checkReq.command !== undefined)
+                ignored.push("check.command");
+        }
+        const entriesRaw = parsed.customRoles;
+        if (entriesRaw !== undefined && !Array.isArray(entriesRaw))
+            throw new Error(`config request's customRoles must be an array (got ${show(entriesRaw)})`);
+        const entries = entriesRaw;
+        // Verified declaration (part 1/2): a declared check is fail-closed — the gate's pre-check
+        // rejects a red run and a failure that reproduces on main parks every queued pin behind a
+        // red main no role can repair by code — so the declared command must be observed green in
+        // the requesting worktree BEFORE it is written. Only a `passed` outcome writes; failed,
+        // timed-out, or skipped writes nothing and returns an error naming what was observed. Each
+        // candidate is run at `check.cwd` resolved against the worktree (default `.`) under the
+        // config-resolved timeout, and when a `check.gateCommand` is set and differs the gate
+        // command is verified first too — the declared command is the fail-closed promise, the
+        // gate command is what the gate scope will actually run — so a green here is a green at
+        // the gate for every command the write leaves live.
+        if (checkCommand !== undefined) {
+            // Read the current config only for the guard — the write reloads fresh under the lock.
+            const currentForGuard = loadConfig(root);
+            // Pre-validate what the request would write BEFORE the declared check runs: a request
+            // that pairs a valid check.command with an invalid customRoles entry must be rejected
+            // without ever spawning the check (it would fail validation anyway). The locked write
+            // re-loads fresh and re-validates, so a config change between here and the write is
+            // still caught.
+            const { candidate: preCandidate } = buildCandidate(root, currentForGuard, entries, checkCommand);
+            validateConfig(collapseBackendAliases(preCandidate));
+            for (const check of guardChecks(currentForGuard, wt, checkCommand)) {
+                const outcome = await runCheck(wt, check, currentForGuard);
+                if (outcome.status !== "passed") {
+                    throw new Error(`check.command not declared: \`${outcome.script}\` ${describeGuardFailure(outcome)} in the worktree`);
+                }
+            }
+        }
         // The load-to-write sequence is one critical section under withConfigLock: a concurrent
         // `config set`/dashboard write between the load and this write must not be dropped by the
         // whole-file overwrite (see writeConfigMutation).
         withConfigLock(root, () => {
             const current = loadConfig(root); // fresh — bypasses the stat cache: a writer sees the latest file
-            // Same as the live array: write nothing, like writeConfigMutation's no-op skip.
-            if (isDeepStrictEqual(entries, current.customRoles)) {
+            const { candidate, changed } = buildCandidate(root, current, entries, checkCommand);
+            // Nothing the request would change: write nothing, like writeConfigMutation's no-op skip.
+            if (!changed) {
                 unchanged = true;
                 return;
             }
-            // Strip roles.<id> entries for custom roles this request removes (see docstring).
-            // Structurally valid names only; anything else stays for validateConfig to reject — never
-            // dereference a request entry before validation.
-            const requestedNames = new Set();
-            for (const entry of entries) {
-                if (isJsonObject(entry) && typeof entry.name === "string")
-                    requestedNames.add(entry.name);
-            }
-            // Base the roles rewrite on the FILE's own section, not the loaded (catalog-merged)
-            // map: this whole-config write must not re-expand a partial section to every built-in
-            // (preserveFileRoles' rule). Only the removed custom roles' entries are stripped, and
-            // only from what the file actually holds.
-            const rawRolesCandidate = rawConfigObject(root).roles;
-            const roles = isJsonObject(rawRolesCandidate)
-                ? { ...(rawRolesCandidate) }
-                : {};
-            for (const c of current.customRoles) {
-                if (!requestedNames.has(c.name))
-                    delete roles[c.name];
-            }
-            const candidate = { ...current, customRoles: entries };
-            const candidateRecord = candidate;
-            if (rawRolesCandidate === undefined)
-                delete candidateRecord.roles;
-            else
-                candidateRecord.roles = roles;
             // Collapse legacy/new pi spellings before writing so a merged config (which always
             // carries the default piArgs) never lands both forms in the file — the next load's raw
             // pass rejects a file holding both `piArgs` and `backends.pi.args`.

package/dist/src/config/config-validation-roles.js

@@ -0,0 +1,271 @@
+/** The per-role and cross-field section rules of tumwater.json validation: the `customRoles`
+ * collect-and-check block, the `roles.<id>` entry block, `review.afterMerge`'s name check,
+ * the per-role daily cost caps and quiet hours, `maxConcurrentPerProvider`,
+ * `claudeWindowReserve` and its mutually-exclusive spelling pair, and the `idleBackoff`
+ * cross-field pair. Extracted from the single validateConfig gate (config-validation.ts) so a
+ * per-role or cross-field edit lands as a per-theme diff instead of a whole-gate one; this
+ * module runs once, at the gate's end, after every other section has appended its problems,
+ * so the overall problem order is unchanged. These rules sit on top of the generic machinery
+ * in config-field-checks.ts; the helpers passed in are the closures the gate binds once (the
+ * problems-bound checkers and the shared model-triple/window-reserve sequences), and the
+ * cross-cutting `customNames` set — collected in the customRoles block, consumed by the
+ * roles.<id>, afterMerge, cap and quiet-hour blocks — is owned here, so validateConfig
+ * passes no set across the boundary. */
+import { CUSTOM_ROLE_KEYS, CUSTOM_NAME_RE, CUSTOM_TASK_MAX_CHARS, ROLE_ENTRY_KEYS, ROLE_INSTRUCTIONS_MAX_CHARS, } from "./config-schema.js";
+import { DIRECTOR_ROLE, allRoleIds } from "../roles/roles.js";
+import { INSTANCE_ROLES, baseRoleOf } from "../roles/runner-ids.js";
+import { isJsonObject } from "../files/json-object.js";
+import { isNonBlankString } from "../text/text.js";
+import { parseQuietHours } from "../scheduling/quiet-hours.js";
+import { TUMWATER_SOURCE } from "../events/events.js";
+import { DOLLAR_CAP, MAX_DURATION_SECONDS, POSITIVE_INTEGER, checkKnownKeys, checkKnownRoleId, checkNumberField, show, } from "./config-field-checks.js";
+const DURATION_NON_NEGATIVE = {
+    ok: (n) => n >= 0 && n <= MAX_DURATION_SECONDS,
+    what: `a number of 0 or more, at most ${MAX_DURATION_SECONDS}`,
+};
+/** A per-role instance count (`roles.feature.instances`): an integer from 1 to 8. Bounded so
+ * a typo like `instances: 800` cannot spawn hundreds of runners, and integer so
+ * `feature-1.5` — which no role id can name — is refused. */
+const INSTANCE_COUNT = {
+    ok: (n) => Number.isInteger(n) && n >= 1 && n <= 8,
+    what: "an integer from 1 to 8",
+};
+/** Validate one per-role map section (`maxDailyCostUsdPerRole`, `quietHoursPerRole`): the
+ * value must be an object mapping role ids to entries, every key must name a known role
+ * (checkKnownRoleId's guard — a typo'd id would silently no-op the section), and each entry
+ * goes through `checkValue` with its role id. `expectation` is the value description the
+ * type-error message quotes. One home for the section shape the two dotted per-role keys
+ * share, so a third per-role map reuses it instead of re-copying the loop. */
+function checkPerRoleMap(r, key, expectation, customNames, problems, checkValue) {
+    if (!(key in r))
+        return;
+    const map = r[key];
+    if (!isJsonObject(map)) {
+        problems.push(`${key} must be an object mapping role ids to ${expectation} (got ${show(map)})`);
+        return;
+    }
+    for (const [id, value] of Object.entries(map)) {
+        if (!checkKnownRoleId(key, id, customNames, problems))
+            continue;
+        checkValue(id, value);
+    }
+}
+/** Validate the per-role and cross-field sections that close the gate: `customRoles`, the
+ * `roles.<id>` entries, `review.afterMerge`'s role names, the per-role caps and quiet hours,
+ * `maxConcurrentPerProvider`, `claudeWindowReserve` and the `idleBackoff` cross-field pair,
+ * each appended to `problems` in the order the gate produced. The single call site in
+ * validateConfig is the point where these problems were appended, so the order across the
+ * whole pass is unchanged. */
+export function validateRolesAndCrossField(r, problems, helpers) {
+    const customNames = validateCustomRoles(r, problems, helpers);
+    validateRoleEntries(r, problems, helpers, customNames);
+    validateReviewAfterMerge(r, problems, customNames);
+    validatePerRoleCostCaps(r, problems, customNames);
+    validatePerRoleQuietHours(r, problems, customNames);
+    validateMaxConcurrentPerProvider(r, problems);
+    validateClaudeWindowReserve(r, problems, helpers);
+    validateIdleBackoff(r, problems);
+}
+/** Collect the `customRoles` names and refuse this block's bad shapes, appending to
+ * `problems` and returning the set of accepted names for the later per-role sections. Names
+ * become worktree dirs and git refs (plans/user-defined-loops.md), so they are validated
+ * strictly — a colliding name would silently shadow a built-in's prompt (roleById wins in
+ * runPrompt), validation makes that impossible instead of subtle. The collected names feed
+ * the roles cross-check: an id under `roles` is valid when it is in the catalog OR listed as
+ * a customRoles name. */
+function validateCustomRoles(r, problems, helpers) {
+    const { checkPromptLength } = helpers;
+    const customNames = new Set();
+    if ("customRoles" in r) {
+        const cl = r.customRoles;
+        if (!Array.isArray(cl)) {
+            problems.push(`customRoles must be an array of { name, task } entries (got ${show(cl)})`);
+        }
+        else {
+            cl.forEach((entry, i) => {
+                const where = `customRoles[${i}]`;
+                if (!isJsonObject(entry)) {
+                    problems.push(`${where} must be an object with keys name and task (got ${show(entry)})`);
+                    return;
+                }
+                checkKnownKeys(entry, CUSTOM_ROLE_KEYS, where, problems);
+                const name = entry.name;
+                if (typeof name !== "string") {
+                    problems.push(`${where}.name must be a string matching /^[a-z0-9][a-z0-9_-]{0,31}$/ (got ${show(name)})`);
+                }
+                else if (!CUSTOM_NAME_RE.test(name)) {
+                    problems.push(`${where}.name "${name}" is not a valid role name: start with a lowercase letter or digit, then at most 31 more of [a-z0-9_-]`);
+                }
+                else if (name === TUMWATER_SOURCE) {
+                    problems.push(`${where}.name "${name}" is reserved: events tumwater writes about itself carry that source, so a role's events would be indistinguishable from them — pick another name`);
+                }
+                else if (allRoleIds().includes(name)) {
+                    problems.push(`${where}.name "${name}" collides with a built-in role id — pick another name`);
+                }
+                else if (baseRoleOf(name) !== name) {
+                    problems.push(`${where}.name "${name}" would shadow the ${baseRoleOf(name)} role's instance ids — pick another name`);
+                }
+                else if (customNames.has(name)) {
+                    problems.push(`${where}.name "${name}" is duplicated in customRoles — names must be unique`);
+                }
+                else {
+                    customNames.add(name);
+                }
+                const task = entry.task;
+                // A whitespace-only task is as inert as an empty one — it rides into every one of
+                // this role's run prefills as blank text, so the role has nothing to do and runs
+                // no_change forever. Reject both shapes with the same message; the model-triple
+                // checkString rule uses the same trim-based emptiness test.
+                if (!isNonBlankString(task)) {
+                    problems.push(`${where}.task must be a non-empty string (got ${show(task)})`);
+                }
+                else {
+                    checkPromptLength(`${where}.task`, task, CUSTOM_TASK_MAX_CHARS);
+                }
+            });
+        }
+    }
+    return customNames;
+}
+/** Validate the `roles.<id>` entry block: the object shape, `checkKnownRoleId`, the per-entry
+ * settings checks, and the INSTANCE_ROLES instances rule. */
+function validateRoleEntries(r, problems, helpers, customNames) {
+    const { checkString, checkBoolean, checkNumber, checkPromptLength, checkModelTripleEntry } = helpers;
+    if ("roles" in r) {
+        const roles = r.roles;
+        if (!isJsonObject(roles)) {
+            problems.push(`roles must be an object mapping role ids to settings (got ${show(roles)})`);
+        }
+        else {
+            for (const [id, rc] of Object.entries(roles)) {
+                // An id outside the catalog and customRoles cannot work: runPrompt has no prompt for
+                // it and the role would error every run forever (checkKnownRoleId).
+                if (!checkKnownRoleId("roles", id, customNames, problems))
+                    continue;
+                if (!isJsonObject(rc)) {
+                    problems.push(`roles.${id} must be an object (got ${show(rc)})`);
+                    continue;
+                }
+                const o = rc;
+                checkKnownKeys(o, ROLE_ENTRY_KEYS, `roles.${id}`, problems);
+                // Empty is a deliberate "no extra instructions". A non-empty value rides into every
+                // one of this role's run prefills, so it is capped like a custom role's task.
+                checkString(o, `roles.${id}.`, "instructions");
+                checkPromptLength(`roles.${id}.instructions`, o.instructions, ROLE_INSTRUCTIONS_MAX_CHARS);
+                checkModelTripleEntry(o, `roles.${id}.`, `roles.${id}`);
+                checkBoolean(o, `roles.${id}.`, "enabled");
+                checkNumber(o, `roles.${id}.`, "minRunIntervalSeconds", DURATION_NON_NEGATIVE);
+                // Only feature and bugfix may split (src/roles/runner-ids.ts INSTANCE_ROLES); an
+                // instances count under any other role would never spawn a runner, so reject it
+                // rather than let the operator believe it did something.
+                if ("instances" in o && !INSTANCE_ROLES.has(id)) {
+                    problems.push(`roles.${id}.instances is only valid for ${[...INSTANCE_ROLES].join(" and ")} (got ${show(o.instances)})`);
+                }
+                else {
+                    checkNumber(o, `roles.${id}.`, "instances", INSTANCE_COUNT);
+                }
+            }
+        }
+    }
+}
+/** Validate `review.afterMerge`'s role names: a typo'd id would silently keep that role
+ * reviewed before merging; the director is refused because its changes always merge on a
+ * review first. */
+function validateReviewAfterMerge(r, problems, customNames) {
+    if (isJsonObject(r.review) && Array.isArray(r.review.afterMerge)) {
+        r.review.afterMerge.forEach((id, i) => {
+            if (typeof id !== "string" || id.trim() === "")
+                return; // Already reported by checkStringArray.
+            if (id === DIRECTOR_ROLE)
+                problems.push(`review.afterMerge[${i}] must not be "${DIRECTOR_ROLE}" — its changes are always reviewed before merging`);
+            else
+                checkKnownRoleId("review.afterMerge", id, customNames, problems);
+        });
+    }
+}
+/** Validate the per-role daily cost caps (src/gates/role-cap-gates.ts): each key must name a
+ * known role — built-in or customRoles — because a typo'd id would silently no-op the cap,
+ * the exact silent-ignore class the `roles.<id>` check exists to prevent (the customNames set
+ * is fully collected by this point, so a custom role can be capped). Each value is a spend
+ * threshold with the NON_NEGATIVE_OR_DISABLED semantics: 0 disables that role's cap. */
+function validatePerRoleCostCaps(r, problems, customNames) {
+    checkPerRoleMap(r, "maxDailyCostUsdPerRole", "USD caps", customNames, problems, (id) => {
+        // Same MAX_SAFE_INTEGER bound as maxDailyCostUsd's DOLLAR_CAP rule (BUGS.md
+        // 2026-10-02): a finite-but-unrepresentable per-role cap is an effectively
+        // uncapped budget for that role — DOLLAR_CAP is that rule, so the predicate
+        // and its wording have one home. checkPerRoleMap narrowed the map, so the cast
+        // is sound and checkNumberField sees the entry's value typed as before.
+        checkNumberField(problems, r.maxDailyCostUsdPerRole, "maxDailyCostUsdPerRole.", id, DOLLAR_CAP);
+    });
+}
+/** Validate the per-role quiet hours (src/scheduling/quiet-hours.ts): the same known-role gate
+ * as the caps — a typo'd role id would silently no-op the window. Each value must parse as a
+ * quiet-hours window (an empty string means off for that role, the same disablement the
+ * team-wide key takes), and the message names the key and the offending id/value verbatim. */
+function validatePerRoleQuietHours(r, problems, customNames) {
+    checkPerRoleMap(r, "quietHoursPerRole", '"HH:MM-HH:MM" windows', customNames, problems, (id, value) => {
+        if (typeof value !== "string") {
+            problems.push(`quietHoursPerRole.${id} must be a "HH:MM-HH:MM" string like "23:00-07:00" (an empty string means off) (got ${show(value)})`);
+            return;
+        }
+        if (value.trim() === "")
+            return; // empty = off for that role
+        const parsed = parseQuietHours(value, `quietHoursPerRole.${id}`);
+        if (!parsed.ok)
+            problems.push(parsed.error);
+    });
+}
+/** Validate per-provider concurrency caps (plans/provider-concurrency.md §1): a map from
+ * provider key to a positive integer. Unlike the per-role maps, an unknown provider name is
+ * NOT a validation error — providers live in pi's models.json, which validation does not
+ * read, and a fallback's provider may only come into use later (doctor warns in part 5/5).
+ * Each value must be a positive integer under a non-empty key. */
+function validateMaxConcurrentPerProvider(r, problems) {
+    if (r.maxConcurrentPerProvider !== undefined) {
+        const map = r.maxConcurrentPerProvider;
+        if (!isJsonObject(map)) {
+            problems.push(`maxConcurrentPerProvider must be an object mapping provider names to concurrency caps (got ${show(map)})`);
+        }
+        else {
+            for (const [provider, value] of Object.entries(map)) {
+                if (provider.trim() === "") {
+                    problems.push(`maxConcurrentPerProvider.<empty> — a provider key must not be empty`);
+                    continue;
+                }
+                if (typeof value !== "number" || !Number.isFinite(value) || !POSITIVE_INTEGER.ok(value)) {
+                    problems.push(`maxConcurrentPerProvider.${provider} must be ${POSITIVE_INTEGER.what} (got ${show(value)})`);
+                }
+            }
+        }
+    }
+}
+/** Validate `claudeWindowReserve` (the subscription-window reserve: a map from window type to
+ * a fraction, 0 < f <= 1) and its mutually-exclusive spelling pair with
+ * `backends.claude.windowReserve`. */
+function validateClaudeWindowReserve(r, problems, helpers) {
+    const { checkWindowReserve } = helpers;
+    // The subscription-window reserve: a map from window type to a fraction, 0 < f <= 1.
+    if (r.claudeWindowReserve !== undefined)
+        checkWindowReserve("claudeWindowReserve", r.claudeWindowReserve);
+    // The reserve's two spellings are mutually exclusive (plans/codex-backend.md part 2b/9): the
+    // nested key is the current one; `claudeWindowReserve` is kept as claude's older spelling. A
+    // file holding both is ambiguous about which drives the window, so it is rejected naming both.
+    if (r.claudeWindowReserve !== undefined &&
+        isJsonObject(r.backends) &&
+        isJsonObject(r.backends.claude) &&
+        r.backends.claude.windowReserve !== undefined)
+        problems.push("claudeWindowReserve and backends.claude.windowReserve set the same value — keep one (backends.claude.windowReserve is the current spelling; claudeWindowReserve is its old name)");
+}
+/** Validate the `idleBackoff` cross-field pair (judged on the merged config, where both sides
+ * are always present; on a raw file only when the file itself names both): scheduleBackoff
+ * clamps every idle wait — the first included — to min(initialSeconds, maxSeconds), so a
+ * smaller max silently discards the configured initial wait. Name both values so one edit
+ * fixes the pair. */
+function validateIdleBackoff(r, problems) {
+    const backoff = r.idleBackoff;
+    if (isJsonObject(backoff) &&
+        typeof backoff.initialSeconds === "number" &&
+        typeof backoff.maxSeconds === "number" &&
+        backoff.maxSeconds < backoff.initialSeconds)
+        problems.push(`idleBackoff.maxSeconds (${show(backoff.maxSeconds)}) must be ≥ idleBackoff.initialSeconds (${show(backoff.initialSeconds)}) — every idle wait is clamped to the smaller, so the smaller max would silently shorten the configured first wait`);
+}