@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/ai_council/clients.ts

@@ -148,7 +148,18 @@ export const CODEX_MEASURED_UNSERVABLE: ReadonlyMap<string, string> = new Map([
 ]);
 
 export const DEFAULT_OPENAI_CLI_MODEL = OPENAI_CLI_VENDOR_DEFAULT;
-export const DEFAULT_ANTHROPIC_CLI_MODEL = 'claude-sonnet-4-5';
+// A vendor ALIAS, not a version. `claude --help` documents 'fable', 'opus' and
+// 'sonnet' as "an alias for the latest model" in their band, so an alias cannot
+// go stale the way a dated id can — which is the whole point of the change that
+// put it here.
+//
+// It was `'claude-sonnet-4-5'`, and this line is the half the roadmap that
+// found the defect did not know about: refreshing only the template's pin would
+// have left every member that omits `model:` falling back to the SAME stale id
+// from code. Read from the provider's own CLI surface on 2026-08-22, never from
+// the agent's recall — the source that road-to-council-seat-selection's own
+// Risk 1 declares inadmissible.
+export const DEFAULT_ANTHROPIC_CLI_MODEL = 'sonnet';
 export const DEFAULT_GEMINI_CLI_MODEL = 'gemini-2.5-pro';
 
 // OpenAI-API-compatible endpoints. xAI and Perplexity both expose the

package/src/scripts/ai_council/config.ts

@@ -144,121 +144,6 @@ export class CouncilConfigError extends Error {
     }
 }
 
