@event4u/agent-config 9.15.0 → 9.17.0

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_condensation.ts

@@ -14,7 +14,8 @@
  * - All headings from source present in condensed
  * - All code blocks preserved exactly
  * - YAML frontmatter identical
- * - Word count reduction within healthy range (10-60%)
+ * - Word count: excessive-reduction alarm only (> 60% lost warns; expected
+ *   reduction is 0% post-ADR-201 verbatim copy — see the note near the check)
  * - Iron Law sections (## Iron Law / ### Iron Law / ## The Iron Law /
  *   Iron Laws / numbered) preserved per `preservation-guard`: heading
  *   verbatim at original level, structural-unit survival.