@event4u/agent-config 14.8.0 → 14.9.0

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

package/src/scripts/_lib/host_capability.ts

@@ -120,11 +120,65 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  * host identity a hook/dispatch envelope carries).
  *
  * Each row is partial: an omitted field stays at the `SAFE_DEFAULT` `false`
- * when the row is applied. Claude Code is the one host this roadmap's
- * transcript evidence measured spawning and running subagents concurrently
- * (`Agent` tool dispatch, parallel tool-use blocks); polling and a separate
- * quota pool were never observed, so they stay `false` — add a field only
- * once it is itself observed, never by inference.
+ * when the row is applied — and an ABSENT field is the record for "never
+ * looked", which is a different state from a field written as `false`
+ * deliberately. Add a field only once it is itself observed, never by
+ * inference.
+ *
+ * ## Rows are written under the observation protocol
+ *
+ * `contexts/execution/host-capability-manifest.md` § Observation protocol states
+ * the per-field criterion and the four-part citation (host · host version ·
+ * transcript or artefact reference · date). A row without all four is not
+ * admissible, and no row may be filled from a host's documentation.
+ *
+ * ## REACHABILITY, 2026-08-22 — one of eight, and the other seven are recorded
+ *
+ * `hook_manifest.yaml` declares eight platform keys. Reachable means a real
+ * session can be started on the host, not that it is installable in principle.
+ *
+ *   - `claude`   — REACHABLE. Row below, re-cited under the protocol.
+ *   - `augment`  — not reachable from this session: a different editor host, no
+ *                  session available to the running agent.
+ *   - `cowork`   — not reachable from this session, same reason.
+ *   - `cursor`   — not reachable from this session, same reason.
+ *   - `cline`    — not reachable from this session, same reason.
+ *   - `windsurf` — not reachable from this session, same reason.
+ *   - `gemini`   — not reachable from this session, same reason.
+ *   - `copilot`  — not reachable from this session, same reason; additionally
+ *                  `fallback_only` in the manifest.
+ *
+ * The seven have **no row**, so every field resolves to the safe default and
+ * `describeHostCapabilities` reports its source as `default`. That is the
+ * "never looked" state, and it is the honest one — a recorded silence rather
+ * than a table with gaps that reads as a table of negatives.
+ *
+ * ## The `claude` row, RE-CITED rather than grandfathered
+ *
+ * The row predated the protocol. Both its fields are now carried on transcript
+ * evidence, so it is brought up to the new shape rather than marked
+ * grandfathered — which was the other permitted disposition and would have left
+ * it looking like it passed a protocol it never ran.
+ *
+ * `subagent_spawn: true` — OBSERVED. claude (Claude Code, Opus 5 1M session,
+ *   2026-08-22). `agents/runtime/state/subagent-ledger/2026-08.jsonl`: **445**
+ *   `subagent_start` records, and **420** stops carrying a measured
+ *   `duration_ms` — i.e. 420 child legs whose start and stop pair, which is the
+ *   criterion (a measurable child duration, not an inferred one).
+ *
+ * `parallel_spawn: true` — OBSERVED. Same host, session and artefact.
+ *   **6,168** of 6,388 stop records carry `concurrent_open >= 2`, with a
+ *   maximum of **30** concurrently open children. Overlapping intervals at one
+ *   instant, which is the criterion — not two children in sequence.
+ *
+ * `status_polling`, `separate_quota_pool`, `worker_respawn` — **absent from the
+ *   row, and that is deliberate.** The ledger does not instrument any of the
+ *   three, so this is "never looked", NOT "observed absent". They stay at the
+ *   safe default and report `default` provenance. Writing any of them as an
+ *   explicit `false` would claim a measurement nobody took.
+ *
+ * `agent_teams` — out of scope for a row by construction; see its own field
+ *   doc comment and the protocol section.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
     claude: { subagent_spawn: true, parallel_spawn: true },

package/src/scripts/_lib/quota_parked.ts

