@event4u/agent-config 8.7.0 → 8.9.0

package/src/scripts/_lib/orchestration_record.ts

@@ -0,0 +1,170 @@
+/**
+ * Orchestration telemetry record builder (pure, no-I/O).
+ *
+ * Builds ONE validated audit-log-v1 line carrying an `orchestration`
+ * sub-object, from the counts the orchestrating agent already has after an
+ * auto-dispatch. This is the agent-behavioral capture path decided 2026-06-30
+ * (maintainer decision: no hook/daemon — the agent writes directly), made
+ * reliable + one-command here instead of hand-authored JSON.
+ *
+ * Contracts:
+ * - `docs/contracts/audit-log-v1.md` (the envelope)
+ * - `src/agent-src/contexts/execution/orchestration-telemetry.md` (the object)
+ *
+ * PRIVACY BY CONSTRUCTION: every field is a count, enum, or id — there is NO
+ * field capable of holding free-form content, prompt text, or a body. Do not
+ * add one. (Mirrors `domain-safety-pii` § Surface 2 / artifact-engagement.)
+ */
+
+export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
+export type VerifyMode = 'deterministic' | 'judge' | 'none';
+export type Provenance = 'measured' | 'estimated';
+export type TierChosen = 'lite' | 'medium' | 'high';
+export type TierSource = 'static' | 'inferred' | 'inherit';
+export type Band = 'low' | 'medium' | 'high';
+export type LinePhase = 'refine' | 'memory' | 'analyze' | 'plan' | 'implement' | 'test' | 'verify' | 'report';
+export type LineOutcome = 'success' | 'blocked' | 'skipped' | 'error';
+
+/** Inputs the agent supplies about one auto-dispatch. */
+export interface RecordInput {
+    // Orchestration object
+    spawn_count: number;
+    token_delta: number;
+    // Optionals accept explicit `undefined` (CLI parsing yields it); the
+    // builder defaults every one. Compatible with exactOptionalPropertyTypes.
+    token_delta_provenance?: Provenance | undefined;
+    tiers?: string[] | undefined;
+    tier_chosen?: TierChosen | null | undefined;
+    tier_source?: TierSource | null | undefined;
+    task_class?: string | null | undefined;
+    task_size_estimate?: number | undefined;
+    wall_clock_ms?: number | undefined;
+    /** Absolute measured tokens the dispatched slice consumed (feeds the modeled cost-%). */
+    dispatch_tokens?: number | null | undefined;
+    /** The orchestrator's own tier — the baseline the downshift cost-% measures against. */
+    session_tier?: string | null | undefined;
+    dispatch_outcome?: DispatchOutcome | undefined;
+    verify_mode?: VerifyMode | undefined;
+    // Audit-log envelope (sensible defaults for a dispatch record)
+    phase?: LinePhase | undefined;
+    outcome?: LineOutcome | undefined;
+    confidence_band?: Band | undefined;
+    risk_class?: Band | undefined;
+    persona?: string | null | undefined;
+    work_id?: string | undefined;
+    /** ISO-8601 UTC timestamp; caller supplies (keeps this fn pure/deterministic). */
+    ts: string;
+    /** Stable id (ULID or content hash); caller supplies. */
+    id: string;
+}
+
+export interface BuiltLine {
+    line: Record<string, unknown> | null;
+    errors: string[];
+}
+
+const DISPATCH_OUTCOMES: readonly DispatchOutcome[] = ['DONE', 'DONE_WITH_CONCERNS', 'NEEDS_CONTEXT', 'BLOCKED', 'killed'];
+const VERIFY_MODES: readonly VerifyMode[] = ['deterministic', 'judge', 'none'];
+const PROVENANCES: readonly Provenance[] = ['measured', 'estimated'];
+const TIERS_CHOSEN: readonly TierChosen[] = ['lite', 'medium', 'high'];
+const TIER_SOURCES: readonly TierSource[] = ['static', 'inferred', 'inherit'];
+const BANDS: readonly Band[] = ['low', 'medium', 'high'];
+const PHASES: readonly LinePhase[] = ['refine', 'memory', 'analyze', 'plan', 'implement', 'test', 'verify', 'report'];
+
+/** Map a dispatch outcome to the audit-log envelope outcome enum. */
+function envelopeOutcome(d: DispatchOutcome): LineOutcome {
+    if (d === 'BLOCKED') return 'blocked';
+    if (d === 'NEEDS_CONTEXT') return 'skipped';
+    if (d === 'killed') return 'error';
+    return 'success'; // DONE / DONE_WITH_CONCERNS
+}
+
+function isInt(n: unknown): n is number {
+    return typeof n === 'number' && Number.isFinite(n) && Number.isInteger(n);
+}
+
+/**
+ * Build + validate the audit-log-v1 line. Returns `{line, errors}`; when
+ * `errors` is non-empty, `line` is null and the caller must NOT write.
+ */
+export function buildOrchestrationLine(input: RecordInput): BuiltLine {
+    const errors: string[] = [];
+
+    if (!isInt(input.spawn_count) || input.spawn_count < 1) {
+        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record)');
+    }
+    if (!isInt(input.token_delta)) errors.push('token_delta must be an integer (negative = net saved vs the in-session baseline)');
+    if (input.task_size_estimate !== undefined && (!isInt(input.task_size_estimate) || input.task_size_estimate < 0)) {
+        errors.push('task_size_estimate must be a non-negative integer');
+    }
+    if (input.wall_clock_ms !== undefined && (!isInt(input.wall_clock_ms) || input.wall_clock_ms < 0)) {
+        errors.push('wall_clock_ms must be a non-negative integer');
+    }
+    if (input.dispatch_tokens != null && (!isInt(input.dispatch_tokens) || input.dispatch_tokens < 0)) {
+        errors.push('dispatch_tokens must be a non-negative integer (absolute tokens the dispatched slice consumed)');
+    }
+
+    const prov: Provenance = input.token_delta_provenance ?? 'estimated';
+    if (!PROVENANCES.includes(prov)) errors.push(`token_delta_provenance must be one of ${PROVENANCES.join(' | ')}`);
+
+    const dOutcome: DispatchOutcome = input.dispatch_outcome ?? 'DONE';
+    if (!DISPATCH_OUTCOMES.includes(dOutcome)) errors.push(`dispatch_outcome must be one of ${DISPATCH_OUTCOMES.join(' | ')}`);
+
+    const vMode: VerifyMode = input.verify_mode ?? 'deterministic';
+    if (!VERIFY_MODES.includes(vMode)) errors.push(`verify_mode must be one of ${VERIFY_MODES.join(' | ')}`);
+
+    if (input.tier_chosen != null && !TIERS_CHOSEN.includes(input.tier_chosen)) {
+        errors.push(`tier_chosen must be one of ${TIERS_CHOSEN.join(' | ')} (or omitted)`);
+    }
+    if (input.tier_source != null && !TIER_SOURCES.includes(input.tier_source)) {
+        errors.push(`tier_source must be one of ${TIER_SOURCES.join(' | ')} (or omitted)`);
+    }
+
+    const band = input.confidence_band ?? 'medium';
+    if (!BANDS.includes(band)) errors.push(`confidence_band must be one of ${BANDS.join(' | ')}`);
+    const risk = input.risk_class ?? 'low';
+    if (!BANDS.includes(risk)) errors.push(`risk_class must be one of ${BANDS.join(' | ')}`);
+    const phase = input.phase ?? 'implement';
+    if (!PHASES.includes(phase)) errors.push(`phase must be one of ${PHASES.join(' | ')}`);
+
+    if (!input.ts) errors.push('ts (ISO-8601 UTC) is required');
+    if (!input.id) errors.push('id (ULID or content hash) is required');
+
+    if (errors.length) return { line: null, errors };
+
+    const orchestration: Record<string, unknown> = {
+        task_size_estimate: input.task_size_estimate ?? 0,
+        spawn_count: input.spawn_count,
+        tiers: input.tiers ?? [],
+        token_delta: input.token_delta,
+        token_delta_provenance: prov,
+        wall_clock_ms: input.wall_clock_ms ?? 0,
+        outcome: dOutcome,
+        verify_mode: vMode,
+        task_class: input.task_class ?? null,
+        tier_chosen: input.tier_chosen ?? null,
+        tier_source: input.tier_source ?? null,
+        dispatch_tokens: input.dispatch_tokens ?? null,
+        session_tier: input.session_tier ?? null,
+    };
+
+    const line: Record<string, unknown> = {
+        schema_version: 1,
+        id: input.id,
+        ts: input.ts,
+        work_id: input.work_id ?? `orchestration-${input.ts}`,
+        phase,
+        outcome: input.outcome ?? envelopeOutcome(dOutcome),
+        confidence_band: band,
+        risk_class: risk,
+        memory: { asks: 0, hits: 0 },
+        verify: { claims: 0, first_try_passes: 0 },
+        rules_applied: ['delegation-policy'],
+        persona: input.persona ?? null,
+        input_kind: 'orchestration',
+        type: 'phase',
+        orchestration,
+    };
+
+    return { line, errors: [] };
+}

