@event4u/agent-config 9.15.0 → 9.16.0

package/dist/ui/index.html

@@ -27,7 +27,7 @@
                 document.documentElement.setAttribute('data-theme', theme);
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-DJY_vQVn.js"></script>
+      <script type="module" crossorigin src="/assets/index-DmR0mbk4.js"></script>
       <link rel="stylesheet" crossorigin href="/assets/index-jSfMW8_t.css">
     </head>
     <body>

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.15.0",
+    "version": "9.16.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,
@@ -110,11 +110,11 @@
         "@fastify/static": "^10.1.2",
         "@modelcontextprotocol/sdk": "^1.30.0",
         "@preact/signals": "^2.10.0",
-        "commander": "^12.1.0",
+        "commander": "^15.0.0",
         "execa": "^9.5.0",
         "fastify": "^5.11.0",
-        "js-yaml": "^4.1.0",
-        "open": "^10.2.0",
+        "js-yaml": "^5.2.0",
+        "open": "^11.0.0",
         "preact": "^10.29.0",
         "yaml": "^2.9.0",
         "zod": "^3.25.0",

package/src/config/agent-settings.template.yml

@@ -724,7 +724,9 @@ subagents:
   # the resource-availability gate (council 2026-08-03).
   #   ask  = (default) first budget-motivated downshift of a session asks once
   #   auto = apply the relation silently (telemetry line per routed request)
-  #   off  = today's behavior; single-flip rollback
+  #   off  = today's behavior; single-flip rollback — QUOTE it ("off") when
+  #          editing: bare off is YAML-1.1 boolean false (readers coerce, but
+  #          the quoted form is the unambiguous one, same as `auto: "on"`)
   budget_routing: ask
 
   # Prefer a separate-quota-pool model for delegable sub-tasks WHERE the host

package/src/config/budget-routing.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "Single source of truth for the budget-routing reserve lifecycle (docs/contracts/budget-routing.md). Read by BOTH reserve readers — src/scripts/_lib/tier_budget_routing.ts (acquireBudgetPermit) and src/scripts/cost/budget.mjs (tier subcommand) — so the reserve window can never diverge between them. reserve_ttl_ms: reserves are RACE PROTECTION, not spend accounting — a pending entry older than this is dead and is dropped at the next compaction. lock_break_ms: an .lock file older than this is a crash leftover and is broken (unlink + one retry).",
+  "owner": "maintainer",
+  "review_by": "2027-08-03",
+  "reserve_ttl_ms": 600000,
+  "lock_break_ms": 30000
+}

package/src/scripts/_lib/tier_budget_routing.ts

@@ -20,6 +20,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 export type BudgetTier = 'cheap' | 'medium' | 'strong';
 
@@ -123,19 +124,91 @@ export const RESERVE_FILE = 'tier-reserves.jsonl';
 export const COOLDOWN_FILE = 'tier-cooldowns.json';
 export const DEFAULT_COOLDOWN_MS = 60 * 60 * 1000;
 
