@event4u/agent-config 14.8.0 → 14.10.0

package/src/scripts/ai_council/seating.ts

@@ -0,0 +1,211 @@
+/**
+ * Who is seated for a run, decided once and frozen.
+ *
+ * Selection today is config-static ask-all: every enabled member, every
+ * question, no per-question seating. This adds an OPTIONAL declaration of what
+ * a run wants from its seats, and computes the answer once.
+ *
+ * FAMILY DIVERSITY ONLY — no band ordering. `blocker: b-ladder-order-benchmark-spend`
+ * was resolved (b) on 2026-08-22: nothing in this tree establishes that a higher
+ * capability band reviews better, the archived benchmark substrate would have to
+ * be re-run to support it, and the council that would have decided otherwise had
+ * no quota. So `tier` keeps its single documented meaning — a capability rank
+ * read only as a chairman-selection input — and nothing here reads it. A seat
+ * declaration carries MISSION, never RANK.
+ *
+ * "Family" is the PROVIDER, not a capability band. For a council, diversity means
+ * independent providers: two Claude bands share a vendor, a training pipeline and
+ * a failure mode, so seating `opus` beside `sonnet` buys none of what a second
+ * opinion is for. (`MODEL_FAMILIES` in the orchestration-record hook enumerates
+ * Claude bands for a different purpose — token attribution — and is deliberately
+ * not reused here.)
+ *
+ * Absent declaration ⇒ today's behaviour, byte-identical. That is asserted by a
+ * test rather than intended.
+ */
+import type { MemberConfig } from './config.js';
+
+/** A member's provider family. The map key IS the provider in this config shape. */
+export function familyOf(member: MemberConfig): string {
+    return member.name;
+}
+
+/**
+ * Read the optional `seat_constraints:` block out of a raw council config.
+ *
+ * DELIBERATELY NOT A FIELD ON `CouncilConfig`, and the reason is a ratchet
+ * rather than a design preference. `config.ts` is 2,205 lines — 705 over the
+ * 1,500-line source-size line — and `check_source_size_budget` counts only the
+ * excess above that line, so the 39 lines this feature first added there were a
+ * straight +39 against a shrink-only baseline. The gate's own message is
+ * explicit that raising the baseline is "a defect, not a fix". Extraction is the
+ * sanctioned repair, and this file is 169 lines, so the same code costs nothing
+ * here.
+ *
+ * THE TRADE-OFF, stated rather than buried: validation moves from LOAD time to
+ * READ time. A malformed `min_families` no longer fails the moment the config
+ * is parsed; it fails when a caller asks for the constraints. Today that
+ * difference is unobservable — Phase 2 ships the DECLARATION and no caller
+ * reads it yet — but it is a real change in when a bad config is caught, and
+ * whoever wires the first caller should call this at run start so the failure
+ * lands before any seat is used.
+ *
+ * Fails CLOSED on a malformed value rather than falling back to absent: a run
+ * that declared a diversity floor and silently got none is the exact silent
+ * fallback the degradation line exists to prevent.
+ */
+export function readSeatConstraints(raw: unknown, label = 'seat_constraints'): SeatConstraints {
+    if (raw === null || raw === undefined) return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new TypeError(`${label} must be a mapping (got ${typeof raw}).`);
+    }
+    const block = (raw as Record<string, unknown>)['seat_constraints'] ?? raw;
+    if (block === null || block === undefined) return {};
+    if (typeof block !== 'object' || Array.isArray(block)) {
+        throw new TypeError(`${label} must be a mapping (got ${typeof block}).`);
+    }
+    const mf = (block as Record<string, unknown>)['min_families'];
+    if (mf === null || mf === undefined) return {};
+    if (typeof mf !== 'number' || !Number.isInteger(mf) || mf < 1) {
+        throw new TypeError(`${label}.min_families must be an integer >= 1 when set (got ${String(mf)}).`);
+    }
+    return { min_families: mf };
+}
+
+export interface SeatConstraints {
+    /**
+     * Minimum distinct provider families the run wants seated.
+     *
+     * Absent (or 1) ⇒ no constraint and no degradation line: ask-all, unchanged.
+     */
+    readonly min_families?: number;
+}
+
+export interface Seating {
+    /** The seated members, in deterministic config order. */
+    readonly seats: readonly MemberConfig[];
+    /** Distinct families actually seated. */
+    readonly families: readonly string[];
+    /**
+     * Exactly ONE line when the constraint could not be met, `null` otherwise.
+     *
+     * One line, not a wall: a degradation nobody reads is the same as a silent
+     * fallback, and N warnings is how a reader learns to skip the header.
+     */
+    readonly degraded: string | null;
+}
+
+/**
+ * Compute the seating once.
+ *
+ * Deterministic and side-effect-free: the same members and constraints always
+ * produce the same seats, which is what makes freezing it meaningful. Seating
+ * that changed between round 1 and round 3 would silently invalidate the
+ * anonymised-peer-reply contract the council skill depends on — a "reviewer B"
+ * in round 3 that is not the "reviewer B" of round 1 makes every cross-reference
+ * in the synthesis wrong while looking fine.
+ */
+export function resolveSeating(
+    members: readonly MemberConfig[],
+    constraints: SeatConstraints = {},
+): Seating {
+    const enabled = members.filter((m) => m.enabled);
+    const families = [...new Set(enabled.map(familyOf))];
+    const want = constraints.min_families ?? 1;
+
+    if (want <= 1 || families.length >= want) {
+        return { seats: enabled, families, degraded: null };
+    }
+    return {
+        seats: enabled,
+        families,
+        degraded:
+            `tier-degraded: asked for ${String(want)} model families, seated ${String(families.length)} ` +
+            `(${families.join(', ')}). The run proceeds with what is enabled — a council that refused to ` +
+            `convene on a diversity shortfall would fail closed on the common single-provider install, ` +
+            `which is worse than a stated shortfall.`,
+    };
+}
+
+/**
+ * Freeze a seating so a later config mutation cannot change it.
+ *
+ * Returns a structurally frozen snapshot. This is the mechanism behind "resolve
+ * once per run": the caller resolves at run start, freezes, and passes the
+ * snapshot down — so there is no path by which round 3 re-reads the config.
+ */
+export function freezeSeating(s: Seating): Seating {
+    return Object.freeze({
+        seats: Object.freeze([...s.seats]),
+        families: Object.freeze([...s.families]),
+        degraded: s.degraded,
+    });
+}
+
+/**
+ * Vendor sentinels and "latest in band" aliases — an id that cannot go stale.
+ *
+ * Read from the providers' own CLI surfaces on 2026-08-22, never from recall:
+ * `claude --help` documents 'fable', 'opus' and 'sonnet' as aliases for the
+ * latest model in their band, and `codex-default` is the openai transport's
+ * documented "let the CLI choose".
+ */
+export const ADMISSIBLE_SENTINELS: ReadonlySet<string> = new Set([
+    'codex-default',
+    'fable',
+    'opus',
+    'sonnet',
+    'haiku',
+]);
+
+export interface AdmissibilityResult {
+    readonly admissible: boolean;
+    readonly reason: string | null;
+}
+
+/**
+ * Is this member's `model:` id from an admissible SOURCE?
+ *
+ * THE CRITERION AS WRITTEN COULD NOT BE IMPLEMENTED, and the deviation is
+ * recorded here rather than papered over. The roadmap step says a declared seat
+ * "resolves through the shipped `model_tier` bands; a model id that no tier maps
+ * to is rejected at config load". But `TIER_TO_CLAUDE_MODEL`
+ * (`_lib/model_tier.ts:36-41`) maps tiers onto CLAUDE aliases only — there is no
+ * entry any `gemini-*`, `grok-*` or `sonar-*` id could resolve through. Taken
+ * literally, that rule rejects every non-anthropic member in the shipped starter
+ * config, i.e. it fails closed on a valid config.
+ *
+ * What the step is actually protecting is stated in its own title: "including
+ * the host's own recall". The failure mode is a plausible-sounding model id
+ * TYPED FROM MEMORY, which is indistinguishable from a real one at review time
+ * and would silently undo the pin refresh. So admissibility is checked against
+ * the SOURCE of the id, over the two things this tree can actually verify:
+ *
+ *   1. a vendor sentinel or documented "latest in band" alias — cannot go stale,
+ *      and read from the provider's own surface; or
+ *   2. a dated pin carrying a `verified_at` stamp — which records that a human
+ *      looked at the provider's surface on a named date, and which
+ *      `check_council_pin_staleness` ages out.
+ *
+ * An id that is neither is exactly the recall case: a bare dated id nobody
+ * recorded checking.
+ */
+export function checkModelAdmissibility(member: MemberConfig): AdmissibilityResult {
+    const id = member.model.trim().toLowerCase();
+    if (ADMISSIBLE_SENTINELS.has(id)) {
+        return { admissible: true, reason: null };
+    }
+    if (member.verified_at !== null && member.verified_at !== undefined) {
+        return { admissible: true, reason: null };
+    }
+    return {
+        admissible: false,
+        reason:
+            `members.${member.name}.model is '${member.model}' — a dated id with no verified_at stamp. ` +
+            `An id must come from a source this tree can check: a vendor sentinel or documented ` +
+            `"latest in band" alias (${[...ADMISSIBLE_SENTINELS].join(', ')} — see src/scripts/_lib/model_tier.ts ` +
+            `for the tier vocabulary these bands come from), or a pin carrying verified_at: "YYYY-MM-DD" ` +
+            `recorded from the provider's own surface. A model id remembered rather than read is not an ` +
+            `admissible source, and is indistinguishable from a real one at review time.`,
+    };
+}

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';
 }
 
 /**

package/src/scripts/audit_adr_coverage.ts

@@ -28,7 +28,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { readAdrFrontmatterScalars } from './_lib/adr_frontmatter.js';
+import { readAdrAxisCells, readAdrFrontmatterScalars } from './_lib/adr_frontmatter.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -279,8 +279,13 @@ export function scan_area(area: string): [AdrEntry[], string[]] {
             errs.push(`${area}/${base}: filename does not match NNNN-<slug>.md`);
             continue;
         }
-        const fm = read_adr_meta(fs.readFileSync(p, 'utf-8'));
-        adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm });
+        const text = fs.readFileSync(p, 'utf-8');
+        const fm = read_adr_meta(text);
+        // Read apart from `fm`, for the same reason the index does: the two
+        // axes are nested, so the scalar reader keeps them out of its map and
+        // spreading it could never produce these cells.
+        const axes = readAdrAxisCells(text);
+        adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm, ...axes });
     }
     // Gap check.
     const nums = adrs.map((a) => parseInt(a.num, 10));
@@ -322,7 +327,11 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
     } else {
         lines.push(`Contract: _not yet published_ (\`${repoRel}\`).`);
     }
-    lines.push('', '| # | Title | Status | Date | Supersedes |', '|---|---|---|---|---|');
+    lines.push(
+        '',
+        '| # | Title | Status | Date | Provenance | Evidence | Supersedes |',
+        '|---|---|---|---|---|---|---|',
+    );
     for (const a of adrs) {
         // a.get("decision", a["slug"]).replace("-", " ").title()
         const decision = a['decision'] !== undefined ? a['decision'] : a.slug;
@@ -330,11 +339,12 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
         lines.push(
             `| [${a.num}](${a.path}) | ${title} | ` +
                 `${a['status'] ?? '—'} | ${a['date'] ?? '—'} | ` +
+                `${a['provenance_kind'] ?? '—'} | ${a['evidence_grade'] ?? '—'} | ` +
                 `${a['supersedes'] ?? '—'} |`,
         );
     }
     if (adrs.length === 0) {
-        lines.push('| _none yet_ | — | — | — | — |');
+        lines.push('| _none yet_ | — | — | — | — | — | — |');
     }
     return lines.join('\n') + '\n';
 }
@@ -411,9 +421,26 @@ export function cmd_check(): number {
             process.stderr.write(`❌ ${e}\n`);
             hard += 1;
         }
-        if (adrs.length > 0 && !_exists(path.join(ADR_ROOT, area, 'README.md'))) {
+        const readmePath = path.join(ADR_ROOT, area, 'README.md');
+        if (adrs.length > 0 && !_exists(readmePath)) {
             process.stderr.write(`❌ ${area}/: README.md missing\n`);
             hard += 1;
+        } else if (_exists(readmePath)) {
+            // Existence was the whole check until 2026-08-22, and the six
+            // committed READMEs proved what that costs: every one of them had
+            // been generated before the shared frontmatter reader landed, so
+            // they rendered `—` for `status` and `date` on ADRs that carry
+            // both — stale for months against a gate reporting zero failures.
+            // A generated file with no freshness gate is a file nobody
+            // regenerates.
+            const rendered = render_area_readme(area, meta, adrs);
+            if (fs.readFileSync(readmePath, 'utf-8') !== rendered) {
+                process.stderr.write(
+                    `❌ ${area}/README.md is stale — regenerate with ` +
+                        `\`audit_adr_coverage --regen-area-readme ${area}\`\n`,
+                );
+                hard += 1;
+            }
         }
         if (adrs.length === 0) {
             process.stderr.write(`⚠️  ${area}/: no bootstrap ADR yet (contract: ${meta.contract})\n`);

package/src/scripts/check_council_pin_staleness.ts

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+/**
+ * A council model pin cannot notice its own age. This gate is what notices.
+ *
+ * THE DEFECT IT EXISTS FOR. The starter council config shipped a dated,
+ * several-generation-old model id on an **enabled** member — the seat a quality
+ * council actually reviews with — and nothing in the file could flag it: a grep
+ * for `verified_at` or `stale` over the template returned two prose comments and
+ * no key. The pin was unversioned and unstamped, so it rotted silently for as
+ * long as nobody happened to re-read a template.
+ *
+ * WHAT IT DOES NOT DO, and this is the honest half: it cannot tell whether a
+ * pinned id is current. That needs the provider's own listing, which lives
+ * outside this tree and changes on the provider's schedule. It reports how long
+ * ago a **human** last said they looked. A stamp is a claim about attention, not
+ * about correctness, and treating it as the second would be worse than no stamp.
+ *
+ * SENTINELS ARE EXEMPT, BY DESIGN. A member on `codex-default`, or on a vendor
+ * alias the provider documents as "the latest model" in a band (`claude --help`:
+ * 'fable', 'opus', 'sonnet'), delegates the version decision to the vendor CLI
+ * and cannot go stale. Demanding a date there would be asking for a refresh
+ * nobody would ever perform, which is how a gate teaches its reader to ignore
+ * it.
+ *
+ * Mirrors `check_corpus_staleness` rather than inventing a second idiom:
+ * offline, deterministic, and the clock is INJECTABLE via `--today YYYY-MM-DD`
+ * so a fixture cannot flip verdict with the calendar. A future date is its own
+ * violation class — a stamp ahead of today is not "very fresh", it is a typo or
+ * a fabrication, and collapsing it into the fresh path would hide exactly the
+ * case worth catching.
+ *
+ * Exit: 0 clean or advisory-only, 1 on a violation, 2 on a usage error
+ * (unparsable config, bad --today, or a dead scan scope).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+import { runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+
+/** Days before a stamped pin is called stale. */
+export const CADENCE_DAYS = 100;
+
+/**
+ * Vendor sentinels and "latest in band" aliases — a member on one of these
+ * cannot go stale, so it needs no stamp.
+ *
+ * The alias set is READ FROM the provider's own CLI surface (`claude --help`
+ * documents 'fable', 'opus' and 'sonnet' as aliases for the latest model), not
+ * from the agent's recall. That distinction is the one the roadmap behind this
+ * gate names as its top risk: a plausible-sounding id typed from memory is
+ * indistinguishable from a real one at review time.
+ */
+export const SENTINEL_MODELS: ReadonlySet<string> = new Set([
+    'codex-default',
+    'fable',
+    'opus',
+    'sonnet',
+    'haiku',
+]);
+
+export type Verdict = 'fresh' | 'sentinel' | 'unstamped' | 'stale' | 'future-date' | 'malformed';
+
+export interface PinRow {
+    member: string;
+    model: string;
+    verified_at: string | null;
+    enabled: boolean;
+    verdict: Verdict;
+    age_days: number | null;
+}
+
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/** Parse a `YYYY-MM-DD` into a UTC epoch-day, or null when it is not a real date. */
+export function epochDay(s: string): number | null {
+    const m = DATE_RE.exec(s);
+    if (m === null) return null;
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const d = Number(m[3]);
+    const t = Date.UTC(y, mo - 1, d);
+    const probe = new Date(t);
+    if (probe.getUTCFullYear() !== y || probe.getUTCMonth() + 1 !== mo || probe.getUTCDate() !== d) {
+        return null;
+    }
+    return Math.floor(t / 86400000);
+}
+
+/** Classify one member. Pure — the unit under `--self-test`. */
+export function classify(
+    member: string,
+    model: string,
+    verified_at: string | null,
+    enabled: boolean,
+    today: string,
+): PinRow {
+    const base: Omit<PinRow, 'verdict' | 'age_days'> = { member, model, verified_at, enabled };
+    if (SENTINEL_MODELS.has(model.trim().toLowerCase())) {
+        return { ...base, verdict: 'sentinel', age_days: null };
+    }
+    if (verified_at === null || verified_at.trim() === '') {
+        return { ...base, verdict: 'unstamped', age_days: null };
+    }
+    const stamp = epochDay(verified_at);
+    if (stamp === null) return { ...base, verdict: 'malformed', age_days: null };
+    const now = epochDay(today);
+    if (now === null) throw new Error(`--today must be a real YYYY-MM-DD date (got ${today})`);
+    const age = now - stamp;
+    if (age < 0) return { ...base, verdict: 'future-date', age_days: age };
+    return { ...base, verdict: age > CADENCE_DAYS ? 'stale' : 'fresh', age_days: age };
+}
+
+/**
+ * Read the members out of a council YAML without a YAML dependency.
+ *
+ * Deliberately line-based and deliberately narrow: it reads `members:` two
+ * levels deep, which is the whole shape this gate needs. A full parser would
+ * pull a dependency into a gate whose entire job is to be runnable offline in
+ * any checkout.
+ */
+export function parseMembers(text: string): { member: string; model: string; verified_at: string | null; enabled: boolean }[] {
+    const lines = text.split('\n');
+    const out: { member: string; model: string; verified_at: string | null; enabled: boolean }[] = [];
+    let inMembers = false;
+    let cur: { member: string; model: string; verified_at: string | null; enabled: boolean } | null = null;
+    for (const raw of lines) {
+        const line = raw.replace(/\t/g, '  ');
+        if (/^members:\s*$/.test(line)) {
+            inMembers = true;
+            continue;
+        }
+        if (!inMembers) continue;
+        // A non-indented, non-empty, non-comment line ends the block.
+        if (line.trim() !== '' && !line.startsWith(' ') && !line.trimStart().startsWith('#')) break;
+        const head = /^ {2}([A-Za-z0-9_-]+):\s*$/.exec(line);
+        if (head !== null) {
+            if (cur !== null) out.push(cur);
+            cur = { member: String(head[1]), model: '', verified_at: null, enabled: false };
+            continue;
+        }
+        if (cur === null) continue;
+        const kv = /^ {4}([a-z_]+):\s*(.+?)\s*$/.exec(line);
+        if (kv === null) continue;
+        const k = String(kv[1]);
+        const v = String(kv[2]).replace(/^['"]|['"]$/g, '');
+        if (k === 'model') cur.model = v;
+        else if (k === 'verified_at') cur.verified_at = v;
+        else if (k === 'enabled') cur.enabled = v === 'true';
+    }
+    if (cur !== null) out.push(cur);
+    return out.filter((m) => m.model !== '');
+}
+
+function selfTest(): number {
+    const T = '2026-08-22';
+    let seq = 0;
+    // Each case drives the REAL gate over a real fixture, so what is asserted is
+    // the exit code rather than an internal verdict. Reject == the gate refuses.
+    const probe = (body: string): number => {
+        seq += 1;
+        const file = path.join(os.tmpdir(), `pin-staleness-selftest-${String(process.pid)}-${String(seq)}.yml`);
+        fs.writeFileSync(file, body, 'utf-8');
+        try {
+            return main(['--file', file, '--today', T]);
+        } catch (err) {
+            // Mirror the entrypoint: a dead scan scope exits 2 there, so a case
+            // asserting "must not pass" has to observe the same code rather than
+            // an exception the harness would read as a broken test.
+            if (err instanceof DeadScopeError) return 2;
+            throw err;
+        } finally {
+            fs.rmSync(file, { force: true });
+        }
+    };
+    const member = (model: string, stamp: string | null): string =>
+        `members:\n  m:\n    enabled: true\n    model: ${model}\n` +
+        (stamp === null ? '' : `    verified_at: "${stamp}"\n`);
+
+    const cases: SelfTestCase[] = [
+        { name: 'a sentinel needs no stamp', expect: 'accept', run: () => probe(member('codex-default', null)) },
+        { name: 'a vendor alias needs no stamp', expect: 'accept', run: () => probe(member('sonnet', null)) },
+        {
+            name: 'a dated pin with no stamp is advisory, not a failure',
+            expect: 'accept',
+            run: () => probe(member('gemini-2.5-pro', null)),
+        },
+        {
+            name: 'a stamp inside the cadence is fresh',
+            expect: 'accept',
+            run: () => probe(member('gemini-2.5-pro', '2026-08-01')),
+        },
+        // 100 exactly is fresh; 101 is not. A cadence met on the day it comes
+        // due is met — the same boundary `check_corpus_staleness` uses.
+        {
+            name: 'the cadence boundary is inclusive',
+            expect: 'accept',
+            run: () => probe(member('gemini-2.5-pro', '2026-05-14')),
+        },
+        {
+            name: 'a stamp past the cadence is refused',
+            expect: 'reject',
+            run: () => probe(member('gemini-2.5-pro', '2026-01-01')),
+        },
+        {
+            name: 'a future stamp is refused, not read as very fresh',
+            expect: 'reject',
+            run: () => probe(member('gemini-2.5-pro', '2027-01-01')),
+        },
+        {
+            name: 'an impossible date is refused, not treated as stale',
+            expect: 'reject',
+            run: () => probe(member('gemini-2.5-pro', '2026-02-30')),
+        },
+        { name: 'a non-date is refused', expect: 'reject', run: () => probe(member('gemini-2.5-pro', 'soon')) },
+        {
+            name: 'a member with no model: leaves an empty scan and must not pass',
+            expect: 'reject',
+            run: () => probe('members:\n  m:\n    enabled: true\n'),
+        },
+    ];
+    return runSelfTest({
+        gate: 'check_council_pin_staleness',
+        cases,
+        minCases: 10,
+        minRejectCases: 5,
+    });
+}
+
+function main(argv: string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const ti = argv.indexOf('--today');
+    const today =
+        ti >= 0 && argv[ti + 1] !== undefined
+            ? String(argv[ti + 1])
+            : new Date().toISOString().slice(0, 10);
+    if (epochDay(today) === null) {
+        process.stderr.write(`--today must be a real YYYY-MM-DD date (got ${today})\n`);
+        return 2;
+    }
+    const fi = argv.indexOf('--file');
+    const file =
+        fi >= 0 && argv[fi + 1] !== undefined
+            ? String(argv[fi + 1])
+            : path.join(process.cwd(), 'agents/templates/.ai-council.yml.example');
+    if (!fs.existsSync(file)) {
+        process.stderr.write(`no council config at ${file}\n`);
+        return 2;
+    }
+    const members = parseMembers(fs.readFileSync(file, 'utf-8'));
+    const rows = members.map((m) => classify(m.member, m.model, m.verified_at, m.enabled, today));
+    const bad = rows.filter((r) => r.verdict === 'stale' || r.verdict === 'future-date' || r.verdict === 'malformed');
+    const unstamped = rows.filter((r) => r.verdict === 'unstamped');
+
+    for (const r of rows) {
+        const age = r.age_days === null ? '—' : `${r.age_days}d`;
+        process.stdout.write(
+            `  ${r.verdict.padEnd(11)} ${r.member.padEnd(12)} ${r.model.padEnd(20)} ${age}${r.enabled ? '' : '  (disabled)'}\n`,
+        );
+    }
+    // Assert the scope and publish the count in one call: a dead scan scope is a
+    // usage error, never a pass, and "0 stale pins" over 0 members read is the
+    // failure this separates. reportScanned emits the number the assertion just
+    // accepted, so the published count cannot drift from the validated one.
+    reportScanned({
+        gate: 'check_council_pin_staleness',
+        scanned: rows.length,
+        units: 'council member(s) with a model:',
+        roots: [file],
+    });
+    if (bad.length > 0) {
+        process.stdout.write(
+            `❌  ${bad.length} pin(s) need attention (cadence ${CADENCE_DAYS}d). A stamp records when a human last\n` +
+                `    checked the pin against the provider's own surface — refresh the pin or the date, and prefer a\n` +
+                `    vendor sentinel where one exists: a sentinel cannot go stale, so it never needs a stamp.\n`,
+        );
+        return 1;
+    }
+    if (unstamped.length > 0) {
+        process.stdout.write(
+            `⚠️  ${unstamped.length} dated pin(s) carry no verified_at — advisory. Add a stamp, or move the member to a\n` +
+                `    vendor sentinel and it drops out of this gate entirely.\n`,
+        );
+    }
+    process.stdout.write('✅  council model pins within cadence.\n');
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_council_pin_staleness')) {
+    try {
+        process.exit(main(process.argv.slice(2)));
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(2);
+        }
+        throw err;
+    }
+}