@event4u/agent-config 14.8.0 → 14.10.0

package/src/scripts/_lib/base_tree.ts

@@ -0,0 +1,175 @@
+/**
+ * Materialise one subtree of a git ref into a scratch directory, so a gate can
+ * MEASURE the base side with the same function it measures HEAD with.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A ratchet needs a "before" number the change under review cannot rewrite. The
+ * cheapest way to get one is to commit it — and that is what
+ * `src/config/estate-count-budget.json` did until ADR-243. A committed number is
+ * also a file every branch edits, which made it the most-conflicted non-generated
+ * path in this repository: 7 of 7 `CONFLICTING` open PRs on 2026-08-21, and 39 of
+ * 43 non-merge commits in a 60-day window moving it.
+ *
+ * The number does not have to be stored. Where the metric is a function of the
+ * tree, the base ref's own tree IS the "before" side — it is committed, and the
+ * change under review cannot rewrite it either. What is missing is a way to run
+ * a filesystem parser over a ref without checking it out.
+ *
+ * WHY NOT `git archive`
+ * ---------------------
+ * Measured, not assumed: `git archive origin/main agents/roadmaps | tar -x`
+ * produces an EMPTY archive in this repository, because `.gitattributes` carries
+ * `/agents export-ignore` (line 15) and `git archive` honours it. That is correct
+ * for the npm tarball it was written for and fatal here, and it fails silently —
+ * an empty extraction reads as "the estate measured zero", which is the shape of
+ * a floor of 0 that passes everything.
+ *
+ * `git ls-tree` + `git cat-file --batch` reads the object store directly and
+ * ignores export-ignore entirely. Cost, measured on 703 files: 0.22 s, two
+ * spawns total.
+ *
+ * WHY NOT `git worktree add`
+ * --------------------------
+ * It checks out the whole tree — 9177 files here — for a subtree of 703, and it
+ * mutates `.git/worktrees`, so a crashed gate leaves administrative state behind.
+ *
+ * THE EMPTY CASE IS AN ERROR, NEVER A MEASUREMENT
+ * -----------------------------------------------
+ * `materialiseSubtree` returns the file count and callers MUST treat 0 as "the
+ * base side could not be established", never as a measurement. An absent subtree,
+ * a typo in the path, a ref that predates the directory and an export-ignore
+ * silently eating the content are indistinguishable from each other and all
+ * produce zero — and for a shrink-only gate, a floor of zero is a green light for
+ * unbounded growth. This is stated here because the caller cannot see which of
+ * those happened either, and the safe reading of all four is the same.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+/** Ceiling on the blob stream. The roadmap corpus is ~2 MB; this is headroom. */
+const BATCH_MAX_BUFFER = 256 * 1024 * 1024;
+
+export interface MaterialisedTree {
+    /** Absolute path to a directory that now holds `<subtree>/...` from `ref`. */
+    root: string;
+    /** How many blobs were written. `0` means the base side is UNAVAILABLE. */
+    files: number;
+    /** Set when the read failed outright; `files` is then 0. */
+    error: string | null;
+}
+
+/** One entry of `git ls-tree -r -z`: `<mode> SP <type> SP <sha> TAB <path>`. */
+interface TreeEntry {
+    sha: string;
+    rel: string;
+}
+
+/**
+ * Parse `git ls-tree -r -z` output.
+ *
+ * The `-z` form is used rather than `--format`, which needs git ≥ 2.36: this runs
+ * on contributor machines and on runners, and a gate that fails on an older git
+ * is a gate that gets turned off.
+ */
+function parseLsTree(stdout: string): TreeEntry[] {
+    const out: TreeEntry[] = [];
+    for (const record of stdout.split('\0')) {
+        if (record === '') continue;
+        const tab = record.indexOf('\t');
+        if (tab === -1) continue;
+        const meta = record.slice(0, tab).split(' ');
+        const sha = meta[2];
+        const type = meta[1];
+        const rel = record.slice(tab + 1);
+        // Blobs only. A submodule entry is a `commit` and has no content here;
+        // writing its sha as a file would be a silent corruption of the measured
+        // tree rather than a missing file the caller could notice.
+        if (type !== 'blob' || sha === undefined || sha === '' || rel === '') continue;
+        out.push({ sha, rel });
+    }
+    return out;
+}
+
+/**
+ * Walk a `git cat-file --batch` stream, invoking `sink` per object.
+ *
+ * Wire format per object: `<sha> SP <type> SP <size> LF`, then exactly `size`
+ * bytes, then one LF. Sizes are read from the header rather than inferred from
+ * the next header, so a blob containing a line that looks like a header cannot
+ * desynchronise the parse — the failure mode that makes a line-oriented reading
+ * of this stream wrong.
+ */
+function walkBatch(buf: Buffer, sink: (sha: string, body: Buffer) => void): void {
+    let pos = 0;
+    while (pos < buf.length) {
+        const nl = buf.indexOf('\n', pos);
+        if (nl === -1) return;
+        const header = buf.subarray(pos, nl).toString('utf-8');
+        const parts = header.split(' ');
+        if (parts.length < 3) return; // `<sha> missing` — a bad ref; stop cleanly.
+        const size = Number.parseInt(parts[2] ?? '', 10);
+        if (!Number.isFinite(size) || size < 0) return;
+        const start = nl + 1;
+        sink(parts[0] ?? '', buf.subarray(start, start + size));
+        pos = start + size + 1;
+    }
+}
+
+/**
+ * Write `<subtree>` as it exists at `ref` into a fresh temp directory.
+ *
+ * The returned `root` is the caller's to remove — callers hold it in a `finally`.
+ * `subtree` is a repo-relative POSIX path (`agents/roadmaps`), because that is
+ * what git pathspecs take; a `path.sep`-joined value works on POSIX and silently
+ * matches nothing on Windows, so callers pass the POSIX form explicitly.
+ */
+export function materialiseSubtree(repoRoot: string, ref: string, subtree: string): MaterialisedTree {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'base-tree-'));
+    const list = spawnSync('git', ['ls-tree', '-r', '-z', ref, '--', subtree], {
+        cwd: repoRoot,
+        encoding: 'utf-8',
+        maxBuffer: BATCH_MAX_BUFFER,
+    });
+    if (list.status !== 0) {
+        return { root, files: 0, error: `git ls-tree ${ref} -- ${subtree} failed: ${(list.stderr ?? '').trim()}` };
+    }
+    const entries = parseLsTree(list.stdout ?? '');
+    if (entries.length === 0) {
+        return { root, files: 0, error: `${subtree} holds no blobs at ${ref}` };
+    }
+
+    const batch = spawnSync('git', ['cat-file', '--batch'], {
+        cwd: repoRoot,
+        input: `${entries.map((e) => e.sha).join('\n')}\n`,
+        maxBuffer: BATCH_MAX_BUFFER,
+    });
+    if (batch.status !== 0 || batch.stdout === null) {
+        return { root, files: 0, error: `git cat-file --batch failed: ${String(batch.stderr ?? '').trim()}` };
+    }
+
+    // One sha may appear under several paths (identical file content), so the
+    // stream is keyed by sha and every path carrying that sha is written. Keying
+    // by position would break on exactly that case, and it is not hypothetical:
+    // roadmap stubs share boilerplate.
+    const bySha = new Map<string, Buffer>();
+    walkBatch(batch.stdout, (sha, body) => {
+        if (!bySha.has(sha)) bySha.set(sha, body);
+    });
+
+    let files = 0;
+    for (const entry of entries) {
+        const body = bySha.get(entry.sha);
+        if (body === undefined) continue;
+        const dest = path.join(root, ...entry.rel.split('/'));
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, body);
+        files += 1;
+    }
+    if (files !== entries.length) {
+        return { root, files: 0, error: `wrote ${String(files)} of ${String(entries.length)} blobs from ${ref}` };
+    }
+    return { root, files, error: null };
+}

