@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/cost/backfill_rates.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// cost-backfill — re-price ledger rows that `track.mjs` flagged `rate_missing`,
+// using a rate table supplied for the model ids that had none at capture time.
+//
+// Why this exists: `track.mjs` prices an unrecognised model at $0 rather than
+// throwing, because losing a whole session of real token counts over one
+// unknown id is worse than an understated total. It keeps the token counts and
+// sets `rate_missing` precisely so the cost can be repaired later. This is that
+// repair pass.
+//
+// BUILT AGAINST AN OBSERVED ROW, NOT A GUESSED ONE. The shape below was read
+// off a real flagged row produced from this repo's own transcripts on
+// 2026-08-16 (`claude-fable-5`, 468 messages, 236,695,963 cache-read tokens,
+// cost 0). Two limits are properties of that observed shape, and both are
+// stated rather than papered over — a re-priced row that looks exact while
+// resting on an invented split would be worse than the zero it replaces:
+//
+//   1. THE CACHE-WRITE TTL SPLIT IS NOT RETAINED ON THE ROW. `track.mjs`
+//      prices `ephemeral_5m` and `ephemeral_1h` cache writes at different
+//      rates (1.25x / 2x of input), but `byModel[m]` aggregates both into one
+//      `cache_creation_input_tokens` tally. A backfill therefore prices every
+//      cache write at the 5m rate — Anthropic's default TTL, and the same
+//      fallback `costForUsage` already applies to any unaccounted remainder.
+//      A session that really used 1h writes is under-priced by the difference.
+//      Recorded per row as `cache_ttl_assumed: "5m"`.
+//
+//   2. `byBucket[*].cost_usd` IS NOT REPAIRED. The row records per-bucket
+//      totals and per-model totals, but not per-bucket-per-model tokens, so
+//      the recovered cost cannot be attributed across main vs subagent. The
+//      alternative is not a better number but an invented one — the same
+//      honest-limit stance `cost-summary-schema` takes for `by_date`. The
+//      bucket figures stay as captured and the report says so.
+//
+// Rates file (JSON), either form per model id:
+//   { "claude-fable-5": "opus" }                       // reuse a known tier's rates
+//   { "claude-fable-5": { "input": 5, "output": 25,    // explicit USD per 1M
+//                         "cache_write_5m": 6.25, "cache_read": 0.5 } }
+// Every rate must be a finite number >= 0, and an all-zero table is refused.
+// `cache_write_1h` is accepted but unused — see RATE_KEYS.
+//
+// Usage: node src/scripts/cost/backfill_rates.mjs --rates <file.json>
+//                                                 [--store <ledger.jsonl>] [--apply]
+// Env:
+//   BACKFILL_STORE=<path>   ledger to re-price (default: agents/cost-tracking/sessions.jsonl)
+//   BACKFILL_RATES=<path>   rates file (same as --rates)
+//   BACKFILL_APPLY=1        write the result (same as --apply); default is a dry run
+//   BACKFILL_QUIET=1        suppress the report; exit code and writes are unchanged
+
+import { readFileSync, writeFileSync, renameSync, existsSync } from 'node:fs';
+
+const DEFAULT_STORE = 'agents/cost-tracking/sessions.jsonl';
+
+// Mirrored from track.mjs PRICING. It is a copy rather than an import for the
+// reason that file's own header gives: track.mjs exports nothing and calls
+// main() at module scope, so importing it would scan the developer's real
+// ~/.claude as a side effect. Keep the two in step.
+const PRICING = {
+  haiku: { input: 0.25, output: 1.25, cache_write_5m: 0.30, cache_write_1h: 0.50, cache_read: 0.03 },
+  sonnet: { input: 3.00, output: 15.00, cache_write_5m: 3.75, cache_write_1h: 6.00, cache_read: 0.30 },
+  opus: { input: 15.00, output: 75.00, cache_write_5m: 18.75, cache_write_1h: 30.00, cache_read: 1.50 },
+};
+
+// The keys `costForModelEntry` actually reads. `cache_write_1h` is deliberately
+// NOT here: the row does not retain the TTL split (honest limit 1), so a 1h
+// rate cannot affect any output, and requiring a number that provably changes
+// nothing is a usability wart rather than a safeguard. It is accepted when
+// present — a tier alias carries one — and ignored. A future 1h-aware pass
+// would need the producer to keep the split first, at which point this list is
+// where the key goes back.
+const RATE_KEYS = ['input', 'output', 'cache_write_5m', 'cache_read'];
+
+/**
+ * A usable rate is finite and non-negative.
+ * `typeof x === 'number'` is NOT enough, and the gap is not theoretical: JSON
+ * parses `1e999` to `Infinity`, which prices to `null` in the written row;
+ * a negative rate writes a negative total. Both then clear `rate_missing`,
+ * which is worse than the silent zero 2.4 removed — the row now carries a
+ * confident wrong figure with its own warning switched off, and the token
+ * counts that made a re-price possible have already been overwritten.
+ */
+function isUsableRate(v) {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+
+/**
+ * Resolve one rates-file entry to `{ tier, rates }`.
+ * A string is a tier alias; an object is an explicit table. Anything else, a
+ * table missing a key, an unusable value, or an all-zero table is rejected by
+ * name — a silently-defaulted rate would reintroduce the understatement this
+ * pass exists to remove.
+ */
+function resolveRate(model, spec) {
+  if (typeof spec === 'string') {
+    const rates = PRICING[spec];
+    if (!rates) throw new Error(`rates["${model}"]: unknown tier alias "${spec}" (known: ${Object.keys(PRICING).join(', ')})`);
+    return { tier: spec, rates };
+  }
+  if (spec && typeof spec === 'object') {
+    const missing = RATE_KEYS.filter((k) => spec[k] === undefined);
+    if (missing.length) throw new Error(`rates["${model}"]: missing ${missing.join(', ')}`);
+    const unusable = RATE_KEYS.filter((k) => !isUsableRate(spec[k]));
+    if (unusable.length) throw new Error(`rates["${model}"]: ${unusable.map((k) => `${k}=${JSON.stringify(spec[k])}`).join(', ')} — a rate must be a finite number >= 0`);
+    // An all-zero table is not a price, it is the absence of one, and no tier
+    // in PRICING is free. Accepting it would re-create the exact case the flag
+    // exists to distinguish: a $0 row that reads as cheap work.
+    if (RATE_KEYS.every((k) => spec[k] === 0)) throw new Error(`rates["${model}"]: an all-zero table is not a price — it re-creates the $0 row rate_missing exists to flag`);
+    return { tier: 'backfilled', rates: spec };
+  }
+  throw new Error(`rates["${model}"]: expected a tier alias or a rate table, got ${typeof spec}`);
+}
+
+/**
+ * Cost for one `byModel` entry at the supplied rates.
+ * Cache writes price at the 5m rate — see honest limit 1 in the header.
+ */
+function costForModelEntry(entry, rates) {
+  return (entry.input_tokens || 0) / 1e6 * rates.input
+    + (entry.output_tokens || 0) / 1e6 * rates.output
+    + (entry.cache_creation_input_tokens || 0) / 1e6 * rates.cache_write_5m
+    + (entry.cache_read_input_tokens || 0) / 1e6 * rates.cache_read;
+}
+
+/** Mirrors track.mjs's flag condition: a row with no billable tokens costs 0 at any rate. */
+function billableTokens(entry) {
+  if (!entry) return 0;
+  return (entry.input_tokens || 0) + (entry.output_tokens || 0)
+    + (entry.cache_creation_input_tokens || 0) + (entry.cache_read_input_tokens || 0);
+}
+
+/**
+ * Re-price one row in place. Returns the per-model repairs made, or [] when
+ * the row is not flagged, carries no supplied rate, or was already backfilled
+ * for that model — which is what makes a second run a no-op rather than a
+ * double count.
+ */
+export function backfillRow(row, rateTable) {
+  if (!row || row.rate_missing !== true) return [];
+  const already = new Set((row.rate_backfill || []).map((b) => b.model));
+  const repairs = [];
+
+  for (const model of row.rate_missing_models || []) {
+    if (already.has(model)) continue;
+    const spec = rateTable[model];
+    if (!spec) continue;
+    const entry = (row.byModel || {})[model];
+    if (!entry || billableTokens(entry) <= 0) continue;
+
+    const { tier, rates } = spec;
+    const cost = costForModelEntry(entry, rates);
+    const previous = entry.cost_usd || 0;
+    const delta = cost - previous;
+
+    entry.cost_usd = cost;
+    entry.tier = tier;
+    row.byTier = row.byTier || {};
+    row.byTier[tier] = (row.byTier[tier] || 0) + delta;
+    row.total_cost_usd = (row.total_cost_usd || 0) + delta;
+
+    repairs.push({ model, tier, cost_usd: cost, delta_usd: delta });
+  }
+
+  if (!repairs.length) return [];
+
+  row.rate_backfill = [
+    ...(row.rate_backfill || []),
+    ...repairs.map((r) => ({
+      model: r.model,
+      tier: r.tier,
+      cost_usd: r.cost_usd,
+      cache_ttl_assumed: '5m',
+      bucket_split_repaired: false,
+      at: new Date().toISOString(),
+    })),
+  ];
+
+  // Whatever is still unpriced keeps the flag. A row re-priced for one model
+  // and not another is still understated, and saying otherwise is the exact
+  // silent zero 2.4 removed.
+  const remaining = (row.rate_missing_models || []).filter(
+    (m) => !row.rate_backfill.some((b) => b.model === m),
+  );
+  row.rate_missing_models = remaining;
+  row.rate_missing = remaining.length > 0;
+
+  return repairs;
+}
+
+function parseArgs(argv) {
+  const out = { rates: process.env.BACKFILL_RATES || null, store: process.env.BACKFILL_STORE || DEFAULT_STORE, apply: process.env.BACKFILL_APPLY === '1' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--apply') out.apply = true;
+    else if (a === '--rates') out.rates = argv[++i];
+    else if (a === '--store') out.store = argv[++i];
+    else if (a.startsWith('--rates=')) out.rates = a.slice('--rates='.length);
+    else if (a.startsWith('--store=')) out.store = a.slice('--store='.length);
+    else throw new Error(`unknown argument: ${a}`);
+  }
+  return out;
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    console.error(`cost-backfill: ${e.message}`);
+    process.exit(2);
+  }
+  if (!args.rates) {
+    console.error('cost-backfill: --rates <file.json> is required (or BACKFILL_RATES)');
+    process.exit(2);
+  }
+  if (!existsSync(args.rates)) {
+    console.error(`cost-backfill: rates file not found: ${args.rates}`);
+    process.exit(2);
+  }
+  if (!existsSync(args.store)) {
+    console.error(`cost-backfill: ledger not found: ${args.store}`);
+    process.exit(2);
+  }
+
+  let rateTable;
+  try {
+    const raw = JSON.parse(readFileSync(args.rates, 'utf-8'));
+    rateTable = Object.fromEntries(Object.entries(raw).map(([m, spec]) => [m, resolveRate(m, spec)]));
+  } catch (e) {
+    console.error(`cost-backfill: ${e.message}`);
+    process.exit(2);
+  }
+
+  const before = readFileSync(args.store, 'utf-8');
+  const lines = before.split('\n').filter((l) => l.trim().length > 0);
+  const rows = [];
+  const repaired = [];
+  let flaggedRows = 0;
+
+  for (const line of lines) {
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      // A malformed line is preserved verbatim rather than dropped: this pass
+      // repairs prices, it does not curate the ledger.
+      rows.push(line);
+      continue;
+    }
+    if (row.rate_missing === true) flaggedRows++;
+    const repairs = backfillRow(row, rateTable);
+    if (repairs.length) repaired.push({ sessionId: row.sessionId, repairs, stillMissing: row.rate_missing_models });
+    rows.push(JSON.stringify(row));
+  }
+
+  if (args.apply && repaired.length) {
+    // This is a read-modify-REWRITE against a store whose producer APPENDS
+    // (`track.mjs` uses appendFileSync). temp-then-rename makes the write
+    // atomic; it does not make the read-write pair safe — a `track.mjs` run
+    // landing in between would be silently discarded by the rename. There is
+    // no lock, so the honest move is to detect the collision and refuse rather
+    // than to overwrite: on an append-only cost ledger a lost row is silent
+    // data loss, and re-running the pass afterwards costs nothing.
+    if (readFileSync(args.store, 'utf-8') !== before) {
+      console.error('cost-backfill: the ledger changed while this pass was running — refusing to overwrite. Re-run it.');
+      process.exit(2);
+    }
+    const tmp = `${args.store}.backfill.tmp`;
+    writeFileSync(tmp, rows.join('\n') + '\n');
+    renameSync(tmp, args.store);
+  }
+
+  if (process.env.BACKFILL_QUIET === '1') return;
+
+  const total = repaired.reduce((s, r) => s + r.repairs.reduce((t, x) => t + x.delta_usd, 0), 0);
+  console.log(`# cost-backfill — ${args.apply ? 'APPLIED' : 'DRY RUN (pass --apply to write)'}`);
+  console.log('');
+  console.log(`Ledger: \`${args.store}\` · rows ${lines.length} · flagged ${flaggedRows} · re-priced ${repaired.length}`);
+  console.log('');
+  if (!repaired.length) {
+    console.log('No row was re-priced — either nothing is flagged, or no rate was supplied for the flagged ids.');
+  } else {
+    console.log('| Session | Model | Tier | Recovered | Still missing |');
+    console.log('|---|---|---|---:|---|');
+    for (const r of repaired) {
+      for (const x of r.repairs) {
+        console.log(`| \`${(r.sessionId || '').slice(0, 8)}\` | \`${x.model}\` | ${x.tier} | $${x.delta_usd.toFixed(6)} | ${r.stillMissing.length ? r.stillMissing.join(', ') : '—'} |`);
+      }
+    }
+    console.log('');
+    console.log(`**Recovered total: $${total.toFixed(6)}** — previously reported as $0.`);
+  }
+  console.log('');
+  console.log('Two limits of the recovered figure, both properties of the stored row:');
+  console.log('- Cache writes price at the **5m** rate; the row does not retain the 5m/1h TTL split, so a session that used 1h writes stays under-priced by the difference.');
+  console.log('- `byBucket[*].cost_usd` is **not** repaired — the row carries no per-bucket-per-model tokens, so the recovered cost cannot be attributed to main vs subagent.');
+}
+
+// Importable for tests; runs only when invoked directly, unlike track.mjs.
+if (process.argv[1] && process.argv[1].endsWith('backfill_rates.mjs')) main();