@@ -0,0 +1,133 @@
+/**
+ * quota_parked — the marker that says a run stopped because plan quota ran out,
+ * rather than because it crashed.
+ *
+ * `run_supervise` can already tell a dead session from a live one, and a
+ * finished run from an unfinished one. What it cannot tell is WHY a run
+ * stopped, and for one cause that distinction decides the whole response: a run
+ * held back by an exhausted plan quota is not broken, it is early. Reported as
+ * `relaunchable` with "the session is gone" it reads as a crash, and the one
+ * fact an operator needs — that waiting is a strategy here and is not a
+ * strategy for a crash — is the fact that gets lost.
+ *
+ * **The trigger is ours, and that is the point.** Detecting the billing cliff
+ * inside Claude Code needs a host signal nobody has shown exists
+ * (`agents/roadmaps/later/road-to-billing-cliff-detection.md`). But the council
+ * establishes the same fact under its own roof: when `api_on_quota: 'ask'`
+ * parks a seat, plan quota for that provider is exhausted, measured by us, with
+ * no host surface involved. This marker is written from there.
+ *
+ * PII-exclusion-by-construction, the same shape as `billing_grant`: a record
+ * holds a run id, provider names, and an ISO stamp. There is no field capable
+ * of carrying a prompt, a path, or an error body, so there is no scrubbing pass
+ * here that could fail.
+ *
+ * **It records, it does not act.** Nothing here sleeps, probes, or relaunches.
+ * Unattended relaunch is a published refusal
+ * (road-to-long-horizon-execution 4.0, AI council 2026-08-19) whose reopen
+ * condition has since fired — see
+ * `agents/evidence/billing-cliff/spawn-reopen-condition.md` — and a fired
+ * condition reopens the question in the venue that closed it, never the
+ * capability by itself.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Directory, relative to the repo root, holding one marker per parked run. */
+export const QUOTA_PARKED_DIR_REL = path.join('agents', 'runtime', 'state', 'quota-parked');
+
+export interface QuotaParkedMarker {
+    readonly run_id: string;
+    /** Providers whose plan quota was exhausted, sorted and deduplicated. */
+    readonly providers: string[];
+    readonly parked_at: string;
+}
+
+/** Filesystem-safe path for a run's marker. Mirrors `billing_grant.grantFile`. */
+export function markerFile(repoRoot: string, runId: string): string {
+    return path.join(
+        repoRoot,
+        QUOTA_PARKED_DIR_REL,
+        `${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.json`,
+    );
+}
+
+/**
+ * Record that `runId` is held back by exhausted plan quota on `providers`.
+ *
+ * Idempotent on the timestamp: a second park inside one run keeps the original
+ * `parked_at` and merges the provider set, so "when did this run first hit the
+ * cliff" survives a round that parks twice.
+ */
+export function writeQuotaParked(
+    repoRoot: string,
+    runId: string,
+    providers: readonly string[],
+    now: () => Date = () => new Date(),
+): QuotaParkedMarker {
+    const file = markerFile(repoRoot, runId);
+    const existing = readMarker(file);
+    const merged = [...new Set([...(existing?.providers ?? []), ...providers])].sort();
+    const marker: QuotaParkedMarker = {
+        run_id: runId,
+        providers: merged,
+        parked_at: existing?.parked_at ?? now().toISOString(),
+    };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+    return marker;
+}
+
+/** Remove a run's marker. Safe to call when none exists. */
+export function clearQuotaParked(repoRoot: string, runId: string): void {
+    try {
+        fs.unlinkSync(markerFile(repoRoot, runId));
+    } catch {
+        // Already gone is the state the caller asked for.
+    }
+}
+
+/**
+ * The marker for a session, or `null`.
+ *
+ * Looks up by run id first, then scans. The scan is not redundant: the run id
+ * the council writes comes from `currentRunId`, whose chain is
+ * `AC_BILLING_GRANT` → `AC_RUN_ID` → `CLAUDE_CODE_SESSION_ID`, while the
+ * register's `session_id` comes from `AGENT_CONFIG_SESSION_ID` →
+ * `CLAUDE_CODE_SESSION_ID`. The two coincide in an ordinary Claude Code session
+ * and diverge the moment an orchestrator sets `AC_RUN_ID` — so a direct hit is
+ * the common case and the scan is what stops the uncommon one from silently
+ * reporting a parked run as a crashed one. The directory holds one small file
+ * per parked run, so the scan is cheap by construction.
+ */
+export function findQuotaParked(repoRoot: string, sessionId: string): QuotaParkedMarker | null {
+    const direct = readMarker(markerFile(repoRoot, sessionId));
+    if (direct !== null) return direct;
+    let names: string[];
+    try {
+        names = fs.readdirSync(path.join(repoRoot, QUOTA_PARKED_DIR_REL));
+    } catch {
+        return null;
+    }
+    for (const name of names) {
+        if (!name.endsWith('.json')) continue;
+        const m = readMarker(path.join(repoRoot, QUOTA_PARKED_DIR_REL, name));
+        if (m !== null && m.run_id === sessionId) return m;
+    }
+    return null;
+}
+
+function readMarker(file: string): QuotaParkedMarker | null {
+    try {
+        const raw: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (raw === null || typeof raw !== 'object') return null;
+        const o = raw as Record<string, unknown>;
+        if (typeof o['run_id'] !== 'string' || typeof o['parked_at'] !== 'string') return null;
+        if (!Array.isArray(o['providers'])) return null;
+        const providers = o['providers'].filter((p): p is string => typeof p === 'string');
+        return { run_id: o['run_id'], providers, parked_at: o['parked_at'] };
+    } catch {
+        return null;
+    }
+}