@event4u/agent-config 12.1.0 → 14.0.0

package/src/scripts/ai_council/clients.ts

@@ -78,6 +78,8 @@ export function _resetModelCeilingMemo(): void {
     _modelCeilingMemo.clear();
 }
 import * as user_global_paths from '../_lib/user_global_paths.js';
+import { jsonDumpsIndent2 as _jsonDumpsIndent2 } from './_py_json.js';
+import * as budget from './cli_call_budget.js';
 import { appendEvent } from './events_log.js';
 
 export const ANTHROPIC_KEY_FILENAME = 'anthropic.key';
@@ -453,6 +455,12 @@ interface CliClientOptions {
     max_calls_per_day?: number | null | undefined;
     warn_at?: number | undefined;
     cli_calls_path?: string | null | undefined;
+    /**
+     * Who is booking these calls — a `CLI_CONSUMER_*` constant, declared by the
+     * construction site because the client cannot know its caller. Omitted →
+     * `CLI_CONSUMER_UNKNOWN`, which is a finding rather than a default.
+     */
+    consumer?: string | undefined;
 }
 
 /**
@@ -987,6 +995,17 @@ export class PerplexityClient extends _OpenAICompatibleClient {
 
 export const CLI_CALLS_FILENAME = 'cli-calls.json';
 
+// Durability, attribution and cap resolution live in `cli_call_budget.ts` — see
+// its header for why the dependency runs one way only.
+export {
+    CLI_CALLS_ATTRIBUTION_SUFFIX,
+    CLI_CONSUMER_COUNCIL,
+    CLI_CONSUMER_TEAM,
+    CLI_CONSUMER_UNKNOWN,
+    QUOTA_SOURCE_LOCAL_BUDGET,
+    QUOTA_SOURCE_PROVIDER,
+} from './cli_call_budget.js';
+
 // Default subprocess timeout (seconds) for a single CLI call. Long enough for
 // the largest frontier models to think; short enough to surface a hung
 // subprocess without freezing the council run.
@@ -1056,18 +1075,39 @@ export function load_cli_call_counts(p: string | null = null): Record<string, nu
     return out;
 }
 
-/** Increment today's call count for `provider`. Returns new total. */
-export function record_cli_call(provider: string, p: string | null = null): number {
+/**
+ * Return today's `provider → consumer → count` attribution. Fail-soft: an
+ * absent, stale, or malformed sidecar reads as `{}` and never gates a call.
+ */
+export function load_cli_call_attribution(
+    p: string | null = null,
+): Record<string, Record<string, number>> {
     const target = p !== null ? p : _cliCallsStatePath();
-    const counts = load_cli_call_counts(target);
-    counts[provider] = (counts[provider] ?? 0) + 1;
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(
-        target,
-        _jsonDumpsIndent2({ date: _today_utc_iso(), counts }),
-        { encoding: 'utf-8' },
-    );
-    return counts[provider];
+    return budget.readAttribution(target, _today_utc_iso());
+}
+
+/**
+ * Increment today's call count for `provider`. Returns the new total.
+ *
+ * `consumer` names who booked it and lands in the sidecar, never in the counter
+ * the gate reads. It defaults to `CLI_CONSUMER_UNKNOWN` so an undeclared call
+ * path is visible as a finding rather than attributed to whoever happens to be
+ * first in the enumeration.
+ */
+export function record_cli_call(
+    provider: string,
+    p: string | null = null,
+    consumer: string = budget.CLI_CONSUMER_UNKNOWN,
+): number {
+    const target = p !== null ? p : _cliCallsStatePath();
+    const today = _today_utc_iso();
+    return budget.withStateLock(target, () => {
+        const counts = load_cli_call_counts(target);
+        counts[provider] = (counts[provider] ?? 0) + 1;
+        budget.writeStateAtomically(target, _jsonDumpsIndent2({ date: today, counts }));
+        budget.recordAttribution(target, provider, consumer, today, _jsonDumpsIndent2);
+        return counts[provider] as number;
+    });
 }
 
 /**
@@ -1082,57 +1122,29 @@ export function reset_cli_call_counts(
     p: string | null = null,
 ): Record<string, number> {
     const target = p !== null ? p : _cliCallsStatePath();
-    let counts = load_cli_call_counts(target);
-    if (provider === null) {
-        counts = {};
-    } else {
-        delete counts[provider];
-    }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(
-        target,
-        _jsonDumpsIndent2({ date: _today_utc_iso(), counts }),
-        { encoding: 'utf-8' },
-    );
-    return counts;
+    const today = _today_utc_iso();
+    return budget.withStateLock(target, () => {
+        let counts = load_cli_call_counts(target);
+        if (provider === null) {
+            counts = {};
+        } else {
+            delete counts[provider];
+        }
+        budget.writeStateAtomically(target, _jsonDumpsIndent2({ date: today, counts }));
+        budget.resetAttribution(target, provider, today, _jsonDumpsIndent2);
+        return counts;
+    });
 }
 
 /**
- * Build the pre-run quota summary line (step-8 P1, D1 + D4).
- *
- * Returns `[summary, warn_providers]` where `summary` is the formatted
- * one-liner (empty string when no CLI member has a configured cap) and
- * `warn_providers` is the subset whose `used / max_calls_per_day` ratio crossed
- * `warn_at`. Uncapped providers (`max_calls_per_day is None`) are omitted from
- * the summary entirely — they cannot exceed a threshold that does not exist.
+ * Build the pre-run quota summary line (step-8 P1, D1 + D4). Formatting lives in
+ * `cli_call_budget.ts`; this reads the counter and delegates.
  */
 export function quota_summary_line(
     clients: CliClient[],
     opts: { cli_calls_path?: string | null } = {},
 ): [string, string[]] {
-    const cliCallsPath = opts.cli_calls_path ?? null;
-    // Python: [c for c in clients if getattr(c, "max_calls_per_day", None)]
-    // → truthy check (None or 0 both falsy).
-    const capped = clients.filter((c) => _pyTruthy(_getattr(c, 'max_calls_per_day', null)));
-    if (capped.length === 0) {
-        return ['', []];
-    }
-    const counts = load_cli_call_counts(cliCallsPath);
-    const parts: string[] = [];
-    const warn: string[] = [];
-    for (const c of capped) {
-        const name = _getattr(c, 'name', '?') as string;
-        const used = _pyInt(counts[name] ?? 0);
-        const limit = _pyInt((c.max_calls_per_day as number));
-        parts.push(`${name} ${used}/${limit}`);
-        const ratio = limit > 0 ? used / limit : 0.0;
-        const warnAt = Number(_getattr(c, 'warn_at', 0.8));
-        if (ratio >= warnAt) {
-            warn.push(name);
-        }
-    }
-    const prefix = warn.length > 0 ? '⚠️  ' : '';
-    return [`${prefix}council:quota · ${parts.join(' · ')}`, warn];
+    return budget.quotaSummaryLine(clients, load_cli_call_counts(opts.cli_calls_path ?? null));
 }
 
 /** Transport-seam result, shaped like a finished `subprocess.run`. */
@@ -1196,6 +1208,8 @@ export abstract class CliClient extends ExternalAIClient {
     warn_at: number;
     binary!: string;
     protected _cli_calls_path: string | null;
+    /** Attribution label for every booking this client makes. */
+    protected _consumer: string;
 
     static _AUTH_FAILURE_PATTERNS: readonly string[] = [
         'authentication',
@@ -1239,6 +1253,7 @@ export abstract class CliClient extends ExternalAIClient {
         this.max_calls_per_day = opts.max_calls_per_day ?? null;
         this.warn_at = opts.warn_at ?? 0.8;
         this._cli_calls_path = opts.cli_calls_path ?? null;
+        this._consumer = opts.consumer ?? budget.CLI_CONSUMER_UNKNOWN;
         const binary = opts.binary ?? null;
         if (binary !== null) {
             this.binary = binary;
@@ -1287,7 +1302,7 @@ export abstract class CliClient extends ExternalAIClient {
      */
     protected _recordCallQuietly(): void {
         try {
-            record_cli_call(this.name, this._cli_calls_path);
+            record_cli_call(this.name, this._cli_calls_path, this._consumer);
         } catch {
             // state-file write failure is non-fatal here.
         }
@@ -1441,6 +1456,9 @@ export abstract class CliClient extends ExternalAIClient {
                         cli: true,
                         cli_calls_used: used,
                         cli_calls_max: this.max_calls_per_day,
+                        // Our counter refused before any spawn — nothing sent,
+                        // nothing booked for this call.
+                        quota_source: budget.QUOTA_SOURCE_LOCAL_BUDGET,
                     },
                 });
             }
@@ -1549,6 +1567,13 @@ export abstract class CliClient extends ExternalAIClient {
                     cli: true,
                     returncode: proc.returncode,
                     stderr_tail: (proc.stderr || '').slice(-500),
+                    // The vendor refused us; the local-budget refusal above
+                    // returns before spawning. Opposite remedies, one error
+                    // string — so discriminate explicitly rather than leaving it
+                    // inferable from which metadata keys happen to be absent.
+                    ...(code === 'cli_quota_exhausted'
+                        ? { quota_source: budget.QUOTA_SOURCE_PROVIDER }
+                        : {}),
                 },
             });
         }
@@ -1679,23 +1704,23 @@ export class AnthropicCliClient extends CliClient {
             // documented "disable all tools" value.
             //
             // It also repairs a live failure, which is how the grant was found
-            // rather than reasoned about. The spawn inherits the caller's cwd
-            // (`_runSubprocess` sets none, deliberately — the worker-role marker
-            // below depends on the vendor CLI loading this repo's hook chain),
-            // so invoking the council from inside a repository made the child
-            // load that project's own instructions AND every tool definition.
-            // In this package that overflowed the model's context window
-            // outright: `is_error: true`, `"the request is ~214331 tokens
+            // rather than reasoned about. AT THE TIME (2026-08-12) the spawn
+            // inherited the caller's cwd, so invoking the council from inside a
+            // repository made the child load that project's own instructions AND
+            // every tool definition. In this package that overflowed the context
+            // window outright: `is_error: true`, `"the request is ~214331 tokens
             // (limit 200000) … the rest is system prompt, tool definitions"`,
-            // exit 1, empty stderr — so the member reported as unavailable with
-            // no diagnosable cause. Measured 2026-08-12: identical call from
-            // `/tmp` exit 0, from the worktree exit 1, and adding this one flag
-            // returns the worktree call to exit 0.
+            // exit 1, empty stderr — the member reported unavailable with no
+            // diagnosable cause. Identical call from `/tmp` exit 0, from the
+            // worktree exit 1, and this one flag returns the worktree to exit 0.
             //
-            // Dropping the tools rather than neutralising the cwd is the
-            // narrower fix of the two: it leaves the worker-role hook chain
-            // intact and removes only the capability the role never had a use
-            // for. The context saving is a consequence, not the justification.
+            // TENSE CORRECTED 2026-08-16. This block read "`_runSubprocess` sets
+            // none, deliberately" and "dropping the tools RATHER THAN
+            // neutralising the cwd" — both false since `_runSubprocess` set
+            // `cwd: os.tmpdir()` for a DIFFERENT contamination (a member
+            // answering this repo's `end-review-nudge`). Two repairs, one
+            // cause, neither aware of the other, so a reader here concluded
+            // the cwd is inherited. Both are live; this flag bounds what a member may DO.
             '--tools',
             '',
             '--append-system-prompt',
@@ -1836,10 +1861,10 @@ export class OpenAICliClient extends CliClient {
                 `"The '${this.model}' model is not supported when using Codex with a ` +
                 'ChatGPT account." The CLI publishes no list of models it DOES accept, ' +
                 'so there is no supported set to offer here — the one configuration ' +
-                'measured to work is no pin at all. Fix: remove the `model:` line from ' +
-                'the openai member (or set it to `codex-default`) to use the CLI\'s own ' +
-                'default. A pinned model is only reachable on the API transport ' +
-                '(`api_key_ref:` without `mode: cli`).',
+                'measured to work is no pin at all. Fix: set `model: codex-default` on ' +
+                'the openai member. Do NOT delete the `model:` line — an enabled member ' +
+                'with no model fails config load, so that takes EVERY provider to NOT ' +
+                'CONFIGURED. A pin is reachable only on the API transport.',
         };
     }
 
@@ -1985,8 +2010,8 @@ export class OpenAICliClient extends CliClient {
                         ? {
                               hint:
                                   'the codex subscription transport serves no explicitly pinned ' +
-                                  'model measured so far — remove the `model:` line from the ' +
-                                  'openai member to use the CLI default',
+                                  'model measured so far — set `model: codex-default` on the ' +
+                                  'openai member; deleting the line fails config load',
                           }
                         : {}),
                 },