+// Reserve lifecycle constants — single source of truth shared with
+// budget.mjs (the second reserve reader) via src/config/budget-routing.json.
+// Duplicating the literal here was the exact two-truths defect the external
+// review flagged; both readers now load the same file.
+const _LIFECYCLE_CONFIG = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '..',
+    '..',
+    'config',
+    'budget-routing.json',
+);
+
+function _lifecycle(): { reserve_ttl_ms: number; lock_break_ms: number } {
+    try {
+        const raw = JSON.parse(fs.readFileSync(_LIFECYCLE_CONFIG, 'utf-8')) as Record<string, unknown>;
+        const ttl = typeof raw['reserve_ttl_ms'] === 'number' ? raw['reserve_ttl_ms'] : 600_000;
+        const brk = typeof raw['lock_break_ms'] === 'number' ? raw['lock_break_ms'] : 30_000;
+        return { reserve_ttl_ms: ttl, lock_break_ms: brk };
+    } catch {
+        return { reserve_ttl_ms: 600_000, lock_break_ms: 30_000 };
+    }
+}
+
+export function reserveTtlMs(): number {
+    return _lifecycle().reserve_ttl_ms;
+}
+
 interface ReserveEntry {
     ts_ms: number;
     tier: BudgetTier;
     est_usd: number;
-    status: 'pending';
+    status: 'pending' | 'settled';
+}
+
+function _readReserves(reservePath: string): ReserveEntry[] {
+    if (!fs.existsSync(reservePath)) {
+        return [];
+    }
+    const out: ReserveEntry[] = [];
+    for (const line of fs.readFileSync(reservePath, 'utf-8').split('\n')) {
+        if (!line.trim()) continue;
+        try {
+            out.push(JSON.parse(line) as ReserveEntry);
+        } catch {
+            // tolerate a torn line — reserve file is advisory spend state
+        }
+    }
+    return out;
+}
+
+/** Take the reserve lock; break a stale one (crash leftover) once. */
+function _takeLock(lock: string, now_ms: number, lock_break_ms: number): number | null {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            return fs.openSync(lock, 'wx');
+        } catch {
+            try {
+                const age = now_ms - fs.statSync(lock).mtimeMs;
+                if (age > lock_break_ms) {
+                    fs.rmSync(lock, { force: true });
+                    continue; // one retry after breaking the stale lock
+                }
+            } catch {
+                continue; // lock vanished between open and stat — retry once
+            }
+            return null;
+        }
+    }
+    return null;
 }
 
 /**
- * Atomic budget reserve: O_EXCL lock → sum ledger+reserves → append a
- * pending entry → release. Returns granted=false (never throws) when the
- * ceiling would be crossed or the lock cannot be taken quickly — the
- * caller falls back per the relation (fail-open at the DECISION layer,
- * conservative at the SPEND layer).
+ * Atomic budget reserve — full lifecycle (external review 2026-08-03):
+ *
+ *   acquire → expire (TTL) / settle → compact-on-write
+ *
+ * Under the lock: live reserves = pending entries younger than the shared
+ * TTL (reserves are RACE PROTECTION, not spend accounting — real spend is
+ * the ledger's job); the file is COMPACTED to exactly those live entries
+ * on every acquire, so it stays bounded; a lock file older than
+ * `lock_break_ms` is a crash leftover and is broken with one retry.
+ * Returns granted=false (never throws) when the ceiling would be crossed
+ * or a fresh lock is genuinely held — the caller falls back per the
+ * relation (fail-open at the DECISION layer, conservative at the SPEND
+ * layer).
  */
 export function acquireBudgetPermit(options: {
     tracking_dir: string;
@@ -148,44 +221,45 @@ export function acquireBudgetPermit(options: {
     const dir = options.tracking_dir;
     fs.mkdirSync(dir, { recursive: true });
     const lock = path.join(dir, `${RESERVE_FILE}.lock`);
-    let fd: number;
-    try {
-        fd = fs.openSync(lock, 'wx');
-    } catch {
+    const { reserve_ttl_ms, lock_break_ms } = _lifecycle();
+    const fd = _takeLock(lock, options.now_ms, lock_break_ms);
+    if (fd === null) {
         return { granted: false, reason: 'reserve lock busy — treat tier as unavailable this instant' };
     }
     try {
         const reservePath = path.join(dir, RESERVE_FILE);
-        let reserved = 0;
-        if (fs.existsSync(reservePath)) {
-            for (const line of fs.readFileSync(reservePath, 'utf-8').split('\n')) {
-                if (!line.trim()) continue;
-                try {
-                    const e = JSON.parse(line) as ReserveEntry;
-                    if (e.tier === options.tier && e.status === 'pending') {
-                        reserved += e.est_usd;
-                    }
-                } catch {
-                    // tolerate a torn line — reserve file is advisory spend state
-                }
-            }
-        }
+        const live = _readReserves(reservePath).filter(
+            (e) => e.status === 'pending' && options.now_ms - e.ts_ms < reserve_ttl_ms,
+        );
+        const reserved = live
+            .filter((e) => e.tier === options.tier)
+            .reduce((acc, e) => acc + e.est_usd, 0);
         if (
             options.ceiling_usd !== null &&
             options.spent_usd + reserved + options.estimated_cost_usd > options.ceiling_usd
         ) {
+            // Compact even on deny — expiry must not depend on a grant.
+            fs.writeFileSync(
+                reservePath,
+                live.map((e) => JSON.stringify(e)).join('\n') + (live.length ? '\n' : ''),
+                'utf-8',
+            );
             return {
                 granted: false,
                 reason: `ceiling ${options.ceiling_usd} would be crossed (spent ${options.spent_usd} + reserved ${reserved})`,
             };
         }
-        const entry: ReserveEntry = {
+        live.push({
             ts_ms: options.now_ms,
             tier: options.tier,
             est_usd: options.estimated_cost_usd,
             status: 'pending',
-        };
-        fs.appendFileSync(reservePath, `${JSON.stringify(entry)}\n`, 'utf-8');
+        });
+        fs.writeFileSync(
+            reservePath,
+            live.map((e) => JSON.stringify(e)).join('\n') + '\n',
+            'utf-8',
+        );
         return { granted: true, reason: 'reserved' };
     } finally {
         fs.closeSync(fd);
@@ -193,7 +267,54 @@ export function acquireBudgetPermit(options: {
     }
 }
 
-/** Record a quota/429 error: the tier cools down; pickTier skips it. */
+/**
+ * Settle the oldest live pending reserve of a tier (call when the real
+ * cost lands in the ledger, so the estimate stops counting immediately
+ * instead of waiting out the TTL). Settled entries are dropped by the
+ * next compaction. Best-effort: lock busy → no-op (the TTL is the
+ * backstop that makes settling optional, never load-bearing).
+ */
+export function settlePermit(options: {
+    tracking_dir: string;
+    tier: BudgetTier;
+    now_ms: number;
+}): boolean {
+    const lock = path.join(options.tracking_dir, `${RESERVE_FILE}.lock`);
+    const { reserve_ttl_ms, lock_break_ms } = _lifecycle();
+    const fd = _takeLock(lock, options.now_ms, lock_break_ms);
+    if (fd === null) {
+        return false;
+    }
+    try {
+        const reservePath = path.join(options.tracking_dir, RESERVE_FILE);
+        const live = _readReserves(reservePath).filter(
+            (e) => e.status === 'pending' && options.now_ms - e.ts_ms < reserve_ttl_ms,
+        );
+        const idx = live.findIndex((e) => e.tier === options.tier);
+        if (idx === -1) {
+            return false;
+        }
+        live.splice(idx, 1);
+        fs.writeFileSync(
+            reservePath,
+            live.map((e) => JSON.stringify(e)).join('\n') + (live.length ? '\n' : ''),
+            'utf-8',
+        );
+        return true;
+    } finally {
+        fs.closeSync(fd);
+        fs.rmSync(lock, { force: true });
+    }
+}
+
+/**
+ * Record a quota/429 error: the tier cools down; pickTier skips it.
+ *
+ * Deliberately lock-free: last-writer-wins on a 3-key timestamp map is
+ * benign (two concurrent trips write near-identical "until" values), so
+ * the reserve lock is not reused here (accepted in the 2026-08-03 review).
+ * Expired entries are purged on every write so the map never grows stale.
+ */
 export function tripCooldown(options: {
     tracking_dir: string;
     tier: BudgetTier;
@@ -208,6 +329,11 @@ export function tripCooldown(options: {
     } catch {
         state = {};
     }
+    for (const [k, v] of Object.entries(state)) {
+        if (typeof v !== 'number' || v <= options.now_ms) {
+            delete state[k];
+        }
+    }
     state[options.tier] = until;
     fs.mkdirSync(options.tracking_dir, { recursive: true });
     fs.writeFileSync(p, `${JSON.stringify(state, null, 2)}\n`, 'utf-8');

package/src/scripts/anchor_scoring_run.ts

@@ -22,7 +22,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 import { build_thin, RULES_SOURCE } from './project_thin_rules.js';
 import { cohensKappa } from './check_quality_regression.js';

package/src/scripts/bench_persona_placebo.ts

@@ -29,7 +29,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 import { signTestP } from './second_brain_retrieval.js';
 

package/src/scripts/bench_quality_run.ts

@@ -30,7 +30,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 import { build_thin, RULES_SOURCE } from './project_thin_rules.js';
 import { evaluatePair, type JudgeFn, type JudgeVerdict, type PairResult } from './check_quality_regression.js';

package/src/scripts/check_cli_registry_budget_sync.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env tsx
+/**
+ * CLI-registry ↔ evaluator-budget sync gate.
+ *
+ * The evaluator budget `cli_help_command_count` (src/config/evaluator-budgets.json)
+ * and the committed measurement record (agents/evidence/metrics/
+ * evaluator-measurements.json) are derived from `src/cli/registry.ts`, but until
+ * this gate nothing forced the PR that changes the registry to move them: the
+ * breach only WARNED on main and BLOCKED the next release. That is how 9.15.0
+ * went red — f02db54c2 registered `routing:doctor` (80 → 81 entries) and the
+ * drift surfaced days later, at release time, on an unrelated branch.
+ *
+ * This gate runs on every PR (Static Checks + `task preflight`) and fails the
+ * moment the three numbers disagree, so the registering PR carries the budget
+ * move itself.
+ *
+ * The count uses the SAME pinned method as evaluator_umbrella.sh — the number
+ * of `{ name: ` entry openers in src/cli/registry.ts (NOT --help prose
+ * parsing; methods historically disagreed 74 vs 76 vs 79).
+ *
+ * Exit codes: 0 in sync · 1 out of sync · 2 a required file is missing or
+ * unparseable (fail-closed: a gate that cannot read its inputs must not
+ * certify them).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const REGISTRY_PATH = path.join(REPO_ROOT, 'src/cli/registry.ts');
+const BUDGETS_PATH = path.join(REPO_ROOT, 'src/config/evaluator-budgets.json');
+const RECORD_PATH = path.join(REPO_ROOT, 'agents/evidence/metrics/evaluator-measurements.json');
+
+const METRIC = 'cli_help_command_count';
+
+/** Pinned method — byte-for-byte the umbrella's CLI_COUNT probe. */
+function count_registry_entries(source: string): number {
+    return (source.match(/\{ name: /g) || []).length;
+}
+
+interface BudgetEntry {
+    max?: unknown;
+    last_measured?: unknown;
+}
+
+interface SyncInputs {
+    count: number;
+    budget: BudgetEntry | undefined;
+    recorded: unknown;
+}
+
+const REMEDY =
+    'Fix, in THIS PR (the one that moves src/cli/registry.ts):\n' +
+    `  1. src/config/evaluator-budgets.json → budgets.${METRIC}: set max +\n` +
+    '     last_measured to the new count, bump last_measured_at, and extend\n' +
+    '     baseline_note naming the commit that moves the surface.\n' +
+    '  2. Regenerate the committed record (never hand-edit):\n' +
+    '       node src/scripts/record_evaluator_measurements.mjs \\\n' +
+    '         --measurements <file with the re-measured metrics> \\\n' +
+    '         --out agents/evidence/metrics/evaluator-measurements.json \\\n' +
+    '         --sha "$(git rev-parse HEAD)"\n' +
+    'Otherwise the drift stays invisible until the next release, where the\n' +
+    'evaluator gate blocks it (the 9.15.0 failure mode this gate exists to stop).\n';
+
+/** Pure comparison — the CLI owns the filesystem. */
+function collect_findings(inputs: SyncInputs): string[] {
+    const findings: string[] = [];
+    const { count, budget, recorded } = inputs;
+
+    if (budget === undefined) {
+        findings.push(`budgets.${METRIC} is missing from evaluator-budgets.json`);
+        return findings;
+    }
+    if (budget.last_measured !== count) {
+        findings.push(
+            `registry has ${count} entries but budgets.${METRIC}.last_measured says ` +
+                `${String(budget.last_measured)}`,
+        );
+    }
+    if (typeof budget.max !== 'number' || count > budget.max) {
+        findings.push(
+            `registry has ${count} entries but budgets.${METRIC}.max is ` +
+                `${String(budget.max)}`,
+        );
+    }
+    if (recorded === undefined) {
+        findings.push(
+            `measurements.${METRIC} is missing from the committed record ` +
+                '(agents/evidence/metrics/evaluator-measurements.json)',
+        );
+    } else if (recorded !== count) {
+        findings.push(
+            `registry has ${count} entries but the committed record says ` +
+                `${String(recorded)}`,
+        );
+    }
+    return findings;
+}
+
+function _read_json(p: string): Record<string, unknown> {
+    return JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
+}
+
+function main(): number {
+    let registrySource: string;
+    let budgetsDoc: Record<string, unknown>;
+    let recordDoc: Record<string, unknown>;
+    try {
+        registrySource = fs.readFileSync(REGISTRY_PATH, 'utf-8');
+        budgetsDoc = _read_json(BUDGETS_PATH);
+        recordDoc = _read_json(RECORD_PATH);
+    } catch (err) {
+        process.stderr.write(
+            `ERROR: cannot read a gate input: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+        return 2;
+    }
+
+    const count = count_registry_entries(registrySource);
+    const budgets = budgetsDoc['budgets'] as Record<string, BudgetEntry> | undefined;
+    const measurements = recordDoc['measurements'] as Record<string, unknown> | undefined;
+    const findings = collect_findings({
+        count,
+        budget: budgets?.[METRIC],
+        recorded: measurements?.[METRIC],
+    });
+
+    process.stdout.write('scanned: 3\n');
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(`❌  ${METRIC} out of sync: ${f}\n`);
+        }
+        process.stdout.write('\n' + REMEDY);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  ${METRIC} in sync — registry (${count}) == budget == committed record.\n`,
+    );
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    // Symlinked invocations (installed projections, macOS /var → /private/var)
+    // make the raw URLs differ — compare realpaths so the entry guard fires.
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argvPath = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argvPath;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { collect_findings, count_registry_entries, main };

package/src/scripts/check_gate_coverage.ts

@@ -48,7 +48,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { runCountedProbe } from './_lib/counted_probe.js';
 
 const _HERE = fileURLToPath(import.meta.url);

package/src/scripts/check_token_quality_golden.ts

@@ -41,7 +41,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');

package/src/scripts/cost/budget.mjs

@@ -199,9 +199,21 @@ function cmdCheck() {
 }
 
 // --- Per-tier budget state (docs/contracts/budget-routing.md) -------------
-// v1 window for per-tier ceilings: rolling 24h. Sums ledger entries tagged
-// `tier:` plus pending reserves from tier-reserves.jsonl (the atomic-permit
-// file) so a concurrent dispatch cannot read a stale "available".
+// v1 window for per-tier ceilings: rolling 24h for SPEND (ledger entries
+// tagged `tier:`). Pending reserves from tier-reserves.jsonl count only
+// within the shared reserve TTL — reserves are race protection, not spend
+// accounting. The TTL comes from src/config/budget-routing.json, the SAME
+// source acquireBudgetPermit reads, so the two readers cannot diverge
+// (external review 2026-08-03, Finding 1b).
+
+function loadReserveTtlMs() {
+  try {
+    const cfgPath = join(dirname(new URL(import.meta.url).pathname), '..', '..', 'config', 'budget-routing.json');
+    const raw = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+    if (Number.isFinite(raw.reserve_ttl_ms)) return raw.reserve_ttl_ms;
+  } catch { /* fall through to the safe default below */ }
+  return 600000;
+}
 
 function loadPerTierCeilings() {
   const out = { cheap: null, medium: null, strong: null };
@@ -234,13 +246,14 @@ function cmdTier(rest) {
     .filter((s) => s.tier === tier && inWindow(s.capturedAt || s.endedAt || s.ts))
     .reduce((acc, s) => acc + (Number(s.total_cost_usd ?? s.cost_usd ?? 0) || 0), 0);
   let reserved = 0;
+  const reserveTtl = loadReserveTtlMs();
   const reservePath = join(dirname(STORE), 'tier-reserves.jsonl');
   if (existsSync(reservePath)) {
     for (const line of readFileSync(reservePath, 'utf-8').split('\n')) {
       if (!line.trim()) continue;
       try {
         const e = JSON.parse(line);
-        if (e.tier === tier && e.status === 'pending' && (now - e.ts_ms) < dayMs) {
+        if (e.tier === tier && e.status === 'pending' && (now - e.ts_ms) < reserveTtl) {
           reserved += Number(e.est_usd || 0) || 0;
         }
       } catch { /* skip malformed line */ }
@@ -251,6 +264,7 @@ function cmdTier(rest) {
   console.log(JSON.stringify({
     tier,
     window: 'rolling-24h',
+    reserve_ttl_ms: reserveTtl,
     ceiling_usd: ceiling,
     spent_usd: spent,
     reserved_usd: reserved,