-// ── Python-format helpers (byte-faithful error messages) ───────────
-
-/** Python `repr()` for a string scalar (single-quoted, escaped). */
-function _pyReprStr(s: string): string {
-    const hasSingle = s.includes("'");
-    const hasDouble = s.includes('"');
-    const quote = hasSingle && !hasDouble ? '"' : "'";
-    let body = s
-        .replace(/\\/g, '\\\\')
-        .replace(/\n/g, '\\n')
-        .replace(/\r/g, '\\r')
-        .replace(/\t/g, '\\t');
-    if (quote === "'") {
-        body = body.replace(/'/g, "\\'");
-    } else {
-        body = body.replace(/"/g, '\\"');
-    }
-    return `${quote}${body}${quote}`;
-}
-
-/** Python `repr()` for a float value (shortest round-trip, `N.0` for ints). */
-function _pyReprFloat(value: number): string {
-    if (Number.isInteger(value) && Number.isFinite(value)) {
-        return `${value}.0`;
-    }
-    if (value === Infinity) {
-        return 'inf';
-    }
-    if (value === -Infinity) {
-        return '-inf';
-    }
-    if (Number.isNaN(value)) {
-        return 'nan';
-    }
-    return String(value);
-}
-
-/**
- * Python `repr()` for an arbitrary parsed value. Floats are tracked via
- * `_FLOAT` so int-valued floats render `N.0`; bare numbers render as
- * Python ints (no decimal). Mirrors `{value!r}` formatting.
- */
-function _pyRepr(value: unknown): string {
-    if (value instanceof _Float) {
-        return _pyReprFloat(value.value);
-    }
-    if (value === null || value === undefined) {
-        return 'None';
-    }
-    if (typeof value === 'boolean') {
-        return value ? 'True' : 'False';
-    }
-    if (typeof value === 'string') {
-        return _pyReprStr(value);
-    }
-    if (typeof value === 'number') {
-        return String(value);
-    }
-    if (Array.isArray(value)) {
-        return `[${value.map((v) => _pyRepr(v)).join(', ')}]`;
-    }
-    if (typeof value === 'object') {
-        const parts: string[] = [];
-        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-            parts.push(`${_pyReprStr(k)}: ${_pyRepr(v)}`);
-        }
-        return `{${parts.join(', ')}}`;
-    }
-    return String(value);
-}
-
-/** Wrapper marking a number that should `repr()` as a Python float. */
-class _Float {
-    constructor(readonly value: number) {}
-}
-
-/** Mark `n` so `_pyRepr` renders it with a Python float repr (`N.0`). */
-function _f(n: number): _Float {
-    return new _Float(n);
-}
-
-/** Python `type(value).__name__`. */
-function _pyTypeName(value: unknown): string {
-    if (value === null || value === undefined) {
-        return 'NoneType';
-    }
-    if (typeof value === 'boolean') {
-        return 'bool';
-    }
-    if (typeof value === 'number') {
-        return Number.isInteger(value) ? 'int' : 'float';
-    }
-    if (typeof value === 'string') {
-        return 'str';
-    }
-    if (Array.isArray(value)) {
-        return 'list';
-    }
-    if (typeof value === 'object') {
-        return 'dict';
-    }
-    return typeof value;
-}
-
-/** Python `sorted(set_of_strings)` rendered as a list repr `['a', 'b']`. */
-function _sortedListRepr(items: Iterable<string>): string {
-    const sorted = [...items].sort();
-    return `[${sorted.map((s) => _pyReprStr(s)).join(', ')}]`;
-}
-
-/** Python `oct(mode)` → `0o600`-shaped string. */
-function _pyOct(mode: number): string {
-    return `0o${mode.toString(8)}`;
-}
-
 // ── Python int()/float() coercion + isinstance helpers ─────────────
 
 /**
@@ -432,6 +317,19 @@ export interface MemberConfig {
      * the falsification condition that gates ever enabling `'1h'`.
      */
     readonly prompt_cache_ttl: '5m' | '1h';
+    /**
+     * Optional `YYYY-MM-DD` stamp: the date this member's `model:` pin was last
+     * checked against the provider's own surface. `null` when unset.
+     *
+     * Exists because a hard pin cannot notice its own age. The starter template
+     * shipped `claude-sonnet-4-5` on an enabled member with nothing in the file
+     * able to flag it — and `check_council_pin_staleness` reads exactly this
+     * field. A member on a vendor sentinel (`codex-default`, or an alias like
+     * `sonnet` that the provider documents as "the latest model") needs no
+     * stamp: it cannot go stale, which is why the gate exempts it rather than
+     * demanding a date nobody would refresh.
+     */
+    readonly verified_at: string | null;
 }
 
 /**
@@ -635,6 +533,15 @@ export type QuorumMinPresent = number;
 
 export type { FallbackConfig } from './fallback_config.js';
 import { buildFallback, buildSecondModel, type FallbackConfig as _FallbackConfig } from './fallback_config.js';
+import {
+    _f,
+    _pyOct,
+    _pyRepr,
+    _pyReprFloat,
+    _pyReprStr,
+    _pyTypeName,
+    _sortedListRepr,
+} from './py_format.js';
 
 export interface CouncilConfig {
     readonly enabled: boolean;
@@ -1916,6 +1823,55 @@ function _build_member(
     // untouched here) OR as a mapping carrying `ttl`. '5m' is the
     // permanent default; see docs/contracts/ai-council-config.md
     // § Prompt cache TTL for the falsification condition on '1h'.
+    // A malformed date fails CLOSED. A stamp is a claim about when a human
+    // last looked; accepting `2026-13-45` or `soon` would make the staleness
+    // gate report on a string it cannot compare, which is worse than no stamp.
+    const verified_at_raw = _get(cfg, 'verified_at', null);
+    let verified_at: string | null = null;
+    if (verified_at_raw !== null && verified_at_raw !== undefined) {
+        // The stamp must be a QUOTED string, and the reason is a measured
+        // fail-open rather than a style preference.
+        //
+        // YAML 1.1 resolves an unquoted `2026-08-22` to a Date. Accepting that
+        // and normalising it back with `toISOString()` was the first
+        // implementation, and it LAUNDERED impossible dates: the loader silently
+        // rolls `2026-13-45` over to 2027-02-14, so the calendar check below saw
+        // a valid date and the malformed input passed. Verified against a real
+        // config, not reasoned about.
+        //
+        // A Date is therefore rejected with the fix in the message. That keeps
+        // the impossible-date case failing CLOSED, which is the only direction
+        // worth defending here: a stamp is a claim about attention, and a
+        // silently corrected claim is worse than a rejected one.
+        if (verified_at_raw instanceof Date) {
+            throw new CouncilConfigError(
+                `members.${name}.verified_at must be QUOTED — write ` +
+                    `verified_at: "YYYY-MM-DD". Unquoted, YAML parses it as a date and ` +
+                    `silently rolls impossible values over (2026-13-45 becomes 2027-02-14), ` +
+                    `which would let a malformed stamp through.`,
+            );
+        }
+        const coerced = verified_at_raw;
+        if (typeof coerced !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(coerced)) {
+            throw new CouncilConfigError(
+                `members.${name}.verified_at must be a 'YYYY-MM-DD' string when set ` +
+                    `(got ${_pyRepr(verified_at_raw)}).`,
+            );
+        }
+        const [y, m, d] = coerced.split('-').map((x) => Number(x));
+        const probe = new Date(Date.UTC(y as number, (m as number) - 1, d as number));
+        if (
+            probe.getUTCFullYear() !== y ||
+            probe.getUTCMonth() + 1 !== m ||
+            probe.getUTCDate() !== d
+        ) {
+            throw new CouncilConfigError(
+                `members.${name}.verified_at is not a real calendar date ` +
+                    `(got ${_pyRepr(verified_at_raw)}).`,
+            );
+        }
+        verified_at = coerced;
+    }
     const prompt_cache_raw = _get(cfg, 'prompt_cache', null);
     let prompt_cache_ttl: '5m' | '1h' = '5m';
     if (prompt_cache_raw !== null && prompt_cache_raw !== undefined && !_isBool(prompt_cache_raw)) {
@@ -1947,6 +1903,7 @@ function _build_member(
         participate_low_impact: participate_raw,
         tier,
         prompt_cache_ttl,
+        verified_at,
     };
 }
 

package/src/scripts/ai_council/fallback_config.ts

@@ -10,6 +10,8 @@
  * here; the rest is there rather than duplicated.
  */
 