package/src/scripts/cost/budget.mjs

@@ -10,7 +10,7 @@
 // Env: BUDGET_STORE, BUDGET_CONFIG, BUDGET_PERIOD={today|week|month|all}, BUDGET_QUIET=1
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname } from 'node:path';
 
 const STORE = process.env.BUDGET_STORE || 'agents/cost-tracking/sessions.jsonl';
 const CONFIG = process.env.BUDGET_CONFIG || 'agents/cost-tracking/budget.json';
@@ -200,20 +200,16 @@ function cmdCheck() {
 
 // --- Per-tier budget state (docs/contracts/budget-routing.md) -------------
 // 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;
-}
+// tagged `tier:`).
+//
+// The pending-RESERVE half was removed 2026-08-16 with the permit lifecycle it
+// belonged to (converged council verdict, anthropic + openai 2 of 2; migration
+// record in the contract above). This reader summed `tier-reserves.jsonl`, whose
+// only writer was `acquireBudgetPermit` — a function with no production caller —
+// so `reserved_usd` was provably always 0 here, and a reader could not tell that
+// zero from "nothing is currently reserved". The shared-TTL config it loaded
+// (src/config/budget-routing.json) existed solely to keep the two reserve
+// readers in step and went with them.
 
 function loadPerTierCeilings() {
   const out = { cheap: null, medium: null, strong: null };
@@ -245,29 +241,13 @@ function cmdTier(rest) {
   const spent = loadSessions()
     .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) < reserveTtl) {
-          reserved += Number(e.est_usd || 0) || 0;
-        }
-      } catch { /* skip malformed line */ }
-    }
-  }
   const ceiling = loadPerTierCeilings()[tier];