package/src/scripts/_lib/billing_grant.ts

@@ -0,0 +1,165 @@
+/**
+ * billing_grant — the run-scoped answer to "plan quota is gone, may I spend?".
+ *
+ * The problem this closes is a billing-class switch nobody chose at the moment
+ * it happened. A council seat on a vendor CLI under a subscription login is
+ * unmetered; its api twin is metered USD. Until `api_on_quota: 'ask'` existed
+ * that switch was decided once, at configuration time, and then applied
+ * silently mid-round — see `transport_resolver.ts` § `FallbackPolicy`.
+ *
+ * A grant is the human's yes, and it is scoped to ONE run for two reasons.
+ *
+ * The first is that a run is the unit the question is answerable in. "May I
+ * spend money finishing this?" needs the remaining scope in view; a standing
+ * setting has no scope to show. The second is the failure a wall-clock TTL
+ * produces: the git-guard grant expired after 30 minutes, so a drain outliving
+ * its own grant re-asked mid-run — which is the interruption this whole
+ * mechanism exists to remove. So the TTL here is the RUN, and `revoke` is
+ * called from the path that already clears run-continuation state. A wall
+ * clock appears only as a backstop for a run that died without cleaning up.
+ *
+ * Transport is an env var (`AC_BILLING_GRANT`) plus a file under
+ * `agents/runtime/`. Both are needed and neither is redundant: the env var is
+ * what a spawned subagent can read without knowing the repo root, and the file
+ * is what makes the grant survive a subprocess boundary in the other
+ * direction and gives `revoke` something to delete. `hardenedSpawnEnv()`
+ * passes the `AC_` family through — verified, and pinned by a test in
+ * `tests/scripts/_lib/spawn_env.test.ts`, because a future deny-family entry
+ * would otherwise break the chain silently.
+ *
+ * PII-exclusion-by-construction: a grant record holds a run id, an ISO
+ * timestamp, and nothing else. There is no field capable of carrying a prompt,
+ * a path, or a credential, so there is no scrubbing pass here that could fail.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Env var the main session sets and every spawned worker reads. */
+export const BILLING_GRANT_ENV = 'AC_BILLING_GRANT';
+
+/** Directory, relative to the repo root, holding one file per live grant. */
+export const BILLING_GRANT_DIR_REL = path.join('agents', 'runtime', 'billing-grants');
+
+/**
+ * Backstop only. A run that exits through its normal path calls `revoke`; this
+ * bounds the damage of one that does not, and is deliberately far longer than
+ * any run so it can never be the thing that ends a live grant.
+ */
+export const BILLING_GRANT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface BillingGrant {
+    readonly run_id: string;
+    readonly issued_at: string;
+}
+
+/** Filesystem-safe filename for a run id. Mirrors `run_checkpoint.checkpointFile`. */
+export function grantFile(repoRoot: string, runId: string): string {
+    return path.join(
+        repoRoot,
+        BILLING_GRANT_DIR_REL,
+        `${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.json`,
+    );
+}
+
+/**
+ * Record the human's yes for `runId` and return the env pair to hand to
+ * subagents. Idempotent: re-issuing keeps the original `issued_at`, so a
+ * second yes inside one run cannot extend the backstop window.
+ */
+export function issueBillingGrant(
+    repoRoot: string,
+    runId: string,
+    now: () => Date = () => new Date(),
+): BillingGrant {
+    const file = grantFile(repoRoot, runId);
+    const existing = _read(file);
+    if (existing !== null && existing.run_id === runId) return existing;
+    const grant: BillingGrant = { run_id: runId, issued_at: now().toISOString() };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(grant, null, 2)}\n`, 'utf8');
+    return grant;
+}
+
+/**
+ * Is a grant in force for `runId`?
+ *
+ * Both halves must agree, and the AND is the security property rather than
+ * belt-and-braces: an env var alone is settable by anything in the process
+ * tree, and a file alone would let a grant from a previous run authorise this
+ * one. Requiring the env var to NAME the run whose file exists is what makes
+ * a different run's grant unusable.
+ */
+export function isBillingGrantActive(
+    repoRoot: string,
+    runId: string,
+    env: NodeJS.ProcessEnv = process.env,
+    now: () => Date = () => new Date(),
+): boolean {
+    if ((env[BILLING_GRANT_ENV] ?? '').trim() !== runId) return false;
+    const grant = _read(grantFile(repoRoot, runId));
+    if (grant === null || grant.run_id !== runId) return false;
+    const age = now().getTime() - Date.parse(grant.issued_at);
+    return Number.isFinite(age) && age >= 0 && age <= BILLING_GRANT_MAX_AGE_MS;
+}
+
+/**
+ * Ambient check for a caller that does not carry a run id — the council CLI
+ * reading config, for instance. The env var names the run, so the file it
+ * names is the one that must exist; there is no "any grant will do" branch.
+ */
+export function hasBillingGrant(
+    repoRoot: string,
+    env: NodeJS.ProcessEnv = process.env,
+    now: () => Date = () => new Date(),
+): boolean {
+    const runId = (env[BILLING_GRANT_ENV] ?? '').trim();
+    if (runId === '') return false;
+    return isBillingGrantActive(repoRoot, runId, env, now);
+}
+
+/**
+ * Remove the grant for `runId`. Safe to call when none exists.
+ *
+ * Called from `run_continuation_hook.clearRunState` — the one place a run is
+ * declared over, and therefore the grant's real TTL. `clearRunState` is
+ * exported for that reason: reaching it through the concern chain would mean
+ * standing up the whole dispatch harness to assert one unlink.
+ */
+export function revokeBillingGrant(repoRoot: string, runId: string): void {
+    try {
+        fs.unlinkSync(grantFile(repoRoot, runId));
+    } catch {
+        // Already gone is the success case, not an error worth surfacing.
+    }
+}
+
+function _read(file: string): BillingGrant | null {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as unknown;
+        if (raw === null || typeof raw !== 'object') return null;
+        const o = raw as Record<string, unknown>;
+        if (typeof o.run_id !== 'string' || typeof o.issued_at !== 'string') return null;
+        return { run_id: o.run_id, issued_at: o.issued_at };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The id of the run a grant would be scoped to.
+ *
+ * Resolution order, first non-empty wins: `AC_BILLING_GRANT` (a grant already
+ * in force names its own run), then `AC_RUN_ID` (what an orchestrating session
+ * sets), then the host's session id. Returns `null` when none resolves — and
+ * `null` is rendered as a literal placeholder rather than a fabricated id,
+ * because a grant command carrying an invented run id would be a command that
+ * silently authorises nothing.
+ */
+export function currentRunId(env: NodeJS.ProcessEnv = process.env): string | null {
+    for (const key of [BILLING_GRANT_ENV, 'AC_RUN_ID', 'CLAUDE_CODE_SESSION_ID']) {
+        const v = (env[key] ?? '').trim();
+        if (v !== '') return v;
+    }
+    return null;
+}

package/src/scripts/_lib/billing_grant_cli.ts

@@ -0,0 +1,123 @@
+/**
+ * The `council:{grant-billing,revoke-billing}` verbs, and the round's closing
+ * Human Gate line.
+ *
+ * Lives here rather than in `council_cli.ts` for the reason that file's other
+ * extractions give: it is ~2,500 lines over the source ceiling and the
+ * documented remedy is extraction, not a raised baseline
+ * (`gate-violation-baselines.json` § check_source_size_budget).
+ *
+ * IO is injected rather than imported so this module stays testable without a
+ * process: `council_cli.ts` owns the repo root and the stdout/stderr pair.
+ */
+
+import {
+    BILLING_GRANT_ENV,
+    currentRunId,
+    hasBillingGrant,
+    issueBillingGrant,
+    revokeBillingGrant,
+} from './billing_grant.js';
+import { renderBillingGateLines } from './council_fallback_posture.js';
+import { writeQuotaParked } from './quota_parked.js';
+
+export interface BillingCliDeps {
+    readonly repoRoot: string;
+    readonly stdout: (s: string) => void;
+    readonly stderr: (s: string) => void;
+}
+
+/** The verbs this module owns, spread into `council_cli`'s subcommand list. */
+export const BILLING_SUBCOMMANDS = ['grant-billing', 'revoke-billing'] as const;
+
+/**
+ * The arg spec for a billing verb, or `null` when `cmd` is not one.
+ *
+ * Consulted from `council_cli`'s `default:` arm rather than added as two more
+ * `case` labels there: the verb list already lives in this module, and a
+ * second copy of it in a switch is a copy that can drift.
+ */
+export function billingArgSpec(
+    cmd: string,
+): { positionals: string[]; opts: never[]; requiredOpts: never[] } | null {
+    return (BILLING_SUBCOMMANDS as readonly string[]).includes(cmd)
+        ? { positionals: ['run_id'], opts: [], requiredOpts: [] }
+        : null;
+}
+
+/**
+ * Dispatch a billing verb, or return `null` when `cmd` is not one.
+ *
+ * A `null` return rather than a thrown or a boolean out-param: the caller's
+ * dispatch chain is a run of `if (cmd === x) return f()`, and this has to slot
+ * into it as two lines without teaching the caller which verbs exist.
+ */
+export function handleBillingCommand(
+    cmd: string,
+    runId: unknown,
+    d: BillingCliDeps,
+): number | null {
+    if (cmd === 'grant-billing') return grantBilling(String(runId ?? ''), d);
+    if (cmd === 'revoke-billing') return revokeBilling(String(runId ?? ''), d);
+    return null;
+}
+
+/**
+ * Record the human's yes for one run.
+ *
+ * Writes the grant file and then prints the export line, because the file
+ * alone is not the grant: a grant is in force only when `AC_BILLING_GRANT`
+ * NAMES the run whose file exists (see `isBillingGrantActive`), and that AND
+ * is what stops a previous run's grant from authorising this one. Printing the
+ * export rather than setting it is not a limitation being apologised for — a
+ * process cannot set its parent's environment, and a command claiming to would
+ * be lying.
+ */
+export function grantBilling(runId: string, d: BillingCliDeps): number {
+    if (runId.trim() === '') {
+        d.stderr('❌  council:grant-billing: a run id is required.\n');
+        return 2;
+    }
+    const g = issueBillingGrant(d.repoRoot, runId.trim());
+    d.stdout(`✅  billing grant recorded for run ${g.run_id} (issued ${g.issued_at})\n`);
+    d.stdout(`    export ${BILLING_GRANT_ENV}=${g.run_id}\n`);
+    const live = hasBillingGrant(d.repoRoot) ? 'yes' : 'not until the export above is set';
+    d.stdout(`    in force: ${live}\n`);
+    return 0;
+}
+
+/**
+ * End the grant. Exit 0 on an absent one: "there is no grant for this run" is
+ * the state the caller asked for, and failing on it would make the run-end
+ * cleanup path noisy on exactly the runs that never needed a grant.
+ */
+export function revokeBilling(runId: string, d: BillingCliDeps): number {
+    if (runId.trim() === '') {
+        d.stderr('❌  council:revoke-billing: a run id is required.\n');
+        return 2;
+    }
+    revokeBillingGrant(d.repoRoot, runId.trim());
+    d.stdout(`✅  billing grant revoked for run ${runId.trim()}\n`);
+    return 0;
+}
+
+/**
+ * Print the round's closing question when `api_on_quota: 'ask'` parked seats.
+ * Silent when nothing parked, so the caller needs no branch.
+ */
+export function printBillingGate(parked: readonly string[], d: BillingCliDeps): void {
+    const runId = currentRunId();
+    // Record before rendering. A parked round is the one moment this repository
+    // KNOWS plan quota is exhausted without needing a host signal, and the
+    // printed line reaches whoever is watching the terminal — which for an
+    // autonomous drain is nobody. The marker is what survives to the next
+    // `run:supervise` report. Skipped when no run id resolves: a marker with a
+    // fabricated key is worse than none, because nothing would ever match it.
+    if (parked.length > 0 && runId !== null) writeQuotaParked(d.repoRoot, runId, parked);
+    for (const line of renderBillingGateLines(parked, {
+        runId: runId ?? '<run-id>',
+        estimatedUsd: null,
+    })) {
+        d.stdout(`${line}\n`);
+    }
+}

package/src/scripts/_lib/council_fallback_posture.ts

@@ -13,6 +13,8 @@
  * `council:status` is the one command that must stay free of side effects.
  */
 
+import type { ApiOnQuota } from '../ai_council/transport_resolver.js';
+
 export type FallbackPosture = 'api' | 'none' | 'n/a';
 
 export interface PostureInput {
@@ -59,7 +61,7 @@ export function fallbackPostureFor(input: PostureInput): FallbackPosture {
  */
 export function renderPostureLines(
     postures: ReadonlyArray<readonly [string, FallbackPosture]>,
-    apiOnQuota: boolean,
+    apiOnQuota: ApiOnQuota,
 ): string[] {
     const live = postures.filter(([, p]) => p !== 'n/a');
     if (live.length === 0) return [];
@@ -72,10 +74,55 @@ export function renderPostureLines(
     );
     // Separate from the per-seat lines: not a per-seat property but the one
     // billing-class decision, governing every seat at once.
-    lines.push(
-        `  fallback quota   api_on_quota: ${apiOnQuota ? 'on' : 'off'}` +
-            ` — an exhausted cli quota ${apiOnQuota ? 'MAY' : 'may not'}` +
-            ' retry on the metered rung',
-    );
+    // Three postures, rendered by name rather than by truthiness. `'ask'` is
+    // truthy, so an `apiOnQuota ? 'on' : 'off'` reading would print `on` for
+    // it — telling the operator that quota fall-through happens silently when
+    // the whole point of the value is that it does not.
+    const word = apiOnQuota === 'ask' ? 'ask' : apiOnQuota ? 'on' : 'off';
+    const consequence =
+        apiOnQuota === 'ask'
+            ? ' — an exhausted cli quota PARKS the seat and the round closes with a question,' +
+              ' unless a run-scoped billing grant is already in force'
+            : apiOnQuota
+              ? ' — an exhausted cli quota MAY retry on the metered rung'
+              : ' — an exhausted cli quota may not retry on the metered rung';
+    lines.push(`  fallback quota   api_on_quota: ${word}${consequence}`);
     return lines;
 }
+
+/**
+ * The Human Gate a round closes with when `api_on_quota: 'ask'` parked seats.
+ *
+ * A correction to this roadmap step, recorded rather than quietly absorbed:
+ * the step said to render this "through the existing `renderPostureLines`
+ * path". That path is `council:status`, which runs before any round and can
+ * therefore never know which seats a round parked. So this is a sibling in the
+ * same module rather than a branch inside that function — same place, same
+ * vocabulary, different moment.
+ *
+ * Returns `[]` when nothing parked, so a caller may render unconditionally
+ * without a heading over an empty list.
+ */
+export function renderBillingGateLines(
+    parked: readonly string[],
+    opts: { readonly runId: string; readonly estimatedUsd: number | null },
+): string[] {
+    if (parked.length === 0) return [];
+    const seats = [...new Set(parked)].sort();
+    const cost =
+        opts.estimatedUsd === null
+            ? 'unknown — no priced estimate for the retry'
+            : `~$${opts.estimatedUsd.toFixed(2)}`;
+    return [
+        '',
+        'HUMAN GATE — plan quota exhausted, metered spend not authorised',
+        `  parked seats     ${seats.join(', ')}`,
+        `  retry cost       ${cost}`,
+        // The command is printed rather than described because the whole
+        // mechanism fails if answering it takes a lookup: an operator who has
+        // to go find the syntax is an operator who says yes tomorrow, on a run
+        // that has already ended.
+        `  to authorise     agent-config council:grant-billing ${opts.runId}`,
+        '  to decline       do nothing — the grant is never implied by silence',
+    ];
+}

package/src/scripts/_lib/council_fallback_wiring.ts

@@ -13,13 +13,18 @@
  */
 
 import type { CliFallbackOptions, FallbackEvent } from '../ai_council/mid_flight_fallback.js';
+import type { ApiOnQuota } from '../ai_council/transport_resolver.js';
+import { parseApiOnQuota } from '../ai_council/transport_resolver.js';
+import { hasBillingGrant } from './billing_grant.js';
 import { CouncilConfigError } from '../ai_council/config.js';
 
 type Dict = Record<string, unknown>;
 
 /** Anything the twin factory needs that `council_cli.ts` owns. */
 export interface FallbackWiringDeps {
-    readonly apiOnQuota: boolean;
+    readonly apiOnQuota: ApiOnQuota;
+    /** Run-scoped billing grant in force. Read only under `'ask'`. */
+    readonly billingGrant?: boolean;
     /** Does this provider have an api constructor at all? */
     readonly hasApiRung: (provider: string) => boolean;
     /** This provider's `members.<name>` block, or `{}`. */
@@ -38,6 +43,7 @@ export interface FallbackWiringDeps {
     ) => unknown;
     /** The events-log appender. */
     readonly emit: (record: Dict) => unknown;
+
 }
 
 /**
@@ -77,8 +83,15 @@ function isRefusal(exc: unknown): boolean {
 }
 
 export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptions {
+    // Owned here, not passed in. `establishTwin` emits `awaiting_grant` and
+    // this is the nearest thing to it that outlives one call, so a caller
+    // wanting the closing question reads `options.parked` instead of
+    // threading a collector through the factory.
+    const parked: string[] = [];
     return {
         api_on_quota: deps.apiOnQuota,
+        billing_grant: deps.billingGrant === true,
+        parked,
         // The orchestrator is a pure library and holds no sink; this is it.
         // One line per establishing escalation, so attendance analysis can
         // tell a seat SAVED by the fallback from one that was natively api.
@@ -93,6 +106,7 @@ export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptio
             // during a fallback kills the whole round, and the mechanism whose
             // entire purpose is to SAVE a seat becomes the thing that loses
             // every seat. Losing the log line is the strictly smaller failure.
+            if (e.outcome === 'awaiting_grant') parked.push(e.provider);
             try {
                 deps.emit({
                     action: 'transport_fallback',
@@ -124,3 +138,49 @@ export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptio
         },
     };
 }
+
+/** Everything `wireCouncilFallback` needs that `council_cli.ts` owns. */
+export interface CallSiteDeps {
+    readonly repoRoot: string;
+    readonly isDict: (v: unknown) => v is Dict;
+    readonly membersCfg: Dict;
+    readonly overrides: Dict;
+    readonly hasApiRung: (provider: string) => boolean;
+    readonly constructApi: FallbackWiringDeps['constructApi'];
+    readonly emit: (record: Dict) => unknown;
+}
+
+/**
+ * Build the fallback factory from the raw `ai_council` block and hand it back
+ * through the out-param `build_members` threads.
+ *
+ * Extracted from `council_cli.ts` when the billing-grant read joined the two
+ * config reads already here: that file is ~2,500 lines over the source ceiling
+ * and the documented remedy is extraction rather than a raised baseline
+ * (`gate-violation-baselines.json` § check_source_size_budget). Keeping the
+ * derivation next to the factory it feeds is the better shape anyway — the
+ * caller had to know that an absent `fallback` block means `false` and that
+ * the grant is read per-run, neither of which is the caller's business.
+ */
+export function wireCouncilFallback(
+    out: { options: CliFallbackOptions | null } | null,
+    ai: Dict,
+    d: CallSiteDeps,
+): void {
+    // The null check lives here, not at the call site: `fallback_out` is an
+    // optional out-param and "the caller passed no ref" is this function's
+    // business, not a branch every caller has to remember.
+    if (out === null) return;
+    // Absent/malformed block means `false`, never a throw. Why quota
+    // fall-through is opt-in: `FallbackPolicy.apiOnQuota`.
+    const cfg = d.isDict(ai['fallback']) ? ai['fallback'] : {};
+    out.options = buildFallbackOptions({
+        apiOnQuota: parseApiOnQuota(cfg['api_on_quota']),
+        billingGrant: hasBillingGrant(d.repoRoot),
+        hasApiRung: d.hasApiRung,
+        memberConfig: (p) => ((d.membersCfg[p] as Dict) || {}) as Dict,
+        modelOverride: (p) => (d.overrides[p] as string | undefined) ?? null,
+        constructApi: d.constructApi,
+        emit: d.emit,
+    });
+}