+import type { ApiOnQuota } from './transport_resolver.js';
+
 /**
  * `fallback.*` — the mid-flight cli→api retry's one configurable knob.
  *
@@ -24,8 +26,13 @@ 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.
+     *
+     * Three values, not two. `'ask'` defers the answer out of configuration
+     * time and into the round that would cross the cliff: the seat is PARKED
+     * unless a run-scoped billing grant says a human already agreed for this
+     * run. See `transport_resolver.ts` § `ApiOnQuota` and `_lib/billing_grant`.
      */
-    readonly api_on_quota: boolean;
+    readonly api_on_quota: ApiOnQuota;
 }
 
 /**
@@ -67,12 +74,17 @@ export function buildFallback(raw: unknown, d: FallbackBuilderDeps): FallbackCon
     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 };
+    if (d.isBool(v)) return { api_on_quota: v };
+    // `'ask'` is the ONLY string this accepts, and the narrowness is the
+    // point: the paragraph above refuses `"yes"` because an operator writing
+    // it is trying to authorise spend, and widening to "any truthy-looking
+    // string" to let `ask` through would readmit exactly that. A third named
+    // value is not a lenient parse.
+    if (d.isStr(v) && v === 'ask') return { api_on_quota: 'ask' };
+    throw d.error(
+        `\`fallback.api_on_quota\`=${d.repr(v)} must be \`false\`, \`true\` or \`'ask'\` ` +
+            `(got ${d.typeName(v)}).`,
+    );
 }
 
 /**

package/src/scripts/ai_council/mid_flight_fallback.ts

@@ -19,19 +19,28 @@
 import type { ExternalAIClient, CouncilResponse } from './clients.js';
 import {
     classifyCliFailure,
+    effectiveApiOnQuota,
     isFallbackEligibleUnder,
+    type ApiOnQuota,
     type FallbackPolicy,
     type MidFlightFallback,
 } from './transport_resolver.js';
 
-/** One escalation's outcome, for the event sink. */
-export type FallbackOutcome = 'retried' | 'no_twin' | 'cost_budget';
+/**
+ * One escalation's outcome, for the event sink.
+ *
+ * `awaiting_grant` is the posture `'ask'` adds and it is neither of the two
+ * that existed: the seat was NOT switched to metered billing and it was NOT
+ * lost. It is held, and the round closes with a question instead of a silent
+ * charge or a silent absence.
+ */
+export type FallbackOutcome = 'retried' | 'no_twin' | 'cost_budget' | 'awaiting_grant';
 
 export interface FallbackEvent {
     readonly provider: string;
     readonly failure: string;
     readonly outcome: FallbackOutcome;
-    readonly api_on_quota: boolean;
+    readonly api_on_quota: ApiOnQuota;
 }
 
 export interface CliFallbackOptions {
@@ -42,7 +51,21 @@ export interface CliFallbackOptions {
      */
     readonly construct: (provider: string) => ExternalAIClient | null;
     /** `ai_council.fallback.api_on_quota` — see `FallbackPolicy.apiOnQuota`. */
-    readonly api_on_quota: boolean;
+    readonly api_on_quota: ApiOnQuota;
+    /**
+     * True when a run-scoped billing grant is in force for THIS run. Read only
+     * under `api_on_quota: 'ask'`; absence means park, never proceed.
+     */
+    readonly billing_grant?: boolean;
+    /**
+     * Providers parked under `'ask'`, appended during the round.
+     *
+     * It lives on the options object rather than in the CLI because the CLI
+     * has nothing to do with it: the factory that decides a seat is parked is
+     * the only thing that can populate it, and a caller threading an array
+     * down to that factory and back is plumbing with no reader in between.
+     */
+    readonly parked?: string[];
     /**
      * Called once per ESTABLISHING escalation, never per substituted call.
      *
@@ -60,6 +83,42 @@ export interface EstablishedTwin {
     readonly original_error: string;
 }
 
+/**
+ * A seat held back because the policy is `'ask'` and no grant is in force.
+ *
+ * The third state the boolean could not express. Before `'ask'` existed a
+ * quota-hit seat had exactly two futures — a twin (metered, silent) or `null`
+ * (lost for the round). Neither is answerable afterwards: by the time a human
+ * reads the output, the spend has happened or the seat is gone. A parked seat
+ * is still in the round's seat map, so the question the round closes with is
+ * about work that can still be done.
+ */
+export interface ParkedSeat {
+    readonly parked: true;
+    readonly provider: string;
+    readonly reason: string;
+    readonly original_error: string;
+}
+
+/** `establishTwin`'s three outcomes: a twin, a parked seat, or nothing. */
+export type EstablishOutcome = EstablishedTwin | ParkedSeat | null;
+
+/**
+ * Narrow an `EstablishOutcome` to the twin branch.
+ *
+ * Every caller must use this rather than a truthiness test: a `ParkedSeat` is
+ * an object, so `if (twin)` retries the parked marker as though it were a
+ * client — the one bug the park branch exists to make impossible.
+ */
+export function isEstablishedTwin(o: EstablishOutcome): o is EstablishedTwin {
+    return o !== null && !('parked' in o);
+}
+
+/** Narrow an `EstablishOutcome` to the parked branch. */
+export function isParkedSeat(o: EstablishOutcome): o is ParkedSeat {
+    return o !== null && 'parked' in o;
+}
+
 /**
  * Why the twin map exists alongside the ledger.
  *
@@ -99,10 +158,32 @@ export interface EstablishInput {
  * budget then refused. An ineligible class emits nothing at all: there was no
  * escalation to report.
  */
-export function establishTwin(input: EstablishInput): EstablishedTwin | null {
+export function establishTwin(input: EstablishInput): EstablishOutcome {
     const { member, error, fallback, ledger } = input;
     const failure = classifyCliFailure(error);
-    const policy: FallbackPolicy = { apiOnQuota: fallback.api_on_quota };
+    const policy: FallbackPolicy = {
+        apiOnQuota: fallback.api_on_quota,
+        billingGrant: fallback.billing_grant === true,
+    };
+    // The park branch runs BEFORE the eligibility test, and the order is the
+    // whole mechanism. `effectiveApiOnQuota` collapses an ungranted `'ask'`
+    // to `false`, so an eligibility-first reading would return `null` here —
+    // the seat lost, exactly as under `api_on_quota: false`, and the operator
+    // never asked. The ledger is deliberately NOT consulted: parking spends no
+    // fallback attempt, so the seat is still escalatable on the grant.
+    if (
+        fallback.api_on_quota === 'ask' &&
+        failure === 'quota_exhausted' &&
+        !effectiveApiOnQuota(policy)
+    ) {
+        fallback.on_event?.({
+            provider: member.name,
+            failure,
+            outcome: 'awaiting_grant',
+            api_on_quota: fallback.api_on_quota,
+        });
+        return { parked: true, provider: member.name, reason: failure, original_error: error };
+    }
     if (!isFallbackEligibleUnder(failure, policy)) return null;
     if (ledger.attempt(member.name, failure, policy) !== 'api') return null;
 
@@ -241,7 +322,7 @@ export function escalateUnmetered(
         fallback,
         ledger,
     });
-    if (twin === null) return null;
+    if (!isEstablishedTwin(twin)) return null;
     // NOTHING is emitted here, and the previous comment justifying an emit at
     // establishment is deleted rather than reworded because it stopped being
     // true. It read: "on this path the twin goes through the round's ORDINARY

package/src/scripts/ai_council/orchestrator.ts

@@ -75,7 +75,7 @@ import {
     emitOutcome,
     escalateUnmetered,
     refuseUnmeteredEscalation,
-    establishTwin,
+    establishTwin, isEstablishedTwin,
     isFailedCliCall,
     runGatedRetry,
     stampFallback,
@@ -764,7 +764,7 @@ function _run_round(
                 fallback,
                 ledger,
             });
-            if (twin !== null) {
+            if (isEstablishedTwin(twin)) {
                 const out = runGatedRetry(response, member, twin, fallback, {
                     gate: (client) =>
                         table === null ||

package/src/scripts/ai_council/py_format.ts

@@ -0,0 +1,124 @@
+/**
+ * Python-format helpers, extracted from `config.ts`.
+ *
+ * Every error string this package emits is byte-faithful to the Python original
+ * it replaced, which is why `repr()`, `type().__name__` and `oct()` are
+ * reimplemented here instead of being approximated with template literals.
+ *
+ * Pure and self-contained: these functions call only each other, which is what
+ * made the section safe to move out whole. Extracted because config.ts is
+ * hundreds of lines above the 1500-line source ceiling and a change adding to it
+ * has to pay for the lines somewhere.
+ */
+/** Python `repr()` for a string scalar (single-quoted, escaped). */
+export function _pyReprStr(s: string): string {
+    const hasSingle = s.includes("'");
+    const hasDouble = s.includes('"');
+    const quote = hasSingle && !hasDouble ? '"' : "'";
+    let body = s
+        .replace(/\\/g, '\\\\')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    if (quote === "'") {
+        body = body.replace(/'/g, "\\'");
+    } else {
+        body = body.replace(/"/g, '\\"');
+    }
+    return `${quote}${body}${quote}`;
+}
+
+/** Python `repr()` for a float value (shortest round-trip, `N.0` for ints). */
+export function _pyReprFloat(value: number): string {
+    if (Number.isInteger(value) && Number.isFinite(value)) {
+        return `${value}.0`;
+    }
+    if (value === Infinity) {
+        return 'inf';
+    }
+    if (value === -Infinity) {
+        return '-inf';
+    }
+    if (Number.isNaN(value)) {
+        return 'nan';
+    }
+    return String(value);
+}
+
+/**
+ * Python `repr()` for an arbitrary parsed value. Floats are tracked via
+ * `_FLOAT` so int-valued floats render `N.0`; bare numbers render as
+ * Python ints (no decimal). Mirrors `{value!r}` formatting.
+ */
+export function _pyRepr(value: unknown): string {
+    if (value instanceof _Float) {
+        return _pyReprFloat(value.value);
+    }
+    if (value === null || value === undefined) {
+        return 'None';
+    }
+    if (typeof value === 'boolean') {
+        return value ? 'True' : 'False';
+    }
+    if (typeof value === 'string') {
+        return _pyReprStr(value);
+    }
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => _pyRepr(v)).join(', ')}]`;
+    }
+    if (typeof value === 'object') {
+        const parts: string[] = [];
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            parts.push(`${_pyReprStr(k)}: ${_pyRepr(v)}`);
+        }
+        return `{${parts.join(', ')}}`;
+    }
+    return String(value);
+}
+
+/** Wrapper marking a number that should `repr()` as a Python float. */
+export class _Float {
+    constructor(readonly value: number) {}
+}
+
+/** Mark `n` so `_pyRepr` renders it with a Python float repr (`N.0`). */
+export function _f(n: number): _Float {
+    return new _Float(n);
+}
+
+/** Python `type(value).__name__`. */
+export function _pyTypeName(value: unknown): string {
+    if (value === null || value === undefined) {
+        return 'NoneType';
+    }
+    if (typeof value === 'boolean') {
+        return 'bool';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'int' : 'float';
+    }
+    if (typeof value === 'string') {
+        return 'str';
+    }
+    if (Array.isArray(value)) {
+        return 'list';
+    }
+    if (typeof value === 'object') {
+        return 'dict';
+    }
+    return typeof value;
+}
+
+/** Python `sorted(set_of_strings)` rendered as a list repr `['a', 'b']`. */
+export function _sortedListRepr(items: Iterable<string>): string {
+    const sorted = [...items].sort();
+    return `[${sorted.map((s) => _pyReprStr(s)).join(', ')}]`;
+}
+
+/** Python `oct(mode)` → `0o600`-shaped string. */
+export function _pyOct(mode: number): string {
+    return `0o${mode.toString(8)}`;
+}

package/src/scripts/ai_council/transport_resolver.ts

@@ -403,13 +403,76 @@ const FALLBACK_ELIGIBLE: ReadonlySet<CliFailureClass> = new Set([
  * `auto` may infer — the USD spend itself remains guarded by the ordinary
  * `cost_budget` gates the orchestrator runs on the retry.
  */
+/**
+ * The three postures of `ai_council.fallback.api_on_quota`.
+ *
+ * `false` and `true` mean what they always meant. `'ask'` is the third: the
+ * billing-class decision is deferred out of configuration time and into the
+ * round that would actually cross the cliff, where the remaining scope is
+ * known. Under `'ask'` the seat is eligible only when a run-scoped billing
+ * grant is present — a human said yes for THIS run — and is parked otherwise.
+ */
+export type ApiOnQuota = boolean | 'ask';
+
 export interface FallbackPolicy {
-    readonly apiOnQuota: boolean;
+    readonly apiOnQuota: ApiOnQuota;
+    /**
+     * True when a run-scoped billing grant is in force. Only consulted under
+     * `apiOnQuota: 'ask'`; absent is never read as granted, which is why this
+     * is optional rather than defaulted anywhere.
+     */
+    readonly billingGrant?: boolean;
 }
 
 /** The base policy: exactly the three-plus-one no-double-charge classes. */
 export const DEFAULT_FALLBACK_POLICY: FallbackPolicy = { apiOnQuota: false };
 
+/**
+ * Collapse the tri-state plus the grant into the boolean the eligibility rule
+ * needs. `'ask'` without a grant is `false` — never `true` by omission, which
+ * is the one direction that would turn a configured question into silent
+ * metered spend.
+ */
+export function effectiveApiOnQuota(policy: FallbackPolicy): boolean {
+    if (policy.apiOnQuota === 'ask') return policy.billingGrant === true;
+    return policy.apiOnQuota === true;
+}
+
+/**
+ * Parse a config value into the tri-state, or throw.
+ *
+ * Rejecting is the point. A parser that mapped an unknown value onto a truthy
+ * default would turn a configured `off` into metered spend — the exact failure
+ * the `'ask'` posture exists to prevent, introduced by the code that adds it.
+ * Accepts the Python-ish spellings the council config has always allowed on
+ * the boolean side, plus `ask` on the new one.
+ */
+export function apiOnQuotaView(raw: unknown): ApiOnQuota {
+    // Lenient by design, unlike `parseApiOnQuota`: this feeds a DISPLAY
+    // surface, where throwing on a malformed file would blank the wizard
+    // instead of showing the operator the setting they need to fix. Reading
+    // by value rather than by truthiness is the half that still matters —
+    // `=== true` alone renders `'ask'` as `false`, and the next save
+    // downgrades a configured question to a configured no.
+    return raw === 'ask' ? 'ask' : raw === true;
+}
+
+export function parseApiOnQuota(raw: unknown): ApiOnQuota {
+    if (typeof raw === 'boolean') return raw;
+    if (raw === undefined || raw === null) return false;
+    if (typeof raw === 'string') {
+        const s = raw.trim().toLowerCase();
+        if (s === 'ask') return 'ask';
+        if (s === 'true' || s === 'yes' || s === 'on' || s === '1') return true;
+        if (s === '' || s === 'false' || s === 'no' || s === 'off' || s === '0') {
+            return false;
+        }
+    }
+    throw new Error(
+        `ai_council.fallback.api_on_quota: expected false | true | 'ask', got ${JSON.stringify(raw)}`,
+    );
+}
+
 /** Normalise a raw client error / skip reason into a `CliFailureClass`. */
 export function classifyCliFailure(raw: string): CliFailureClass {
     const s = raw.trim().toLowerCase();
@@ -464,7 +527,7 @@ export function isFallbackEligibleUnder(
     policy: FallbackPolicy,
 ): boolean {
     if (FALLBACK_ELIGIBLE.has(failure)) return true;
-    return policy.apiOnQuota && failure === 'quota_exhausted';
+    return effectiveApiOnQuota(policy) && failure === 'quota_exhausted';
 }
 
 /**