package/src/scripts/_lib/orchestration_savings.ts

@@ -0,0 +1,180 @@
+/**
+ * Orchestration savings aggregator (pure, no-I/O).
+ *
+ * Aggregates realized orchestration telemetry into a token-savings report.
+ * Consumes the `orchestration` sub-object of audit-log-v1 JSONL lines
+ * (contract: `src/agent-src/contexts/execution/orchestration-telemetry.md`).
+ *
+ * TWO metrics, kept distinct on purpose:
+ * 1. MEASURED token counts — `token_delta` (net token-COUNT delta vs the
+ *    in-session baseline; negative = fewer tokens). Real, but blind to the
+ *    downshift RATE win: the same work on a cheaper tier uses ~the same token
+ *    COUNT, so token_delta ≈ 0 for a pure downshift even though cost dropped.
+ * 2. MODELED cost-% (`modeled_cost`) — captures exactly that downshift win via
+ *    provider-neutral tier weights + absolute `dispatch_tokens`. It is a MODEL
+ *    (weights + a same-token-count assumption), NOT a measured $ figure, and is
+ *    clearly labelled as such in the report notes.
+ */
+
+export type TokenDeltaProvenance = 'measured' | 'estimated';
+
+/**
+ * Relative, provider-NEUTRAL cost weights per model tier — a tunable ratio, not
+ * $ prices. Default reflects the ~5×/~15× cheap-vs-frontier ratios from the
+ * cost-downshift council; override per project via the report's `--weights`.
+ * Used ONLY for the modeled cost-%, never for the measured token counts.
+ */
+export type TierWeights = Record<string, number>;
+export const DEFAULT_TIER_WEIGHTS: TierWeights = { lite: 1, medium: 5, high: 15 };
+
+/** The `orchestration` sub-object shape we read (subset — additive fields only). */
+export interface OrchestrationRecord {
+    spawn_count?: number;
+    token_delta?: number;
+    token_delta_provenance?: TokenDeltaProvenance;
+    tier_chosen?: string | null;
+    task_class?: string | null;
+    outcome?: string;
+    /** Absolute measured tokens the dispatched slice consumed (for the modeled cost-%). */
+    dispatch_tokens?: number | null;
+    /** The orchestrator's own tier — the baseline the downshift is measured against. */
+    session_tier?: string | null;
+}
+
+/** A parsed audit-log-v1 line (only the fields this aggregator touches). */
+export interface AuditLine {
+    input_kind?: string;
+    orchestration?: OrchestrationRecord;
+}
+
+export interface ProvenanceStat {
+    dispatches: number;
+    /** Σ token_delta for this provenance (negative = net saved). */
+    net_token_delta: number;
+}
+
+export interface ModeledCost {
+    /** Dispatches with dispatch_tokens + session_tier + tier_chosen all weight-resolvable. */
+    covered_dispatches: number;
+    /** Σ dispatch_tokens × weight(session_tier) — same tokens costed on the baseline tier. */
+    baseline_cost_units: number;
+    /** Σ dispatch_tokens × weight(tier_chosen) — modeled cost of the downshifted run. */
+    delegated_cost_units: number;
+    /** (baseline − delegated) / baseline, 0..1; null when no covered dispatches. MODELED, not measured $. */
+    cost_reduction_pct: number | null;
+    weights: TierWeights;
+}
+
+export interface SavingsReport {
+    /** Lines carrying an orchestration object with spawn_count > 0. */
+    dispatches: number;
+    total_spawns: number;
+    /** Σ token_delta across all dispatches (negative = net saved). */
+    net_token_delta: number;
+    /** Magnitude of tokens saved (sum of negative deltas, as a positive number). */
+    tokens_saved: number;
+    /** Sum of positive deltas (orchestration that cost MORE than baseline). */
+    tokens_added: number;
+    by_provenance: { measured: ProvenanceStat; estimated: ProvenanceStat };
+    /** tier_chosen → Σ token_delta (negative = net saved on that tier). */
+    by_tier: Record<string, number>;
+    /** task_class → Σ token_delta. */
+    by_task_class: Record<string, number>;
+    /** measured dispatches / dispatches, 0..1 (0 when no dispatches). */
+    measured_share: number;
+    /** Modeled downshift cost-% (tier-weight based). Distinct from the measured token counts. */
+    modeled_cost: ModeledCost;
+    /** Honest caveats about what the number does and does not mean. */
+    notes: string[];
+}
+
+function emptyProvenance(): ProvenanceStat {
+    return { dispatches: 0, net_token_delta: 0 };
+}
+
+/**
+ * Aggregate orchestration telemetry lines into a savings report.
+ *
+ * A line counts as a dispatch only when it carries an `orchestration` object
+ * with `spawn_count > 0` (spawn_count 0 / absent = handled in-session, not a
+ * dispatch). Unknown/absent fields default safely (token_delta → 0, provenance
+ * → estimated) so a pre-extension line never throws.
+ */
+export function aggregateOrchestrationSavings(
+    lines: AuditLine[],
+    weights: TierWeights = DEFAULT_TIER_WEIGHTS,
+): SavingsReport {
+    const report: SavingsReport = {
+        dispatches: 0,
+        total_spawns: 0,
+        net_token_delta: 0,
+        tokens_saved: 0,
+        tokens_added: 0,
+        by_provenance: { measured: emptyProvenance(), estimated: emptyProvenance() },
+        by_tier: {},
+        by_task_class: {},
+        measured_share: 0,
+        modeled_cost: { covered_dispatches: 0, baseline_cost_units: 0, delegated_cost_units: 0, cost_reduction_pct: null, weights },
+        notes: [],
+    };
+
+    for (const line of lines) {
+        const o = line.orchestration;
+        if (!o) continue;
+        const spawns = o.spawn_count ?? 0;
+        if (!(spawns > 0)) continue; // in-session, not a dispatch
+
+        report.dispatches += 1;
+        report.total_spawns += spawns;
+
+        const delta = o.token_delta ?? 0;
+        report.net_token_delta += delta;
+        if (delta < 0) report.tokens_saved += -delta;
+        else report.tokens_added += delta;
+
+        // Provenance defaults to `estimated` when unstated (matches the
+        // telemetry contract: estimated is the lossy fallback).
+        const prov: TokenDeltaProvenance = o.token_delta_provenance === 'measured' ? 'measured' : 'estimated';
+        report.by_provenance[prov].dispatches += 1;
+        report.by_provenance[prov].net_token_delta += delta;
+
+        const tier = o.tier_chosen ?? 'unknown';
+        report.by_tier[tier] = (report.by_tier[tier] ?? 0) + delta;
+
+        const cls = o.task_class ?? 'unclassified';
+        report.by_task_class[cls] = (report.by_task_class[cls] ?? 0) + delta;
+
+        // Modeled cost — the downshift RATE win token_delta (counts) cannot see:
+        // the same dispatch_tokens on a cheaper tier cost less by the weight ratio.
+        const dt = o.dispatch_tokens ?? 0;
+        const wChosen = o.tier_chosen != null ? weights[o.tier_chosen] : undefined;
+        const wSession = o.session_tier != null ? weights[o.session_tier] : undefined;
+        if (dt > 0 && wChosen !== undefined && wSession !== undefined) {
+            report.modeled_cost.covered_dispatches += 1;
+            report.modeled_cost.baseline_cost_units += dt * wSession;
+            report.modeled_cost.delegated_cost_units += dt * wChosen;
+        }
+    }
+
+    report.measured_share = report.dispatches === 0 ? 0 : report.by_provenance.measured.dispatches / report.dispatches;
+
+    const mc = report.modeled_cost;
+    mc.cost_reduction_pct = mc.baseline_cost_units > 0 ? (mc.baseline_cost_units - mc.delegated_cost_units) / mc.baseline_cost_units : null;
+
+    // Honest caveats — always attached so a consumer never over-reads the number.
+    if (report.dispatches === 0) {
+        report.notes.push('No orchestration telemetry yet (0 dispatches). Data accrues as `subagents.auto: on` delegates real slices (recorded via orchestration_record).');
+    } else {
+        report.notes.push('Token counts are MEASURED but blind to the downshift rate win (same tokens on a cheaper tier ≈ same count). The MODELED cost-% below captures that axis.');
+        if (report.by_provenance.estimated.dispatches > 0) {
+            report.notes.push(`${report.by_provenance.estimated.dispatches}/${report.dispatches} dispatch(es) use ESTIMATED token_delta (chars/4, lossy). Prefer measured (host usage metadata).`);
+        }
+        if (mc.covered_dispatches > 0 && mc.cost_reduction_pct !== null) {
+            report.notes.push(`MODELED cost reduction ${(mc.cost_reduction_pct * 100).toFixed(0)}% over ${mc.covered_dispatches}/${report.dispatches} dispatch(es) that carry tier data — from provider-neutral tier weights ${JSON.stringify(mc.weights)} + a same-token-count assumption. A MODEL, NOT a measured $ figure; tune with --weights.`);
+        } else {
+            report.notes.push('MODELED cost-% unavailable: no dispatch yet carries dispatch_tokens + session_tier + tier_chosen. Record those (orchestration_record --dispatch-tokens/--session-tier/--tier-chosen) to populate it.');
+        }
+    }
+
+    return report;
+}

