@event4u/agent-config 14.1.0 → 14.4.0

package/src/scripts/_lib/stdin.ts

@@ -41,6 +41,31 @@ function _sleepSync(ms: number): void {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+/** Options for {@link readStdinText}. */
+export interface ReadStdinOptions {
+    /**
+     * Give up and return `''` when the FIRST byte has not arrived within this
+     * many milliseconds. Undefined (the default) keeps the historical behaviour:
+     * the full {@link MAX_RETRIES} budget applies from the first read, which is
+     * what a `gh pr diff` pipe needs — its first byte can legitimately take a
+     * while, and reporting that as empty input is the defect this module exists
+     * to prevent.
+     *
+     * A HOOK is the opposite case, and it cost a CI hang to learn the difference.
+     * The host writes the payload synchronously on spawn, so a byte that has not
+     * arrived promptly is not a slow writer — it is an fd 0 nobody will ever
+     * write to, which is what a child inherits when a test spawns it without
+     * piping stdin. With no cap the dispatcher then span the full ~10 s budget on
+     * EVERY such invocation and returned "" anyway; measured 12.4 s per call
+     * against an immediate return before the retry loop existed. Hundreds of
+     * those hung three Node-Tests shards for over an hour.
+     *
+     * Once ANY byte has arrived the cap no longer applies: a writer demonstrably
+     * exists, so the full budget is right and the large-payload fix is intact.
+     */
+    firstByteTimeoutMs?: number;
+}
+
 /**
  * Read all of fd 0 as UTF-8.
  *
@@ -48,10 +73,13 @@ function _sleepSync(ms: number): void {
  *         {@link MAX_RETRIES} consecutive EAGAINs — a caller must not be able to
  *         mistake a failed read for empty input.
  */
-export function readStdinText(fd = 0): string {
+export function readStdinText(fd = 0, opts: ReadStdinOptions = {}): string {
     const chunks: Buffer[] = [];
     const buf = Buffer.alloc(CHUNK);
     let retries = 0;
+    let got_any = false;
+    const first_byte_deadline =
+        opts.firstByteTimeoutMs === undefined ? null : Date.now() + opts.firstByteTimeoutMs;
     for (;;) {
         let read: number;
         try {
@@ -60,6 +88,11 @@ export function readStdinText(fd = 0): string {
         } catch (exc) {
             const code = (exc as NodeJS.ErrnoException).code;
             if (code === 'EAGAIN') {
+                // An idle fd 0 is "no input", not a slow writer — but only
+                // before the first byte. See ReadStdinOptions.firstByteTimeoutMs.
+                if (!got_any && first_byte_deadline !== null && Date.now() >= first_byte_deadline) {
+                    return '';
+                }
                 retries += 1;
                 if (retries > MAX_RETRIES) {
                     throw new Error(
@@ -76,6 +109,7 @@ export function readStdinText(fd = 0): string {
             throw exc;
         }
         if (read === 0) break;
+        got_any = true;
         chunks.push(Buffer.from(buf.subarray(0, read)));
     }
     return Buffer.concat(chunks).toString('utf-8');

package/src/scripts/_lib/turn_end_refusals.ts

@@ -45,10 +45,18 @@ import { read_lockfile } from './installed_lock.js';
  *
  * The roadmap's § 0 names three (A promissory, B language, C verification).
  * That was true of the draft and is not true of the tree: detector D
- * (`completion`) landed under round 7 § Phase 1 and is in the same
- * unconditional list as the other three. Counting three would silently drop a
- * detector's refusals, so the set is read off `DetectorId` in the gate rather
- * than off the prose.
+ * (`completion`) landed under round 7 § Phase 1 and runs in the same detector
+ * list as the other three. Counting three would silently drop a detector's
+ * refusals, so the set is read off `DetectorId` in the gate rather than off the
+ * prose.
+ *
+ * This said "the same UNCONDITIONAL list" until 2026-08-18, which was wrong and
+ * is worth naming rather than quietly rewording: `main()` runs A and D only when
+ * no subagent dispatch is open. It does not change this set — every detector
+ * that CAN fire needs a counter — but it does change what a reader may conclude
+ * from a zero here: A's and D's counts are censored by that third allow path,
+ * and `docs/contracts/turn-end-detector-demotion.md` is where that consequence
+ * is carried.
  */
 export const DETECTOR_IDS = [
     'promissory',

package/src/scripts/_lib/unattended_guard.ts

@@ -0,0 +1,371 @@
+/**
+ * unattended_guard — the three preconditions an unattended run must clear
+ * before anything spawns, and the ledger that bounds it once it has.
+ *
+ * road-to-long-horizon-execution Phase 4.0 (sequencing UOTL Phase 7.1).
+ *
+ * ## What this is, and what it deliberately is not
+ *
+ * It is NOT the spawner. There is no `spawnHeadlessAgent` here and that is a
+ * decision, not an omission — see § "Why the spawn is not in this file".
+ *
+ * It IS the layer that has to be right BEFORE a spawn is safe, and every part
+ * of it is testable offline with no spend:
+ *
+ *   1. **Remote safety.** A worktree an unattended agent works in must carry
+ *      no production remote. UOTL 7.1 says so; the failure it prevents is an
+ *      unattended push reaching a real remote because a worktree inherited
+ *      the parent's `origin`.
+ *   2. **A budget with a ledger.** A cap nobody decrements is a comment. The
+ *      ledger is a file, spend is booked against it, and an exhausted budget
+ *      refuses — before the call, never after.
+ *   3. **Job dedup.** Two schedulers, or one scheduler and one human, must
+ *      not run the same roadmap at the same head twice. The key is derived
+ *      from the work, not from a random id, so the second caller recognises
+ *      the first caller's job.
+ *
+ * ## Why the spawn is not in this file
+ *
+ * Writing a spawner means choosing an invocation shape, an auth path and a
+ * sandbox posture for a process that spends money with nobody watching. Each
+ * of those is a decision with a blast radius, and none of them is testable
+ * without spending. Shipping an untested one behind a flag that reads as
+ * finished is how a capability nobody validated ends up in a scheduler.
+ *
+ * The guard lands first on purpose: it is the half that can be verified, and
+ * it is the half whose absence makes the other half unsafe. Phase 4.2's
+ * pre-registered demotion gate has to exist before a first unattended run
+ * either way, so the ordering costs nothing.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const BUDGET_REL = path.join('agents', 'runtime', 'state', 'unattended-budget.json');
+export const JOBS_REL = path.join('agents', 'runtime', 'state', 'unattended-jobs.json');
+
+/**
+ * Remote URL fragments that mark a remote as PRODUCTION-reachable.
+ *
+ * Deliberately a shape test rather than a host allowlist: the question is not
+ * "which forge" but "can a push from here reach something real". A local path
+ * remote or a remote pointing inside this checkout cannot; anything that
+ * resolves over the network can.
+ */
+export function isProductionRemote(url: string): boolean {
+    const u = url.trim();
+    if (u === '') return false;
+    // ONLY a recognisably-local remote is non-production. Everything else is
+    // treated as reachable, including a shape this function does not know.
+    //
+    // R2 round 4, finding 6. The test used to be positive — enumerate the
+    // network shapes and return false otherwise — which meant an unrecognised
+    // URL cleared the "no production remote" precondition. An SSH-config alias
+    // is the concrete case: `gh:org/repo.git` matches no prefix here and fails
+    // the scp-style pattern (which requires `user@host:`), yet a push through
+    // it reaches GitHub exactly as `git@github.com:` does. The whole module
+    // fails CLOSED on an unreadable git config for precisely this reason, and
+    // this one function was reading "I do not recognise it" as "it is safe".
+    //
+    // A filesystem path — a sibling worktree, a bare mirror on disk. A push
+    // there is recoverable and reaches nobody.
+    if (u.startsWith('/') || u.startsWith('.') || u.startsWith('~') || u.startsWith('file://')) {
+        return false;
+    }
+    return true;
+}
+
+export interface RemoteVerdict {
+    readonly safe: boolean;
+    /** Every remote found, so a refusal can name the one that failed. */
+    readonly remotes: ReadonlyArray<{ name: string; url: string; production: boolean }>;
+    readonly reason: string;
+}
+
+/**
+ * Is this worktree safe for an unattended agent to work in?
+ *
+ * Fails CLOSED on an unreadable git config: "I could not tell" and "there is
+ * no production remote" must not resolve to the same answer when the
+ * consequence of being wrong is an unattended push to a real remote.
+ */
+export function checkRemotes(worktree: string): RemoteVerdict {
+    const r = spawnSync('git', ['remote', '-v'], { cwd: worktree, encoding: 'utf-8' });
+    if (r.status !== 0) {
+        return {
+            safe: false,
+            remotes: [],
+            reason:
+                `could not read remotes in ${worktree} (git exited ${String(r.status)}) — ` +
+                `refusing, because "unreadable" and "none" must not mean the same thing here`,
+        };
+    }
+    // BOTH rows, and the push row decides. R2 round 6, finding 5: parsing only
+    // `(fetch)` judged a remote by the URL it reads from, while the thing this
+    // precondition guards against is a PUSH. `git remote -v` emits a separate
+    // `(push)` row whenever `pushurl` diverges, so a worktree with
+    // `url = /srv/mirrors/repo.git` and `pushurl = git@github.com:org/repo.git`
+    // read as local and cleared the gate — fail-open, in the one module whose
+    // stated posture is fail-closed.
+    //
+    // A remote is production if EITHER of its URLs is, because either one
+    // being reachable is enough for the harm this check exists to prevent.
+    const urls = new Map<string, Set<string>>();
+    for (const line of (r.stdout ?? '').split('\n')) {
+        const m = /^(\S+)\s+(\S+)\s+\((fetch|push)\)$/.exec(line.trim());
+        if (m === null) continue;
+        const name = m[1] as string;
+        const set = urls.get(name) ?? new Set<string>();
+        set.add(m[2] as string);
+        urls.set(name, set);
+    }
+    const remotes = [...urls.entries()].map(([name, set]) => {
+        const all = [...set];
+        const prod = all.filter((u) => isProductionRemote(u));
+        return {
+            name,
+            // The production URL is the one worth naming in a refusal.
+            url: (prod[0] ?? all[0]) as string,
+            production: prod.length > 0,
+        };
+    });
+    const bad = remotes.filter((x) => x.production);
+    if (bad.length > 0) {
+        return {
+            safe: false,
+            remotes,
+            reason:
+                `production-reachable remote(s): ${bad.map((b) => `${b.name} → ${b.url}`).join(', ')} — ` +
+                `an unattended run must not be able to push to a real remote (UOTL 7.1)`,
+        };
+    }
+    return { safe: true, remotes, reason: 'no production-reachable remote' };
+}
+
+/** The cap and what has been spent against it. */
+export interface UnattendedBudget {
+    schema_version: 1;
+    /** Hard ceiling in USD. `0` disables unattended runs entirely. */
+    max_usd: number;
+    /** Hard ceiling in tokens across the window. `0` disables. */
+    max_tokens: number;
+    spent_usd: number;
+    spent_tokens: number;
+    /** ISO date the window opened; a new UTC day resets both counters. */
+    window_opened: string;
+}
+
+export function emptyBudget(day: string): UnattendedBudget {
+    // Both ceilings default to ZERO, which disables unattended runs. An
+    // absent budget file must not read as "unlimited" — that is the one
+    // default that turns a missing config into unbounded spend.
+    return {
+        schema_version: 1,
+        max_usd: 0,
+        max_tokens: 0,
+        spent_usd: 0,
+        spent_tokens: 0,
+        window_opened: day,
+    };
+}
+
+export function utcDay(now: Date = new Date()): string {
+    return now.toISOString().slice(0, 10);
+}
+
+export function readBudget(repoRoot: string, now: Date = new Date()): UnattendedBudget {
+    const day = utcDay(now);
+    let raw: unknown;
+    try {
+        raw = JSON.parse(fs.readFileSync(path.join(repoRoot, BUDGET_REL), 'utf-8'));
+    } catch {
+        return emptyBudget(day);
+    }
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return emptyBudget(day);
+    const o = raw as Record<string, unknown>;
+    const num = (k: string): number => {
+        const v = o[k];
+        return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0;
+    };
+    const opened = typeof o['window_opened'] === 'string' ? o['window_opened'] : day;
+    // A new UTC day rolls the window: the caps persist, the spend resets.
+    const rolled = opened !== day;
+    return {
+        schema_version: 1,
+        max_usd: num('max_usd'),
+        max_tokens: num('max_tokens'),
+        spent_usd: rolled ? 0 : num('spent_usd'),
+        spent_tokens: rolled ? 0 : num('spent_tokens'),
+        window_opened: rolled ? day : opened,
+    };
+}
+
+export function writeBudget(repoRoot: string, b: UnattendedBudget): void {
+    const file = path.join(repoRoot, BUDGET_REL);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(b, null, 2)}\n`, 'utf-8');
+}
+
+export interface BudgetVerdict {
+    readonly allowed: boolean;
+    readonly reason: string;
+}
+
+/**
+ * May a run costing `usd` / `tokens` proceed?
+ *
+ * Checked BEFORE the call, never after: a cap enforced on the way out has
+ * already been exceeded by the time it fires.
+ */
+export function checkBudget(b: UnattendedBudget, usd: number, tokens: number): BudgetVerdict {
+    if (b.max_usd <= 0 && b.max_tokens <= 0) {
+        return {
+            allowed: false,
+            reason:
+                'no unattended budget configured (both ceilings are 0) — an absent budget ' +
+                'disables unattended runs rather than permitting unbounded ones',
+        };
+    }
+    // Each ceiling is checked INDEPENDENTLY, and a 0 on either dimension
+    // refuses any consumption of it rather than skipping the check.
+    //
+    // R2 review, finding 5. The guarded form was `max_tokens > 0 && …`, so an
+    // operator writing `{max_usd: 5, max_tokens: 0}` — following the field's
+    // own "`0` disables" — got an UNBOUNDED token allowance, and `digest()`
+    // then printed `N/0 tokens`, which reads as an exhausted cap while runs
+    // were being permitted. The whole point of this module's zero-default is
+    // that a missing number never means unlimited; a zero written on purpose
+    // must mean the same thing as a zero left unset.
+    if (b.max_usd <= 0 && usd > 0) {
+        return {
+            allowed: false,
+            reason: `USD ceiling is 0 (disabled) and ${usd} was projected`,
+        };
+    }
+    if (b.max_usd > 0 && b.spent_usd + usd > b.max_usd) {
+        return {
+            allowed: false,
+            reason: `USD ceiling: ${b.spent_usd} spent + ${usd} projected > ${b.max_usd}`,
+        };
+    }
+    if (b.max_tokens <= 0 && tokens > 0) {
+        return {
+            allowed: false,
+            reason: `token ceiling is 0 (disabled) and ${tokens} was projected`,
+        };
+    }
+    if (b.max_tokens > 0 && b.spent_tokens + tokens > b.max_tokens) {
+        return {
+            allowed: false,
+            reason: `token ceiling: ${b.spent_tokens} spent + ${tokens} projected > ${b.max_tokens}`,
+        };
+    }
+    return { allowed: true, reason: 'within budget' };
+}
+
+export function bookSpend(
+    b: UnattendedBudget,
+    usd: number,
+    tokens: number,
+): UnattendedBudget {
+    return { ...b, spent_usd: b.spent_usd + usd, spent_tokens: b.spent_tokens + tokens };
+}
+
+/**
+ * The dedup key for one unit of unattended work.
+ *
+ * Derived from WHAT is being done — roadmap plus the commit it starts from —
+ * not from a random id, so a second caller with the same work recognises the
+ * first caller's job. A random id would make every duplicate look new, which
+ * is exactly the collision this exists to catch.
+ */
+export function jobKey(roadmapSlug: string, head: string): string {
+    return `${roadmapSlug}@${head.slice(0, 12)}`;
+}
+
+export type JobLedger = Record<string, { started_at: string }>;
+
+export function readJobs(repoRoot: string): JobLedger {
+    try {
+        const raw: unknown = JSON.parse(fs.readFileSync(path.join(repoRoot, JOBS_REL), 'utf-8'));
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return {};
+        const out: JobLedger = {};
+        for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+            if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+                const started = (v as Record<string, unknown>)['started_at'];
+                if (typeof started === 'string') out[k] = { started_at: started };
+            }
+        }
+        return out;
+    } catch {
+        return {};
+    }
+}
+
+export function writeJobs(repoRoot: string, jobs: JobLedger): void {
+    const file = path.join(repoRoot, JOBS_REL);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(jobs, null, 2)}\n`, 'utf-8');
+}
+
+export interface PreflightInput {
+    readonly repoRoot: string;
+    readonly worktree: string;
+    readonly roadmapSlug: string;
+    readonly head: string;
+    readonly projectedUsd: number;
+    readonly projectedTokens: number;
+    readonly now?: Date;
+}
+
+export interface PreflightVerdict {
+    readonly ok: boolean;
+    /** Every failed precondition, not just the first — one run, one full answer. */
+    readonly refusals: readonly string[];
+    readonly jobKey: string;
+}
+
+/**
+ * All three preconditions, reported together.
+ *
+ * Returns every refusal rather than short-circuiting: an operator fixing one
+ * precondition at a time round-trips N times, and the whole point of a
+ * preflight is that it answers in one pass.
+ *
+ * THE DEDUP PRECONDITION CANNOT FIRE TODAY, and that is stated here rather
+ * than implied by a passing read. It queries the job ledger correctly, but
+ * nothing in the tree WRITES that ledger: `writeJobs`, `bookSpend` and
+ * `writeBudget` have no production caller, so two callers racing the same
+ * `roadmap@head` both receive `ok: true`. R2 review, finding 13 — the module
+ * previously listed dedup among its three preconditions with no note, which
+ * describes a control that is not there.
+ *
+ * The write half belongs to the spawn, which Phase 4.0 deliberately does not
+ * build. The claim-and-release lifecycle is the spawn's to own: a claim
+ * written by a checker that never learns whether the job started would strand
+ * the key on every crash and turn the dedup into a permanent refusal. Until
+ * the spawn exists, treat this as a read that is ready for a writer, never as
+ * a live guarantee.
+ */
+export function preflight(input: PreflightInput): PreflightVerdict {
+    const refusals: string[] = [];
+    const key = jobKey(input.roadmapSlug, input.head);
+
+    const remotes = checkRemotes(input.worktree);
+    if (!remotes.safe) refusals.push(`remote: ${remotes.reason}`);
+
+    const budget = readBudget(input.repoRoot, input.now ?? new Date());
+    const verdict = checkBudget(budget, input.projectedUsd, input.projectedTokens);
+    if (!verdict.allowed) refusals.push(`budget: ${verdict.reason}`);
+
+    const jobs = readJobs(input.repoRoot);
+    if (jobs[key] !== undefined) {
+        refusals.push(
+            `dedup: job '${key}' already started at ${jobs[key]?.started_at ?? 'unknown'} — ` +
+                `the same roadmap at the same head is already in flight`,
+        );
+    }
+
+    return { ok: refusals.length === 0, refusals, jobKey: key };
+}

package/src/scripts/ai_council/config.ts

@@ -94,6 +94,16 @@ const _VALID_PROVIDERS: ReadonlySet<string> = new Set([
 ]);
 const _VALID_MODES: ReadonlySet<string> = new Set(['api', 'manual', 'cli', 'auto']);
 
+// The fallback/second-model surfaces live in `fallback_config.ts` — this file
+// is far over the source ceiling and the documented fix is extraction.
+const _FALLBACK_DEPS = {
+    isDict: _isDict as (v: unknown) => v is Dict,
+    isBool: _isBool as (v: unknown) => v is boolean,
+    isStr: _isStr as (v: unknown) => v is string,
+    repr: _pyRepr, typeName: _pyTypeName, sortedListRepr: _sortedListRepr,
+    error: (msg: string): Error => new CouncilConfigError(msg),
+};
+
 /**
  * Prefixes that signal "this is a raw API key" so we refuse it loudly
  * even when the user accidentally inlined it in `api_key_ref`.
@@ -537,6 +547,12 @@ const _VALID_CHAIRMAN_MODES: ReadonlySet<string> = new Set(['host', 'member', 'a
 export interface DecisionResolutionEntry {
     readonly mode: string;
     readonly confidence_threshold: number;
+    /**
+     * OPTIONAL local second-model rung — UOTL Phase 4.1. Absent (`null`) →
+     * the ladder is unchanged. Provider set, quota binding and the locked-class
+     * refusal live in `fallback_config.ts::buildSecondModel`.
+     */
+    readonly second_model: string | null;
 }
 
 /** Opt-in fuzzy matching for the corpus-aware classifier (step-9 P5). */
@@ -617,6 +633,9 @@ export type QuorumSetting = 'majority' | number;
  */
 export type QuorumMinPresent = number;
 
+export type { FallbackConfig } from './fallback_config.js';
+import { buildFallback, buildSecondModel, type FallbackConfig as _FallbackConfig } from './fallback_config.js';
+
 export interface CouncilConfig {
     readonly enabled: boolean;
     readonly defaults: DefaultsConfig;
@@ -627,6 +646,7 @@ export interface CouncilConfig {
     readonly cli_call_budget: CliCallBudgetConfig;
     readonly quorum: QuorumSetting;
     readonly quorum_min_present: QuorumMinPresent;
+    readonly fallback: _FallbackConfig;
     readonly necessity_classifier: NecessityClassifierConfig;
     readonly model_downgrade: ModelDowngradeConfig;
     readonly debate: DebateConfig;
@@ -881,6 +901,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
     const quorum_min_present = _build_quorum_min_present(
         _get(raw, 'quorum_min_present', SOLO_FLOOR_MIN_PRESENT),
     );
+    const fallback = buildFallback(_get(raw, 'fallback', {}), _FALLBACK_DEPS);
     const necessity_classifier = _build_necessity_classifier(
         _asDict(_getOr(raw, 'necessity_classifier', {})),
     );
@@ -931,6 +952,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         cli_call_budget,
         quorum,
         quorum_min_present,
+        fallback,
         necessity_classifier,
         model_downgrade,
         debate,
@@ -1309,7 +1331,11 @@ function _build_decision_resolution(d: Dict): DecisionResolutionConfig {
                     `must be in [0.0, 1.0] (got ${_pyRepr(_f(threshold))}).`,
             );
         }
-        classes.set(cls, { mode, confidence_threshold: threshold });
+        // UOTL Phase 4.1 — the optional local rung, REFUSED on a locked
+        // class rather than ignored: a dropped key reads as configured.
+            const second_model = buildSecondModel(
+            entry_raw as Record<string, unknown>, cls, _LOCKED_IMPACT_CLASSES, _FALLBACK_DEPS);
+        classes.set(cls, { mode, confidence_threshold: threshold, second_model });
     }
     const fast_path_raw = _getOr(d, 'fast_path', {});
     if (!_isDict(fast_path_raw)) {

package/src/scripts/ai_council/events_log.ts

@@ -66,13 +66,24 @@ import type { AbsentReason } from './transport_resolver.js';
  */
 export const SCHEMA_VERSION = 4;
 
-export type EventAction = 'proceed' | 'skip_necessity' | 'block_quota' | 'quorum_result';
+export type EventAction =
+    | 'proceed'
+    | 'skip_necessity'
+    | 'block_quota'
+    | 'quorum_result'
+    | 'transport_fallback';
 
 const _VALID_ACTIONS: ReadonlySet<string> = new Set([
     'proceed',
     'skip_necessity',
     'block_quota',
     'quorum_result',
+    // A seat lost its cli transport mid-pass and was retried on the metered
+    // api rung. Without this action, attendance analysis cannot tell a seat
+    // SAVED by the fallback from a seat that was natively api all along — the
+    // two are indistinguishable in the response set, and only one of them
+    // costs money that the operator did not plan.
+    'transport_fallback',
 ]);
 
 /**

package/src/scripts/ai_council/fallback_config.ts

@@ -0,0 +1,114 @@
+/**
+ * fallback_config — the two config surfaces the question ladder added, kept
+ * out of `config.ts` because that file is 800 lines over the source ceiling
+ * and the documented fix is extraction rather than a raised baseline
+ * (`gate-violation-baselines.json` § check_source_size_budget).
+ *
+ * Behavioural contract: `docs/contracts/ai-council-config.md` — § "Mid-flight
+ * fallback is failure-class-gated" for `fallback.api_on_quota`, § "Decision
+ * classes" for `second_model`. The reasons a reader needs AT the code are
+ * here; the rest is there rather than duplicated.
+ */
+
+/**
+ * `fallback.*` — the mid-flight cli→api retry's one configurable knob.
+ *
+ * Modelled rather than read leniently off the raw dict for a mechanical
+ * reason: `council_cli.ts::load_settings` does not hand callers the file, it
+ * hands them a block SYNTHESIZED from `CouncilConfig`. A key this type does
+ * not carry cannot reach `build_members`, whatever the operator wrote — the
+ * same defect `quorum` and `quorum_min_present` each shipped once already.
+ */
+export interface FallbackConfig {
+    /**
+     * May an exhausted CLI quota retry on the metered api rung? Default
+     * `false`. The no-double-charge classes are always eligible and never
+     * consult this; `timeout` / 5xx are never eligible under any value.
+     */
+    readonly api_on_quota: boolean;
+}
+
+/**
+ * Providers a `second_model` rung may name — a SUBSET of the five
+ * `members:` accepts, and of `council_cli.ts::_CLI_PROVIDERS`.
+ *
+ * `xai` and `perplexity` ship COMMUNITY CLI wrappers that consume an API key
+ * and set `billable = true`, so routing a resolution there would spend USD on
+ * the rung whose entire purpose is not to. The discriminator is
+ * `billable === false`, not "has a cli subclass" — the wider set would have
+ * been the easy read and the wrong one.
+ */
+export const SECOND_MODEL_PROVIDERS: ReadonlySet<string> = new Set([
+    'anthropic',
+    'openai',
+    'gemini',
+]);
+
+export interface FallbackBuilderDeps {
+    readonly isDict: (v: unknown) => v is Record<string, unknown>;
+    readonly isBool: (v: unknown) => v is boolean;
+    readonly isStr: (v: unknown) => v is string;
+    readonly repr: (v: unknown) => string;
+    readonly typeName: (v: unknown) => string;
+    readonly sortedListRepr: (s: ReadonlySet<string>) => string;
+    readonly error: (msg: string) => Error;
+}
+
+/**
+ * Validate the `fallback` block.
+ *
+ * Asymmetric on purpose. A malformed BLOCK is tolerated as absent — the key's
+ * whole job is to WITHHOLD spend, so a garbled container degrading to "off" is
+ * safe, and a config that fails to load is worse. A malformed `api_on_quota`
+ * VALUE is refused: `"yes"` is an operator trying to authorise spend, and
+ * silently reading that as `false` would be as wrong as reading it as `true`.
+ */
+export function buildFallback(raw: unknown, d: FallbackBuilderDeps): FallbackConfig {
+    if (!d.isDict(raw)) return { api_on_quota: false };
+    const v = raw['api_on_quota'];
+    if (v === undefined) return { api_on_quota: false };
+    if (!d.isBool(v)) {
+        throw d.error(
+            `\`fallback.api_on_quota\`=${d.repr(v)} must be a boolean (got ${d.typeName(v)}).`,
+        );
+    }
+    return { api_on_quota: v };
+}
+
+/**
+ * Validate one decision class's optional `second_model` rung.
+ *
+ * Absent → `null`. Present on a LOCKED class → hard error, even for an
+ * explicit `null`: those classes do not have this dimension, and accepting the
+ * key at any value teaches its author that they do. Present with a provider
+ * outside the USD-neutral set → hard error naming the set, because the failure
+ * this rung exists to prevent is a halt and silently disabling it would
+ * reintroduce that halt at the moment it is needed.
+ */
+export function buildSecondModel(
+    entry: Record<string, unknown>,
+    cls: string,
+    locked: ReadonlySet<string>,
+    d: FallbackBuilderDeps,
+): string | null {
+    if (!('second_model' in entry)) return null;
+    if (locked.has(cls)) {
+        throw d.error(
+            `decision_resolution.classes.${cls}.second_model=${d.repr(entry['second_model'])}: ` +
+                `a second-model rung is not configurable for high-impact / user-required ` +
+                `decisions — those classes are LOCKED to \`user\` (Iron Law) and never resolve ` +
+                `on a model of any kind.`,
+        );
+    }
+    const raw = entry['second_model'];
+    if (raw === null) return null;
+    if (!(d.isStr(raw) && SECOND_MODEL_PROVIDERS.has(raw))) {
+        throw d.error(
+            `decision_resolution.classes.${cls}.second_model=${d.repr(raw)} not in ` +
+                `${d.sortedListRepr(SECOND_MODEL_PROVIDERS)} — the rung must be a provider whose ` +
+                `local CLI runs under subscription auth, so a resolution can never become ` +
+                `metered USD spend.`,
+        );
+    }
+    return raw;
+}