@@ -2719,94 +2744,6 @@ function _excMessage(exc: unknown): string {
     return String(exc);
 }
 
-/** `json.dumps(obj, indent=2)` — default ensure_ascii=True, insertion-order keys. */
-function _jsonDumpsIndent2(value: unknown): string {
-    return _jsonDumpsIndented(value, 2, 0);
-}
-
-function _jsonDumpsIndented(value: unknown, indent: number, level: number): string {
-    if (value === null || value === undefined) {
-        return 'null';
-    }
-    switch (typeof value) {
-        case 'boolean':
-            return value ? 'true' : 'false';
-        case 'number':
-            return _pyJsonNumber(value);
-        case 'string':
-            return _pyJsonStringAscii(value);
-        case 'object':
-            break;
-        default:
-            throw new TypeError(`Object of type ${typeof value} is not JSON serializable`);
-    }
-    const pad = ' '.repeat(indent * (level + 1));
-    const closePad = ' '.repeat(indent * level);
-    if (Array.isArray(value)) {
-        if (value.length === 0) {
-            return '[]';
-        }
-        const items = value.map((v) => pad + _jsonDumpsIndented(v, indent, level + 1));
-        return `[\n${items.join(',\n')}\n${closePad}]`;
-    }
-    const obj = value as Record<string, unknown>;
-    const keys = Object.keys(obj);
-    if (keys.length === 0) {
-        return '{}';
-    }
-    const items = keys.map(
-        (k) => `${pad}${_pyJsonStringAscii(k)}: ${_jsonDumpsIndented(obj[k], indent, level + 1)}`,
-    );
-    return `{\n${items.join(',\n')}\n${closePad}}`;
-}
-
-/** Render a number like Python `json.dumps` (int vs float; JS has one type). */
-function _pyJsonNumber(n: number): string {
-    if (!Number.isFinite(n)) {
-        if (Number.isNaN(n)) {
-            return 'NaN';
-        }
-        return n > 0 ? 'Infinity' : '-Infinity';
-    }
-    return String(n);
-}
-
-/** Escape a string like Python `json.dumps(..., ensure_ascii=True)` (default). */
-function _pyJsonStringAscii(s: string): string {
-    let out = '"';
-    for (const ch of s) {
-        const code = ch.codePointAt(0) ?? 0;
-        if (ch === '"') {
-            out += '\\"';
-        } else if (ch === '\\') {
-            out += '\\\\';
-        } else if (ch === '\b') {
-            out += '\\b';
-        } else if (ch === '\f') {
-            out += '\\f';
-        } else if (ch === '\n') {
-            out += '\\n';
-        } else if (ch === '\r') {
-            out += '\\r';
-        } else if (ch === '\t') {
-            out += '\\t';
-        } else if (code < 0x20) {
-            out += `\\u${code.toString(16).padStart(4, '0')}`;
-        } else if (code < 0x7f) {
-            out += ch;
-        } else if (code <= 0xffff) {
-            out += `\\u${code.toString(16).padStart(4, '0')}`;
-        } else {
-            // Astral plane → surrogate pair, matching Python json.dumps default.
-            const c = code - 0x10000;
-            const hi = 0xd800 + (c >> 10);
-            const lo = 0xdc00 + (c & 0x3ff);
-            out += `\\u${hi.toString(16).padStart(4, '0')}\\u${lo.toString(16).padStart(4, '0')}`;
-        }
-    }
-    return out + '"';
-}
-
 /** Python `shutil.which(name)` — resolve an executable on PATH. */
 function _which(name: string): string | null {
     // Absolute / relative path with a separator: check directly (Python's which

package/src/scripts/ai_council/config.ts

@@ -76,6 +76,7 @@ import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 
 import * as user_global_paths from '../_lib/user_global_paths.js';
+import * as budget from './cli_call_budget.js';
 // LAYERING CONSTRAINT, load-bearing: this is a VALUE import from quorum, while
 // `quorum.ts` imports `QuorumSetting` back from here. That back-edge is
 // `import type` and is erased at build, so there is no runtime cycle today.
@@ -1927,13 +1928,23 @@ function _build_member(
  * Generous per-provider guard for `mode: cli` / `mode: auto` members
  * (road-to-always-on-orchestration Phase 3.4). Before this default the map
  * shipped empty and an unlisted provider ran uncapped — a plan-quota guard
- * that only existed if the user remembered to opt in. Every known provider
- * now carries this floor unless a config entry overrides it; sized as a
- * GUARD against silent quota exhaustion on an always-on pass, not a brake on
- * normal use (see the template's own worked-example sizing for the
- * reasoning behind a TIGHTER per-provider number).
+ * that only existed if the user remembered to opt in.
+ *
+ * Re-exported from `cli_call_budget.ts`, which owns it: `build_members` and
+ * `cmd_quota` both need the same number, and re-deriving it at either site is
+ * how the reported cap and the enforced cap drift apart.
  */
-const _DEFAULT_CLI_CALLS_PER_DAY = 50;
+export const DEFAULT_CLI_CALLS_PER_DAY = budget.DEFAULT_CLI_CALLS_PER_DAY;
+
+/**
+ * Resolve the per-provider daily cap map — the SINGLE authority, shared with the
+ * gate and the report. Thin wrapper that supplies this module's provider set;
+ * the contract (defaults on omission, lenient where this module is strict) is
+ * documented on `budget.resolveCliCallCaps`.
+ */
+export function resolve_cli_call_caps(raw: unknown): Record<string, number> {
+    return budget.resolveCliCallCaps(raw, _VALID_PROVIDERS);
+}
 
 function _build_cli_call_budget(d: Dict): CliCallBudgetConfig {
     if (!_isDict(d)) {
@@ -1945,10 +1956,11 @@ function _build_cli_call_budget(d: Dict): CliCallBudgetConfig {
             '`cli_call_budget.max_calls_per_day` must be a mapping.',
         );
     }
-    const caps = new Map<string, number>();
-    for (const provider of _VALID_PROVIDERS) {
-        caps.set(provider, _DEFAULT_CLI_CALLS_PER_DAY);
-    }
+    // Validate FIRST, then resolve. Splitting the two is what lets the strict
+    // builder and the lenient `resolve_cli_call_caps` share one seeding
+    // implementation without either weakening the other: every rejection below
+    // still throws, and what survives is handed to the shared resolver rather
+    // than seeded a second time here.
     for (const [provider, value] of Object.entries(raw_caps)) {
         if (!_VALID_PROVIDERS.has(provider)) {
             throw new CouncilConfigError(
@@ -1962,8 +1974,10 @@ function _build_cli_call_budget(d: Dict): CliCallBudgetConfig {
                     `non-negative integer (got ${_pyRepr(value)}).`,
             );
         }
-        caps.set(provider, value);
     }
+    const caps = new Map<string, number>(
+        Object.entries(resolve_cli_call_caps(raw_caps)),
+    );
     const warn_at_raw = _get(d, 'warn_at', 0.8);
     if (_isBool(warn_at_raw) || !_isNumber(warn_at_raw)) {
         throw new CouncilConfigError(

package/src/scripts/ai_council/probe_store.ts

@@ -0,0 +1,196 @@
+/**
+ * The observation half of provider qualification (road-to-release-review-p0
+ * Phase 3).
+ *
+ * `qualification.ts` is pure and answers "given what has been observed, what
+ * may this seat claim". This module is the only thing that observes. It exists
+ * because the qualification ladder's strongest rung — has a real exchange with
+ * this provider ever succeeded — cannot be answered from configuration, and
+ * answering it with a fresh probe would mean spending money every time anyone
+ * asked whether the council was healthy.
+ *
+ * So nothing here probes. A council run that receives a non-empty answer from a
+ * seat has already performed the exchange; this records that it happened. The
+ * cost of the observation is zero because the observation is a by-product of
+ * work the operator asked for anyway, and a seat therefore decays out of
+ * `unknown` through normal use rather than through a maintenance ritual.
+ *
+ * **The store is deliberately runtime-local and gitignored.** `agents/runtime/`
+ * is not tracked, which has a consequence worth stating rather than
+ * discovering: a fresh worktree starts with no observations, so every seat
+ * reads `unknown` there until a run happens in it. That is the honest reading —
+ * a checkout that has never talked to a provider genuinely has no evidence that
+ * it can — and it is strictly better than the alternative of committing a
+ * machine-specific health claim into a shared tree, where it would be stale for
+ * everyone but the machine that wrote it.
+ *
+ * Corrupt or unreadable state is treated as "no observations", never as an
+ * error: the same tolerant-reader doctrine the settings surface follows. A
+ * status command that crashes because a JSON file has a stray byte is worse
+ * than one that reports `unknown`, which is what the absence of evidence
+ * actually means.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { isEnvKillSwitchActive } from '../_lib/env_kill_switch.js';
+import type { CliFailureClass } from './transport_resolver.js';
+import type { ProbeRecord } from './qualification.js';
+
+/**
+ * The same kill-switch the council event log honours.
+ *
+ * Sharing it rather than minting a second name is deliberate: both write
+ * council observational state into the worktree, and the suite that needs one
+ * suppressed needs the other suppressed for the identical reason. The
+ * read-only witness in `tests/scripts/witness/` fails on ANY worktree path
+ * appearing while it runs — including a gitignored one — so a test that
+ * exercises `cmd_run` and silently dropped a probe row here would break that
+ * witness whenever sharding put the two files together. Measured on this
+ * branch: the first version of this module had no switch and wrote
+ * `agents/runtime/state/council-probes.json` during the council suite.
+ *
+ * The coupling has a real cost worth stating: an operator who suppresses the
+ * event log also stops accumulating observations, so seats stay `unknown`.
+ * That is the correct direction — a run whose telemetry is switched off did
+ * not record evidence, and pretending otherwise is the over-claim this whole
+ * module exists to remove.
+ */
+const _KILL_SWITCH_ENV = 'AGENT_CONFIG_NO_EVENTS_LOG';
+
+/** Repo-relative location. Runtime state, gitignored, never committed. */
+export const PROBE_STORE_RELPATH = path.join('agents', 'runtime', 'state', 'council-probes.json');
+
+export interface ProbeStore {
+    readonly schema: 1;
+    readonly members: Readonly<Record<string, ProbeRecord>>;
+}
+
+const EMPTY: ProbeStore = { schema: 1, members: {} };
+
+/**
+ * The closed set a stored `outcome` may hold — `ok` plus every
+ * `CliFailureClass`. Duplicated as a runtime value because the type erases,
+ * and this is a trust boundary: the file is hand-editable.
+ */
+const VALID_OUTCOMES: ReadonlySet<string> = new Set<'ok' | CliFailureClass>([
+    'ok',
+    'binary_missing',
+    'auth_rejected',
+    'cli_unsupported',
+    'model_unservable',
+    'timeout',
+    'server_error',
+    'quota_exhausted',
+    'other',
+]);
+
+export function probeStorePath(root: string): string {
+    return path.join(root, PROBE_STORE_RELPATH);
+}
+
+/**
+ * Read the store. Any failure — missing, unreadable, malformed, wrong schema —
+ * yields the empty store.
+ *
+ * Individual member entries are validated one by one rather than trusting the
+ * object wholesale: a single corrupt row must not discard the other seats'
+ * evidence, because that would silently downgrade healthy seats to `unknown`
+ * and the operator would have no way to tell the two causes apart.
+ */
+export function readProbeStore(root: string): ProbeStore {
+    let raw: string;
+    try {
+        raw = fs.readFileSync(probeStorePath(root), 'utf8');
+    } catch {
+        return EMPTY;
+    }
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return EMPTY;
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        return EMPTY;
+    }
+    const obj = parsed as Record<string, unknown>;
+    if (obj['schema'] !== 1) {
+        return EMPTY;
+    }
+    const membersRaw = obj['members'];
+    if (typeof membersRaw !== 'object' || membersRaw === null) {
+        return EMPTY;
+    }
+    const members: Record<string, ProbeRecord> = {};
+    for (const [name, value] of Object.entries(membersRaw as Record<string, unknown>)) {
+        if (typeof value !== 'object' || value === null) {
+            continue;
+        }
+        const v = value as Record<string, unknown>;
+        const at = v['at'];
+        const outcome = v['outcome'];
+        if (typeof at !== 'string' || at === '' || typeof outcome !== 'string') {
+            continue;
+        }
+        // Validated against the closed set, not cast into it. A bare
+        // non-empty-string check let a corrupt or hand-edited value through,
+        // where `_liveProbe` read it as `!== 'ok'` and not impaired — i.e. a
+        // typo silently downgraded a healthy seat to `unavailable`
+        // (R2 finding 9). Dropping the row instead yields `unknown`, which is
+        // the honest reading of "this record is unreadable".
+        if (!VALID_OUTCOMES.has(outcome)) {
+            continue;
+        }
+        members[name] = { at, outcome: outcome as 'ok' | CliFailureClass };
+    }
+    return { schema: 1, members };
+}
+
+/**
+ * Record one member's outcome, merging into whatever is already stored.
+ *
+ * Best-effort by construction: a write failure is swallowed. Telemetry that can
+ * break a council run is worse than telemetry that occasionally misses a row —
+ * the miss costs one `unknown`, the throw costs the run.
+ */
+export function recordProbe(
+    root: string,
+    name: string,
+    outcome: 'ok' | CliFailureClass,
+    at: string,
+): void {
+    recordProbes(root, [{ name, outcome, at }]);
+}
+
+/** One observation, as a caller collects them during a pass. */
+export interface ProbeEntry {
+    readonly name: string;
+    readonly outcome: 'ok' | CliFailureClass;
+    readonly at: string;
+}
+
+/** Batch form — one read/write for a whole pass rather than one per member. */
+export function recordProbes(root: string, entries: readonly ProbeEntry[]): void {
+    if (entries.length === 0 || isEnvKillSwitchActive(_KILL_SWITCH_ENV)) {
+        return;
+    }
+    try {
+        const current = readProbeStore(root);
+        const members: Record<string, ProbeRecord> = { ...current.members };
+        for (const e of entries) {
+            members[e.name] = { at: e.at, outcome: e.outcome };
+        }
+        const target = probeStorePath(root);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, `${JSON.stringify({ schema: 1, members }, null, 2)}\n`, 'utf8');
+    } catch {
+        // Intentionally silent — see the docstring.
+    }
+}
+
+/** The record for one member, or null when nothing was ever observed. */
+export function probeFor(store: ProbeStore, name: string): ProbeRecord | null {
+    return store.members[name] ?? null;
+}