package/src/scripts/_lib/retrieval_sanitize.ts

@@ -0,0 +1,71 @@
+/**
+ * Sanitize floor for retrieval read-surfaces
+ * (road-to-retrieval-substrate-hardening B6).
+ *
+ * Corpus content — especially user-ingested knowledge chunks under
+ * `agents/memory/knowledge/` — flows into the agent context via `retrieve_v1`
+ * / `memory_get_v1`. An attacker (or a compromised ingested source) can embed
+ * hidden-instruction vectors (bidi controls, zero-width chars, Unicode Tag
+ * block) or control-char noise that the model may act on — the untrusted-input
+ * / lethal-trifecta injection surface. This floor strips those vectors from
+ * every string field before it is emitted, treating retrieved content as DATA.
+ *
+ * It deliberately does NOT rewrite visible text (that would corrupt legitimate
+ * rule/chunk bodies and code snippets) — the injection risk is the *invisible*
+ * layer + unbounded length; visible content is the agent's to read as data.
+ * Codepoint classes are shared with `lint_hidden_unicode` (one source of truth
+ * for what counts as a hidden-instruction vector).
+ */
+import { _classify } from '../lint_hidden_unicode.js';
+
+/** Hard per-field length cap — bounds a runaway/adversarial body. */
+export const MAX_FIELD_CHARS = 8192;
+
+/** True for a C0/C1 control char that is NOT a benign whitespace (\t, \n). */
+function _isStrippableControl(cp: number): boolean {
+    if (cp === 0x09 || cp === 0x0a) return false; // keep tab + newline
+    if (cp <= 0x1f) return true; // C0 controls (incl. CR 0x0d — normalised out)
+    if (cp === 0x7f) return true; // DEL
+    if (cp >= 0x80 && cp <= 0x9f) return true; // C1 controls
+    return false;
+}
+
+/**
+ * Strip hidden-instruction vectors (bidi / zero-width / Unicode-tag /
+ * deprecated-format, per `_classify`) and stray control chars from a string,
+ * then cap its length. Preserves all visible content + tabs/newlines.
+ */
+export function sanitize_text(s: string): string {
+    let out = '';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined) continue;
+        if (_classify(cp) !== null) continue; // hidden-instruction vector → drop
+        if (_isStrippableControl(cp)) continue; // control-char noise → drop
+        out += ch;
+    }
+    return out.length > MAX_FIELD_CHARS ? out.slice(0, MAX_FIELD_CHARS) : out;
+}
+
+/**
+ * Return a shallow copy of a retrieval entry with every string value (and
+ * one level of string-array values) sanitized. Non-string values pass through
+ * unchanged (numbers, booleans, the PyFloat marker, nested plain objects are
+ * sanitized recursively).
+ */
+export function sanitize_entry(entry: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(entry)) {
+        out[k] = _sanitize_value(v);
+    }
+    return out;
+}
+
+function _sanitize_value(v: unknown): unknown {
+    if (typeof v === 'string') return sanitize_text(v);
+    if (Array.isArray(v)) return v.map((x) => (typeof x === 'string' ? sanitize_text(x) : _sanitize_value(x)));
+    if (v && typeof v === 'object' && v.constructor === Object) {
+        return sanitize_entry(v as Record<string, unknown>);
+    }
+    return v; // numbers, booleans, null, marker classes (PyFloat/PyTimestamp) untouched
+}