-  const available = ceiling === null ? true : spent + reserved < ceiling;
+  const available = ceiling === null ? true : spent < ceiling;
   console.log(JSON.stringify({
     tier,
     window: 'rolling-24h',
-    reserve_ttl_ms: reserveTtl,
     ceiling_usd: ceiling,
     spent_usd: spent,
-    reserved_usd: reserved,
     available,
   }));
 }

package/src/scripts/cost_summary.ts

@@ -167,6 +167,15 @@ export function aggregate(rows: Row[]): Json {
     const by_model = new Map<string, ModelBucket>();
     const by_date = new Map<string, KvBucket>();
     const rate_missing_models = new Set<string>();
+    // Re-priced rows, counted at the totals layer only — deliberately NOT
+    // per grouping. `rate_missing_sessions` propagates into every grouping
+    // because a flagged row makes THAT grouping's total a floor. A backfilled
+    // row is the opposite: it no longer understates anything, so nothing about
+    // a slice changes. What changes is the provenance of the summary as a
+    // whole — part of it is priced at operator-supplied rates rather than
+    // measured — and that is a totals-level fact.
+    const rate_backfilled_models = new Set<string>();
+    let rate_backfilled_sessions = 0;
     const totals = _zero_kv();
 
     for (const row of rows) {
@@ -185,6 +194,16 @@ export function aggregate(rows: Row[]): Json {
         for (const id of _strList(row['rate_missing_models'])) {
             rate_missing_models.add(id);
         }
+        const backfill = row['rate_backfill'];
+        if (Array.isArray(backfill) && backfill.length > 0) {
+            rate_backfilled_sessions += 1;
+            for (const entry of backfill) {
+                if (entry && typeof entry === 'object') {
+                    const id = _str((entry as Record<string, unknown>)['model'] ?? '');
+                    if (id) rate_backfilled_models.add(id);
+                }
+            }
+        }
 
         const sessBucket = _getOr(by_sess, sid, _zero_kv);
         const convBucket = _getOr(by_conv, cid, _zero_kv);
@@ -231,6 +250,12 @@ export function aggregate(rows: Row[]): Json {
             // aggregated past: a non-zero count means total_cost_usd is a floor.
             rate_missing_sessions: totals.rate_missing_sessions,
             rate_missing_models: [...rate_missing_models].sort(),
+            // The re-priced qualification. Without it, `rate_missing: false`
+            // on a repaired row and on a row that was never flagged aggregate
+            // identically, so a total carrying operator-supplied estimates
+            // reads as fully measured.
+            rate_backfilled_sessions,
+            rate_backfilled_models: [...rate_backfilled_models].sort(),
         },
         by_session: _sortedEntries(by_sess).map(([k, v]) => ({
             key: k,

package/src/scripts/dispatch_r2_reviewer.ts

@@ -222,13 +222,23 @@ export const REVIEW_SCOPE_NAME_ONLY_FLAGS: readonly string[] = [
     '-O/dev/null',
 ];
 
-/** `git diff` argv for the review scope (patch body), config-pinned. */
-export function reviewScopeDiffArgs(base: string): string[] {
+/**
+ * `git diff` argv for the review scope (patch body), config-pinned.
+ *
+ * `head` defaults to `HEAD` — the only value the dispatcher and the validator
+ * ever pass, since both bind the scope being dispatched *now*. It is a
+ * parameter so that an out-of-band measurement can re-derive the scope at a
+ * HISTORICAL revision through this same definition instead of assembling a
+ * second `git diff` argv beside it: a private copy would drift from the
+ * normative flag list above the first time a flag changes, and then report a
+ * hash no gate would ever produce.
+ */
+export function reviewScopeDiffArgs(base: string, head = 'HEAD'): string[] {
     return [
         ...REVIEW_SCOPE_GIT_CONFIG,
         'diff',
         ...REVIEW_SCOPE_DIFF_FLAGS,
-        `${base}...HEAD`,
+        `${base}...${head}`,
         '--',
         ':/',
         ...REVIEW_SCOPE_EXCLUDES,
@@ -236,12 +246,12 @@ export function reviewScopeDiffArgs(base: string): string[] {
 }
 
 /** `git diff --name-only` argv for the review scope (changed-file list), config-pinned. */
-export function reviewScopeNameOnlyArgs(base: string): string[] {
+export function reviewScopeNameOnlyArgs(base: string, head = 'HEAD'): string[] {
     return [
         ...REVIEW_SCOPE_GIT_CONFIG,
         'diff',
         ...REVIEW_SCOPE_NAME_ONLY_FLAGS,
-        `${base}...HEAD`,
+        `${base}...${head}`,
         '--',
         ':/',
         ...REVIEW_SCOPE_EXCLUDES,

package/src/scripts/evidence_report.ts

@@ -29,6 +29,8 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { workspaceIdentity } from './_lib/git_common_dir.js';
+
 // argparse `prog` is hardcoded to "evidence_report.py" in the retired Python implementation,
 // so usage strings stay byte-identical regardless of the `.py`/`.ts` filename.
 const PROG = 'evidence_report.py';
@@ -39,15 +41,24 @@ const DESCRIPTION = 'Evidence Report template automation.';
 // Repo-root resolution
 // ---------------------------------------------------------------------------
 
-/** Return repo root via git, falling back to relative-path heuristic. */
+/**
+ * Return repo root, falling back to the relative-path heuristic.
+ *
+ * Census row R4. The previous implementation spawned
+ * `git rev-parse --show-toplevel` with **no `cwd` and no env scrub**, so an
+ * inherited `GIT_DIR` (every git hook exports one) silently answered about the
+ * hook's repository instead of this one. `workspaceIdentity()` reads files, so
+ * there is no child process to redirect. The fallback is unchanged, and in a
+ * plain invocation both forms return the same path.
+ */
 function _repo_root(): string {
-    const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' });
-    if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
+    const root = workspaceIdentity().repoRoot;
+    if (!root.resolved) {
         // Script lives at src/scripts/; repo root is two levels up.
         const here = fileURLToPath(import.meta.url);
         return path.resolve(path.dirname(here), '..', '..');
     }
-    return result.stdout.trim();
+    return root.value;
 }
 
 function _git_head_short(): string {

package/src/scripts/external_sources_denylist.json

@@ -2,6 +2,7 @@
   "_README": "Denylist for check_no_external_sources.py — blocks readable inspiration/harvest/comparison source names from re-entering the tracked tree. See rule source-confidentiality + the 2026-06-13 source-confidentiality sweep. Recommending an integrated tool is allowed; recording that we copied/derived/were-inspired-by an external source is not. To intentionally retain a source link, encrypt it via src/scripts/_lib/link_crypto.py.",
   "deny": [
     "kdcllc",
+    "nidhinjs",
     "\\bmicrock\\b",
     "obra/superpowers",
     "composiohq",

package/src/scripts/hook_manifest.yaml

@@ -434,6 +434,28 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-inbox-harvest-2026-08-d-runtime-skill-routing Phase 2 — binds the
+  # deterministic task→skill ranker, which had shipped with ZERO production
+  # callers: `score_skill_relevance.rank` and its `suggest_skill_for_task`
+  # wrapper were reachable only from their CLIs and from `routing:doctor`.
+  # Ranks the SUBMITTED prompt over the installed skill catalogue and injects
+  # at most one line naming the top-3 skill ids and their scores — POINTERS,
+  # never bodies, never a load instruction. Same delivery as `delegation-nudge`
+  # above: `{decision:"warn", reason, additional_context}` at exit 2, reduced
+  # to a real exit of 0 by `host_semantics.emitFor`'s warn branch, so it never
+  # blocks a turn.
+  #
+  # Silence is the default and its floor is MEASURED, not chosen: `rank`
+  # returns something on nearly every real prompt, so the trigger is a top-1
+  # score at or above 30/100 — the p90 of the routing-matrix corpus (496 prompt
+  # lines; median 18, p75 28, max 70), firing on 13.9% of them. A median floor
+  # would speak on half of all turns, which is the per-turn-reminder shape this
+  # estate has already measured failing. fail_closed: false.
+  skill-route:
+    script: src/scripts/hooks/skill_route_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   # road-to-orchestrator-discipline-carriers Phase 5 (F4-lite) — end-review
   # nudge. Fires ONLY when the session mutated tracked+untracked, non-doc
   # files beyond MUTATION_LINE_THRESHOLD (50 lines; untracked files added
@@ -556,6 +578,30 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-inbox-harvest-2026-08-d-context-ledger Phase 1 Step 1.1 — the
+  # tool-result byte counter. `hook-token-budget.json` registers the gap it
+  # closes in its own words: bytes-into-context from tool RESULTS are
+  # instrumented nowhere, so every context-cost claim in this tree is made
+  # against a denominator missing its dominant term.
+  #
+  # CAPTURE ONLY. It appends `{ts, tool, bytes, measurable}` to a gitignored
+  # census file and emits NOTHING to the model — zero injection bytes, which
+  # is why it carries a metric registration rather than a per-concern byte
+  # cap. The threshold question (when is a result too large) is deliberately
+  # unanswered: the distribution has never been observed, and the house rule
+  # is baseline before mechanism.
+  #
+  # The record type has four fields and none can hold free text — a tool
+  # NAME, a byte COUNT, a timestamp and a measurable flag. Tool results
+  # routinely carry file contents and command output; none of it can reach
+  # this output because the output has no field able to carry it.
+  #
+  # Never blocks, never warns: exit 0 on every path. fail_closed: false.
+  tool-result-bytes:
+    script: src/scripts/hooks/tool_result_bytes_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   # road-to-subagent-lifecycle-integrity Phase 3 Step 1 — spawn guard, SHADOW
   # ONLY, per docs/contracts/concern-activation-policy.md. On every Agent/Task
   # call it appends one `spawn_guard_shadow` line recording what a guard WOULD
@@ -615,7 +661,11 @@ roles:
     # Orchestrator-only concerns (Phase 2.3): a worker never talks to the
     # user, never dispatches sub-workers, never runs the council, and its
     # complaints route via the orchestrator.
-    drop: [delegation-nudge, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol]
+    # `skill-route` joins the drop list for the same reason `delegation-nudge`
+    # is on it: a worker was handed a bounded slice by an orchestrator that
+    # already chose the approach, so a routing pointer there advises nobody who
+    # can act on it and costs the dispatch anyway.
+    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol]
 
 platforms:
   augment:
@@ -623,22 +673,32 @@ platforms:
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   claude:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, git-authorization, session-canary, self-repair, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape, language-mirror]
-    # round-5 § 6.1 — the ONLY binding on this slot in the tree. `pre_compact`
-    # sets a pin-lost marker; the `post_tool_use` entry above re-emits the pin
-    # exactly once while that marker is set, then clears it. One extra
-    # injection per compaction EVENT — never one per tool call, which is the
-    # shape § 6.2 refuses. claude only: it is the sole verified platform, and
-    # the measured compaction defect is a Claude Code transcript fact.
-    pre_compact:      [language-mirror]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape, language-mirror]
+    # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
+    # the `post_tool_use` entry above re-emits the pin exactly once while that
+    # marker is set, then clears it. One extra injection per compaction EVENT —
+    # never one per tool call, which is the shape § 6.2 refuses. claude only: it
+    # is the sole verified platform, and the measured compaction defect is a
+    # Claude Code transcript fact. (It was the ONLY binding on this slot until
+    # the entry below; that sentence is retired rather than left to rot.)
+    #
+    # `hot-context` — road-to-inbox-harvest-2026-08-d-context-ledger Step 2.1.
+    # This is the one slot that fires WHILE state is being destroyed, and it
+    # carried no WRITER at all: the cache a post-compaction `session_start`
+    # restores was written at the last `stop`, so everything the session did
+    # between that stop and the compaction was lost with it. The concern is
+    # already bound on `stop` and `session_start`; this adds the write at the
+    # moment the loss actually happens. Deterministic rebuild, emits nothing
+    # here — the 4,096-byte row it carries is for its session_start restore.
+    pre_compact:      [language-mirror, hot-context]
     # road-to-subagent-lifecycle-integrity Phase 1 Step 1. `claude` is the only
     # platform where both native events were measured present on the installed
     # binary (2.1.229 — see the evidence page cited on the alias rows below).
@@ -675,7 +735,7 @@ platforms:
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges
     # depend on stdout reaching the model, which this trampoline discards by
@@ -698,7 +758,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
   # (project, no file extension, must be executable per Cline docs) or
@@ -713,7 +773,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
   # (project) or `~/.codeium/windsurf/hooks.json` (user). Cascade has
@@ -749,7 +809,7 @@ platforms:
     session_end:        [chat-history, memory-learn, session-register]
     stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, edit-shape]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   # Phase 7.9 — Copilot has no hook surface. Concerns route through
   # rule-only fallback; the dispatcher silently no-ops on --platform copilot.