package/src/scripts/_lib/security_lint.ts

@@ -52,6 +52,7 @@ export const DEFAULT_SCAN_ROOTS: readonly string[] = [
     'src/rules',
     'src/agent-src',
     'src/domains',
+    'dist/agent-src',
 ];
 
 // A path is "example/teaching" (0.25x weight) when it lives under docs/ or

package/src/scripts/_lib/stat_index.ts

@@ -0,0 +1,98 @@
+/**
+ * Stat-index — skip an expensive scan when the input tree is unchanged
+ * (road-to-retrieval-substrate-hardening B5a).
+ *
+ * The memory / knowledge / discovery scanners re-read their whole file set on
+ * every `stop` / `session_start` hook, even when nothing changed. A stat-index
+ * captures a cheap signature of the input files (size + mtime_ns) and caches
+ * the scan's result beside it; a later call with the same signature returns the
+ * cached payload without re-scanning. The cache is version-namespaced (so a
+ * tool bump invalidates cleanly, versioned-cache lint B5b) and written
+ * atomically (pid-temp + rename) so concurrent hook invocations stay
+ * idempotent (council Q3).
+ *
+ * `size + mtime_ns` is sufficient for gating rebuild decisions (the council
+ * withdrew the crypto-binding demand as a non-problem); a `--force` bypass and
+ * an explicit `clear()` cover the rare stale-mtime case (e.g. `cp -p`).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+/** A deterministic signature over a file set: `<count>:<Σsize>:<maxMtimeNs>:<hashOfPaths>`. */
+export function statSignature(files: readonly string[]): string {
+    let count = 0;
+    let totalSize = 0;
+    let maxMtimeNs = 0n;
+    const sortedPaths = [...files].sort();
+    for (const f of sortedPaths) {
+        let st: fs.Stats;
+        try {
+            st = fs.statSync(f, { bigint: true }) as unknown as fs.Stats;
+        } catch {
+            continue; // missing file → excluded from the signature
+        }
+        count += 1;
+        totalSize += Number((st as unknown as { size: bigint }).size);
+        const m = (st as unknown as { mtimeNs: bigint }).mtimeNs;
+        if (m > maxMtimeNs) maxMtimeNs = m;
+    }
+    // A stable hash of the path list so add/remove/rename shifts the signature
+    // even when count + size + mtime coincide.
+    let h = 5381;
+    for (const p of sortedPaths) {
+        for (let i = 0; i < p.length; i++) h = ((h * 33) ^ p.charCodeAt(i)) >>> 0;
+    }
+    return `${count}:${totalSize}:${maxMtimeNs.toString()}:${h.toString(16)}`;
+}
+
+interface CacheFile<T> {
+    schema_version: number;
+    signature: string;
+    payload: T;
+}
+
+/**
+ * Return the cached payload when the file-set signature is unchanged; otherwise
+ * run `compute`, persist the result under `signature`, and return it.
+ *
+ * @param cachePath  version-namespaced cache file (e.g. `…-index-v1.json`)
+ * @param files      the input file set whose stat signature gates the cache
+ * @param compute    the expensive scan, run only on a miss
+ * @param force      bypass the cache and always recompute (then persist)
+ */
+export function scanCached<T>(
+    cachePath: string,
+    files: readonly string[],
+    compute: () => T,
+    force = false,
+): T {
+    const signature = statSignature(files);
+    if (!force) {
+        try {
+            const cached = JSON.parse(fs.readFileSync(cachePath, 'utf-8')) as CacheFile<T>;
+            if (cached.signature === signature) return cached.payload;
+        } catch {
+            /* miss → recompute */
+        }
+    }
+    const payload = compute();
+    writeCacheAtomic<T>(cachePath, { schema_version: 1, signature, payload });
+    return payload;
+}
+
+function writeCacheAtomic<T>(cachePath: string, data: CacheFile<T>): void {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    const tmp = `${cachePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data));
+    fs.renameSync(tmp, cachePath);
+}
+
+/** Drop a stat-index cache file (for `--force`-style resets / tests). */
+export function clear(cachePath: string): void {
+    try {
+        fs.rmSync(cachePath);
+    } catch {
+        /* already absent */
+    }
+}

package/src/scripts/benchmark.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env tsx
+/**
+ * `agent-config benchmark` — self-measuring token-reduction report
+ * (road-to-retrieval-substrate-hardening B7a).
+ *
+ * Reports the context-token reduction of the retrieval economy against the
+ * REAL alternative: the FULL always-loaded projection (council Q4) — the
+ * honest "what the user pays if everything loads eagerly + full descriptions".
+ * NOT a synthetic full-corpus strawman (explicitly rejected).
+ *
+ * Baseline components (from the pinned internal/bench/reports/token-baseline.json):
+ *   eager_rule_load + skill_descriptions + command_descriptions + mcp_schemas
+ * Reduced: eager→thin rule projection, descriptions/schemas unchanged.
+ *
+ * Deterministic (reads the pinned baseline). Every emitted number binds to
+ * docs/CLAIMS.md with a method line (council Q4 hard condition).
+ *
+ * Usage: benchmark.ts [--baseline PATH] [--format text|json]
+ * Exit codes: 0 ok, 1 baseline missing/malformed, 2 usage error.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const PROG = 'benchmark.ts';
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const BASELINE = path.join(REPO_ROOT, 'internal', 'bench', 'reports', 'token-baseline.json');
+
+interface Metrics {
+    eager_rule_load: number;
+    thin_rule_load: number;
+    skill_descriptions: number;
+    command_descriptions: number;
+    mcp_schemas: number;
+}
+export interface BenchmarkReport {
+    baseline_full_projection: number;
+    reduced_projection: number;
+    saved: number;
+    reduction_ratio: number; // 0..1
+    method: string;
+    components: Metrics;
+}
+
+function _num(v: unknown): number {
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** Compute the reduction report from a token-baseline metrics object. */
+export function computeReport(metrics: Metrics): BenchmarkReport {
+    const shared = metrics.skill_descriptions + metrics.command_descriptions + metrics.mcp_schemas;
+    const full = metrics.eager_rule_load + shared;
+    const reduced = metrics.thin_rule_load + shared;
+    const saved = full - reduced;
+    const ratio = full > 0 ? Math.round((saved / full) * 10000) / 10000 : 0;
+    return {
+        baseline_full_projection: full,
+        reduced_projection: reduced,
+        saved,
+        reduction_ratio: ratio,
+        method:
+            'Baseline = FULL always-loaded projection (eager rule load + skill/command ' +
+            'descriptions + MCP schemas) from token-baseline.json; reduced = thin rule ' +
+            'projection, shared surfaces unchanged. Not a synthetic strawman (council Q4).',
+        components: metrics,
+    };
+}
+
+export function loadMetrics(baselinePath: string): Metrics {
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8')) as { metrics?: Record<string, unknown> };
+    const m = parsed.metrics ?? {};
+    return {
+        eager_rule_load: _num(m['eager_rule_load']),
+        thin_rule_load: _num(m['thin_rule_load']),
+        skill_descriptions: _num(m['skill_descriptions']),
+        command_descriptions: _num(m['command_descriptions']),
+        mcp_schemas: _num(m['mcp_schemas']),
+    };
+}
+
+export function main(argv: string[]): number {
+    let baselinePath = BASELINE;
+    let format: 'text' | 'json' = 'text';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--baseline') baselinePath = argv[++i] ?? baselinePath;
+        else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? 'text';
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write(`usage: ${PROG} [--baseline PATH] [--format text|json]\n`);
+            return 0;
+        } else {
+            process.stderr.write(`${PROG}: error: unknown argument ${a}\n`);
+            return 2;
+        }
+    }
+    let report: BenchmarkReport;
+    try {
+        report = computeReport(loadMetrics(baselinePath));
+    } catch (exc) {
+        process.stderr.write(`${PROG}: cannot read baseline ${baselinePath}: ${String(exc)}\n`);
+        return 1;
+    }
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return 0;
+    }
+    const pct = (report.reduction_ratio * 100).toFixed(1);
+    process.stdout.write(
+        `context token reduction (vs full always-loaded projection):\n` +
+            `  full projection   ${report.baseline_full_projection} tokens\n` +
+            `  reduced (thin)    ${report.reduced_projection} tokens\n` +
+            `  saved             ${report.saved} tokens (${pct}%)\n` +
+            `  method            ${report.method}\n`,
+    );
+    return 0;
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main(process.argv.slice(2)));
+}