@ijfw/memory-server 1.4.3 → 1.5.0

package/src/fs-lock.js

@@ -11,15 +11,37 @@
  * (single retry after rm).
  *
  * Closes SEC-H-01 (cross-process race) from v1.4.3 cross-audit round 1.
+ *
+ * v1.5.0 T3 — heartbeat-refreshed locks. The fixed-30s stale window wrongly
+ * reclaimed locks held by *live* long-running verbs. `withFsLock` now accepts
+ * a `heartbeatMs` option: while `fn` runs, the holder refreshes `holder.json`
+ * (and the lock dir mtime) on that interval, so a concurrent caller's stale
+ * check sees a *recent* `acquired_at` and keeps waiting. A genuinely dead
+ * holder stops refreshing → its lock still ages past `staleMs` and becomes
+ * reclaimable. The heartbeat interval is always cleared on release (success
+ * or throw), so a leaked timer can never touch a recreated lock dir.
+ *
+ * v1.5.0 T3 also exports `canonicalLockOrder` — the STATE-SDK-CONTRACT §3
+ * lock-hierarchy sort. It is the single source of truth for the coarse-to-fine
+ * acquire-order so the state-SDK's `_withLocks` cannot deadlock.
  */
 
-import { mkdir, writeFile, readFile, rm, stat } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import {
+  mkdir, writeFile, readFile, rm, stat, utimes,
+} from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
 
 const DEFAULT_ACQUIRE_TIMEOUT_MS = 5000;
 const DEFAULT_STALE_MS = 30000;
 const BACKOFF_START_MS = 25;
 const BACKOFF_MAX_MS = 250;
+/**
+ * Default heartbeat interval. The refresh cadence must be comfortably shorter
+ * than any `staleMs` a caller picks, so a live holder always renews the lock
+ * before a concurrent caller's stale check fires. Callers needing a smaller
+ * `staleMs` (the state-SDK uses ~10s) pass an explicit `heartbeatMs`.
+ */
+const DEFAULT_HEARTBEAT_MS = 5000;
 
 export class FsLockBusyError extends Error {
   constructor(lockPath, timeoutMs) {
@@ -88,9 +110,40 @@ async function tryAcquireOnce(lockPath) {
 }
 
 /**
- * withFsLock(lockPath, fn, { staleMs, acquireTimeoutMs })
+ * Refresh a held lock's freshness anchor. Rewrites `holder.json` with a fresh
+ * `acquired_at` and bumps the lock directory's own mtime — both are anchors the
+ * stale check consults, so refreshing both keeps the holder.json path AND the
+ * R12-M-01 mtime-fallback path in agreement. Best-effort: a transient failure
+ * (e.g. the dir is mid-release) is swallowed; the next tick retries.
+ */
+async function refreshHolder(lockPath, holder) {
+  const now = Date.now();
+  holder.acquired_at = now;
+  try {
+    await writeFile(
+      join(lockPath, 'holder.json'),
+      JSON.stringify(holder),
+      'utf8',
+    );
+  } catch {
+    // Lock dir may be mid-release. Harmless — next tick retries, or the
+    // interval is about to be cleared.
+  }
+  try {
+    const d = new Date(now);
+    await utimes(lockPath, d, d);
+  } catch {
+    // Same rationale as above.
+  }
+}
+
+/**
+ * withFsLock(lockPath, fn, { staleMs, acquireTimeoutMs, heartbeatMs })
  *
- * See module docstring for contract details.
+ * See module docstring for contract details. `heartbeatMs` (v1.5.0 T3): while
+ * `fn` runs, refresh the lock's freshness anchor on this interval so a live
+ * long-running holder is never wrongly reclaimed as stale. Pass `0` to disable
+ * the heartbeat (legacy fixed-window behaviour). Default: 5000ms.
  */
 export async function withFsLock(lockPath, fn, opts = {}) {
   const staleMs =
@@ -99,6 +152,10 @@ export async function withFsLock(lockPath, fn, opts = {}) {
     typeof opts.acquireTimeoutMs === 'number'
       ? opts.acquireTimeoutMs
       : DEFAULT_ACQUIRE_TIMEOUT_MS;
+  const heartbeatMs =
+    typeof opts.heartbeatMs === 'number'
+      ? opts.heartbeatMs
+      : DEFAULT_HEARTBEAT_MS;
 
   // Ensure the lock's parent directory exists. `tryAcquireOnce` uses
   // `mkdir(lockPath, { recursive: false })` which fails with ENOENT when any
@@ -119,12 +176,16 @@ export async function withFsLock(lockPath, fn, opts = {}) {
   let staleRecoveryUsed = false;
   let backoff = BACKOFF_START_MS;
 
+  // The holder object for THIS acquisition — the heartbeat refreshes it in
+  // place so its `acquired_at` stays current while `fn` runs.
+  let heldHolder = null;
+
   // Acquire loop. We try mkdir; if EEXIST, decide between waiting and stale
   // recovery; otherwise propagate the error.
   // eslint-disable-next-line no-constant-condition
   while (true) {
     try {
-      await tryAcquireOnce(lockPath);
+      heldHolder = await tryAcquireOnce(lockPath);
       break;
     } catch (err) {
       if (err && err.code !== 'EEXIST') {
@@ -161,7 +222,7 @@ export async function withFsLock(lockPath, fn, opts = {}) {
           throw new FsLockStaleError(lockPath, rmErr);
         }
         try {
-          await tryAcquireOnce(lockPath);
+          heldHolder = await tryAcquireOnce(lockPath);
           break;
         } catch (retryErr) {
           if (retryErr && retryErr.code === 'EEXIST') {
@@ -184,13 +245,33 @@ export async function withFsLock(lockPath, fn, opts = {}) {
     }
   }
 
-  // Lock acquired — run fn and ALWAYS release.
+  // Lock acquired — start the heartbeat, run fn, and ALWAYS clear + release.
+  //
+  // The heartbeat keeps a *live* long-running holder's lock fresh so a
+  // concurrent caller never wrongly stale-reclaims it. The interval is cleared
+  // in the `finally` before the lock dir is removed, so a leaked timer can
+  // never touch a recreated lock dir. `unref()` ensures the interval cannot
+  // keep the process alive on its own.
+  let heartbeat = null;
+  if (heartbeatMs > 0 && heldHolder) {
+    heartbeat = setInterval(() => {
+      // Fire-and-forget — refreshHolder swallows its own transient errors.
+      refreshHolder(lockPath, heldHolder);
+    }, heartbeatMs);
+    if (typeof heartbeat.unref === 'function') heartbeat.unref();
+  }
+
   let fnResult;
   let fnError;
   try {
     fnResult = await fn();
   } catch (err) {
     fnError = err;
+  } finally {
+    if (heartbeat) {
+      clearInterval(heartbeat);
+      heartbeat = null;
+    }
   }
 
   try {
@@ -203,3 +284,174 @@ export async function withFsLock(lockPath, fn, opts = {}) {
   if (fnError !== undefined) throw fnError;
   return fnResult;
 }
+
+// ===========================================================================
+// v1.5.0 T3 — STATE-SDK-CONTRACT §3 canonical lock-hierarchy ordering.
+//
+// `canonicalLockOrder(targets)` sorts an arbitrary set of physical state-file
+// paths into the exact coarse-to-fine acquire-order from §3 of
+// `.planning/v150-gap-closure/STATE-SDK-CONTRACT.md`. A verb touching N files
+// acquires its locks in this order and releases in reverse — because the order
+// is total and deterministic, no two verbs can form a lock-ordering cycle, so
+// the state-SDK is deadlock-free by construction.
+//
+// This lives in fs-lock.js (not state-sdk.js) so the ordering rule sits next
+// to the lock primitive it governs — one module owns "how locks behave".
+// ===========================================================================
+
+/**
+ * §3 tier table. Each entry: a tier number (1-based, the §3 list position) and
+ * a `match(path)` predicate. The FIRST matching entry wins, so more-specific
+ * patterns are listed where ambiguity could arise (none currently overlap).
+ *
+ * `sub(path)` extracts the same-tier discriminator (`waveId` / `subId`) so
+ * multiple files at one tier sort deterministically by their natural ascending
+ * order — §3 "sub-orders them by the natural ascending sort of the
+ * discriminator". `null` when a tier has no discriminator.
+ */
+const LOCK_TIERS = [
+  // #1 — intent journal (always first)
+  { tier: 1, match: (p) => /[\\/]\.ijfw[\\/]state[\\/]intent-journal\.jsonl$/.test(p) },
+  // #2 — workflow phase state
+  { tier: 2, match: (p) => /[\\/]\.ijfw[\\/]state[\\/]workflow\.json$/.test(p) },
+  // #3 — wave index
+  { tier: 3, match: (p) => /[\\/]\.ijfw[\\/]state[\\/]waves\.json$/.test(p) },
+  // #4 — per-wave STATE.md (sub-ordered by waveId)
+  {
+    tier: 4,
+    match: (p) => /[\\/]\.ijfw[\\/]wave-[^\\/]+[\\/]STATE\.md$/.test(p),
+    sub: (p) => {
+      const m = /[\\/]\.ijfw[\\/]wave-([^\\/]+)[\\/]STATE\.md$/.exec(p);
+      return m ? m[1] : null;
+    },
+  },
+  // #5 — per-subagent checkpoint (sub-ordered by subId, then waveId)
+  {
+    tier: 5,
+    match: (p) => /[\\/]\.ijfw[\\/]wave-[^\\/]+[\\/]subagent-[^\\/]+\.checkpoint\.json$/.test(p),
+    sub: (p) => {
+      const m = /[\\/]\.ijfw[\\/]wave-([^\\/]+)[\\/]subagent-([^\\/]+)\.checkpoint\.json$/.exec(p);
+      // Discriminator: "<subId> <waveId>" — subId is the primary key per
+      // §3, waveId breaks ties when one verb touches the same subId in two
+      // waves (no current verb does, but the order stays total).
+      return m ? `${m[2]} ${m[1]}` : null;
+    },
+  },
+  // #6 — generated roster
+  { tier: 6, match: (p) => /[\\/]\.ijfw[\\/]team[\\/]workflow\.json$/.test(p) },
+  // #7 — decision / blocker append log
+  { tier: 7, match: (p) => /[\\/]\.ijfw[\\/]blackboard[\\/]decisions\.jsonl$/.test(p) },
+  // #8 — AGENTS.md blackboard rollup
+  { tier: 8, match: (p) => /(^|[\\/])AGENTS\.md$/.test(p) },
+  // #9 — Trident convergence telemetry
+  { tier: 9, match: (p) => /[\\/]\.ijfw[\\/]telemetry[\\/]convergence\.json$/.test(p) },
+  // #10 — per-subagent event log (sub-ordered by subId, then waveId)
+  {
+    tier: 10,
+    match: (p) => /[\\/]\.ijfw[\\/]wave-[^\\/]+[\\/]events-[^\\/]+\.jsonl$/.test(p),
+    sub: (p) => {
+      const m = /[\\/]\.ijfw[\\/]wave-([^\\/]+)[\\/]events-([^\\/]+)\.jsonl$/.exec(p);
+      return m ? `${m[2]} ${m[1]}` : null;
+    },
+  },
+  // #11 — homedir active-extension state (always last — different fs root)
+  { tier: 11, match: (p) => /[\\/]\.ijfw[\\/]state[\\/]active-extension\.json$/.test(p) },
+];
+
+/**
+ * Natural ascending comparison for same-tier discriminators: numeric runs
+ * compare numerically (so `W2 < W10`), non-numeric runs compare
+ * lexicographically. Makes `wave-W1, wave-W2, wave-W10` sort in human order.
+ */
+function naturalCompare(a, b) {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  const ra = String(a).match(/\d+|\D+/g) || [];
+  const rb = String(b).match(/\d+|\D+/g) || [];
+  const n = Math.min(ra.length, rb.length);
+  for (let i = 0; i < n; i += 1) {
+    const sa = ra[i];
+    const sb = rb[i];
+    const na = /^\d+$/.test(sa);
+    const nb = /^\d+$/.test(sb);
+    if (na && nb) {
+      const d = Number(sa) - Number(sb);
+      if (d !== 0) return d < 0 ? -1 : 1;
+    } else if (sa !== sb) {
+      return sa < sb ? -1 : 1;
+    }
+  }
+  if (ra.length !== rb.length) return ra.length < rb.length ? -1 : 1;
+  return 0;
+}
+
+/** Classify one path -> its §3 tier descriptor. Unknown paths land at tier 99. */
+function classify(path) {
+  for (const t of LOCK_TIERS) {
+    if (t.match(path)) {
+      return { tier: t.tier, sub: t.sub ? t.sub(path) : null };
+    }
+  }
+  // An unknown path is acquired AFTER every known tier — still deterministic
+  // (sorts by path string), so a future/typo path can never wedge the order.
+  return { tier: 99, sub: null };
+}
+
+/**
+ * canonicalLockOrder(targets) — return `targets` sorted into the §3 canonical
+ * coarse-to-fine acquire-order, de-duplicated. The total order is:
+ *
+ *   1. tier number ascending (§3 list position #1 … #11)
+ *   2. within a tier, the natural ascending sort of the discriminator
+ *      (`waveId` / `subId`) — §3 same-tier sub-ordering
+ *   3. final tie-break on the full path string (keeps the order total even
+ *      for paths a tier cannot otherwise distinguish)
+ *
+ * Pure + idempotent: `canonicalLockOrder(canonicalLockOrder(x))` deep-equals
+ * `canonicalLockOrder(x)`. Callers are NOT trusted to pre-sort — the state-SDK
+ * always routes its lock-target list through here (defense in depth).
+ *
+ * @param {string[]} targets  physical state-file paths (any order, may repeat)
+ * @returns {string[]}  the §3-ordered, de-duplicated path list
+ */
+export function canonicalLockOrder(targets) {
+  if (!Array.isArray(targets)) {
+    throw new TypeError('canonicalLockOrder: targets must be a string[]');
+  }
+  const seen = new Set();
+  const decorated = [];
+  for (const path of targets) {
+    if (typeof path !== 'string' || path.length === 0) {
+      throw new TypeError(
+        `canonicalLockOrder: every target must be a non-empty string (got ${JSON.stringify(path)})`,
+      );
+    }
+    if (seen.has(path)) continue;
+    seen.add(path);
+    decorated.push({ path, ...classify(path) });
+  }
+  decorated.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    const s = naturalCompare(a.sub, b.sub);
+    if (s !== 0) return s;
+    if (a.path === b.path) return 0;
+    return a.path < b.path ? -1 : 1;
+  });
+  return decorated.map((d) => d.path);
+}
+
+/**
+ * lockPathFor(targetPath) — the dotfile-sibling lock path for a target, per
+ * STATE-SDK-CONTRACT §1 ("Lock files are the dotfile sibling of each target",
+ * e.g. `.ijfw/state/workflow.json` -> `.ijfw/state/.workflow.json.lock`).
+ *
+ * @param {string} targetPath  a physical state file path
+ * @returns {string}  the lock directory path to pass to `withFsLock`
+ */
+export function lockPathFor(targetPath) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0) {
+    throw new TypeError('lockPathFor: targetPath must be a non-empty string');
+  }
+  return join(dirname(targetPath), `.${basename(targetPath)}.lock`);
+}

package/src/gate-result.js

@@ -14,7 +14,7 @@
  *   - Receipt writes MUST NOT throw — the gate's hot path is the priority.
  */
 
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, writeFile, readdir, stat, unlink, appendFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 
 import {
@@ -155,6 +155,18 @@ export async function makeReceipt(gateResult, opts = {}) {
     await mkdir(dirname(receiptPath), { recursive: true });
     const body = JSON.stringify(gateResult, null, 2) + '\n';
     await writeFile(receiptPath, body, 'utf8');
+
+    // v1.5.0 audit MED #9 (memory-engine.md F-PRF-2): bounded LRU on the
+    // gate-receipts dir. Without eviction this directory grew unbounded
+    // (one file per gate run forever); on long-lived projects this hit
+    // hundreds of MB and slowed the memory-feedback scan in
+    // ijfw_memory_prelude. We keep the newest N=1000 *.json files and
+    // append the rest to .archive.jsonl (one JSON line per old receipt),
+    // then unlink the originals. Atomic-ish: we write the archive line
+    // before unlinking so a crash mid-eviction leaves the data preserved
+    // in the archive *and* the receipt -- worst case is a single dup
+    // entry in .archive.jsonl, never data loss.
+    await evictOldReceipts(dirname(receiptPath));
   } catch (err) {
     // Fire-and-forget: log and move on. The gate hot path must not fail.
     const msg = err && err.message ? err.message : String(err);
@@ -174,6 +186,88 @@ export async function makeReceipt(gateResult, opts = {}) {
 // filesystem call.
 const RECEIPT_GATE_ID_PATTERN = /^[a-z][a-z0-9-]+$/;
 
+// v1.5.0 audit MED #9 -- bounded LRU constants. Pulled out so tests can
+// dial the cap down to keep the test fixtures cheap.
+export const RECEIPTS_KEEP = 1000;
+export const RECEIPTS_ARCHIVE = '.archive.jsonl';
+
+/**
+ * evictOldReceipts(dir, opts) -- bounded LRU on the gate-receipts directory.
+ *
+ * Keeps the newest `keep` *.json files; older files are appended to
+ * `.archive.jsonl` as JSONL and then unlinked. Never throws -- the gate's
+ * hot path is the priority and a logging-channel directory should not
+ * propagate I/O errors into the gate result.
+ *
+ * @param {string} dir
+ * @param {{keep?: number}} [opts]
+ * @returns {Promise<{evicted: number}>}
+ */
+export async function evictOldReceipts(dir, opts = {}) {
+  const keep = Number.isFinite(opts.keep) && opts.keep > 0 ? opts.keep | 0 : RECEIPTS_KEEP;
+  try {
+    let entries;
+    try {
+      entries = await readdir(dir);
+    } catch {
+      return { evicted: 0 };
+    }
+    const jsonFiles = entries.filter((f) => f.endsWith('.json'));
+    if (jsonFiles.length <= keep) return { evicted: 0 };
+
+    // Stat each candidate; sort by mtime descending (newest first).
+    const stamped = [];
+    for (const f of jsonFiles) {
+      const full = join(dir, f);
+      try {
+        const s = await stat(full);
+        stamped.push({ full, name: f, mtimeMs: s.mtimeMs });
+      } catch {
+        // Cannot stat -- treat as oldest so it gets evicted/cleaned up.
+        stamped.push({ full, name: f, mtimeMs: 0 });
+      }
+    }
+    stamped.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const toEvict = stamped.slice(keep);
+    if (toEvict.length === 0) return { evicted: 0 };
+
+    const archivePath = join(dir, RECEIPTS_ARCHIVE);
+    let evicted = 0;
+    for (const victim of toEvict) {
+      try {
+        // Read + append to archive *before* unlinking so a mid-eviction crash
+        // leaves the receipt either intact OR in the archive (never lost).
+        let body;
+        try {
+          const { readFile } = await import('node:fs/promises');
+          body = await readFile(victim.full, 'utf8');
+        } catch {
+          // Already gone -- skip without inflating the evicted counter.
+          continue;
+        }
+        // Normalize: archive entries are one JSON object per line. The
+        // receipt body is pretty-printed JSON -- collapse via parse/stringify.
+        let archiveLine;
+        try {
+          archiveLine = JSON.stringify(JSON.parse(body)) + '\n';
+        } catch {
+          // Malformed body -- preserve raw bytes inside a wrapper line so
+          // operators can still inspect what was there.
+          archiveLine = JSON.stringify({ raw: body, evicted_from: victim.name }) + '\n';
+        }
+        await appendFile(archivePath, archiveLine, 'utf8');
+        await unlink(victim.full);
+        evicted++;
+      } catch {
+        // Per-file failures don't abort the eviction -- next call retries.
+      }
+    }
+    return { evicted };
+  } catch {
+    return { evicted: 0 };
+  }
+}
+
 async function resolveProjectType(projectRoot) {
   try {
     const root = typeof projectRoot === 'string' && projectRoot.length > 0

package/src/hero-line.js

@@ -2,6 +2,8 @@
 // Codex U1 caveat: delta is NEVER fabricated. If real data is insufficient,
 // the delta suffix is omitted entirely.
 
+import { getPricing, getPricesTable } from './cost/pricing.js';
+
 // Format duration in whole seconds (or ms if <1000ms total).
 function fmtDuration(ms) {
   if (ms < 1000) return `${Math.round(ms)}ms`;
@@ -29,8 +31,85 @@ function countFindings(f) {
   return { total: consensus + contested + unique, consensus };
 }
 
-// Anthropic cache-read savings rate: full input $3/M, cache-read $0.30/M -> $2.70/M saved.
-const CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+// Anthropic cache-read savings rate FALLBACK (Sonnet): full input $3/M,
+// cache-read $0.30/M -> $2.70/M saved. Used when a receipt has no model id
+// (or its model is unknown). Per-receipt rates come from cost/pricing.js so
+// Opus/Haiku users see the correct dollar figure.
+const SONNET_FALLBACK_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+
+// Known-model detector: mirrors pricing.js's match-then-fuzzy-then-family
+// logic but answers a yes/no question instead of returning a price entry.
+// We need this because getPricing() silently falls back to Sonnet for unknown
+// ids, so we cannot tell "Opus matched" from "garbage -> Sonnet fallback" by
+// looking at the returned rate alone.
+function isKnownModel(modelId) {
+  if (!modelId || typeof modelId !== 'string') return false;
+  let table;
+  try {
+    table = getPricesTable()?.models || {};
+  } catch {
+    return false;
+  }
+  const id = modelId.toLowerCase().trim();
+  if (table[id] || table[modelId]) return true;
+  for (const key of Object.keys(table)) {
+    const k = key.toLowerCase();
+    if (k.startsWith(id) || id.startsWith(k)) return true;
+  }
+  // Family prefixes (must mirror pricing.js fallbacks table).
+  const familyPrefixes = [
+    'claude-opus-4', 'claude-sonnet-4', 'claude-haiku-4',
+    'claude-3-5-sonnet', 'claude-3-5-haiku', 'claude-3-opus',
+    'gpt-5', 'gpt-4o', 'o3', 'o4', 'gemini-2', 'gemini-1.5',
+  ];
+  for (const prefix of familyPrefixes) {
+    if (id.includes(prefix)) return true;
+  }
+  return false;
+}
+
+// Compute per-token cache-read savings for a given model id by consulting
+// the vendored pricing table. Returns { perToken, isFallback, model }.
+// Falls back to Sonnet rate when the model is missing/unknown.
+function cacheSavingsForModel(modelId) {
+  if (!modelId || typeof modelId !== 'string') {
+    return { perToken: SONNET_FALLBACK_SAVINGS_PER_TOKEN, isFallback: true, model: modelId || null };
+  }
+  if (!isKnownModel(modelId)) {
+    return { perToken: SONNET_FALLBACK_SAVINGS_PER_TOKEN, isFallback: true, model: modelId };
+  }
+  try {
+    const p = getPricing(modelId);
+    const perToken = Math.max(0, (p?.in || 0) - (p?.cache_read || 0));
+    if (perToken > 0) {
+      return { perToken, isFallback: false, model: modelId };
+    }
+    return { perToken: SONNET_FALLBACK_SAVINGS_PER_TOKEN, isFallback: true, model: modelId };
+  } catch {
+    return { perToken: SONNET_FALLBACK_SAVINGS_PER_TOKEN, isFallback: true, model: modelId };
+  }
+}
+
+// One-time-per-session stderr advisory for unknown-model fallbacks.
+// Reset only by reloading the module, which matches "per session" semantics
+// for the CLI entrypoint and MCP server.
+let _unknownModelWarned = false;
+export function _resetUnknownModelWarningForTests() {
+  _unknownModelWarned = false;
+}
+function warnUnknownModelOnce(modelId) {
+  if (_unknownModelWarned) return;
+  _unknownModelWarned = true;
+  try {
+    const label = modelId ? `"${modelId}"` : '(missing)';
+    process.stderr.write(
+      `[ijfw hero-line] unknown model ${label} on receipt -- falling back to Sonnet cache-savings rate. ` +
+      `Set receipt.model to a known id for accurate dollar figures.\n`
+    );
+  } catch {
+    // stderr write failures are non-fatal.
+  }
+}
 
 // renderHeroLine(receipts, sessions?)
 //   receipts -- array of cross-runs.jsonl records
@@ -53,7 +132,7 @@ export function renderHeroLine(receipts, sessions = []) {
   let totalConsensus = 0;
   let receiptsInputTokens = 0;
   let hasReceiptsTokens = true;
-  let totalCacheReadTokens = 0;
+  let totalCacheSavings = 0; // dollars, computed per-receipt using its model
 
   for (const r of receipts) {
     if (Array.isArray(r.auditors)) {
@@ -72,7 +151,9 @@ export function renderHeroLine(receipts, sessions = []) {
     }
     const crt = r.cache_stats?.cache_read_input_tokens;
     if (typeof crt === 'number' && crt > 0) {
-      totalCacheReadTokens += crt;
+      const { perToken, isFallback } = cacheSavingsForModel(r.model);
+      if (isFallback) warnUnknownModelOnce(r.model);
+      totalCacheSavings += crt * perToken;
     }
   }
 
@@ -81,7 +162,7 @@ export function renderHeroLine(receipts, sessions = []) {
 
   // Cache savings suffix (10D.4): append only when cache reads produced a
   // visible saving (>= $0.01). A sub-cent figure reads as anti-value.
-  const rawSaved = totalCacheReadTokens * CACHE_SAVINGS_PER_TOKEN;
+  const rawSaved = totalCacheSavings;
   const cacheSuffix = rawSaved >= 0.01
     ? ` (prompt cache hit -- ~$${rawSaved.toFixed(2)} saved)`
     : '';

package/src/intent-router.js

@@ -179,6 +179,41 @@ function adaptProjectScaleNudge(prompt) {
   return `This sounds like a project. Want me to ${verb} with you? I'll ask a few questions, do some research, and come back with recommendations.`;
 }
 
+/**
+ * detectIntent — deterministic keyword → skill router.
+ *
+ * Resolution order (v1.5.0 audit-LOW-work-L6, documented for op-clarity):
+ *
+ *   1. **Priority (DESC).** Each intent entry declares a numeric `priority`.
+ *      Higher numbers beat lower numbers. Reserved bands:
+ *        - 10 : cross-* analytic intents (cross-research / cross-critique /
+ *               cross-audit). These are explicit operator commands and should
+ *               override any prose-pattern match.
+ *        - 8  : brainstorm (primary workflow entry point).
+ *        - 7  : project-scale (length-based fallback for brainstorm).
+ *        - 5  : ship / review / remember / recall / handoff / mode (default
+ *               band for everyday skills).
+ *        - 1  : critique (broad-pattern; intentionally lowest so it never
+ *               steals a more specific intent).
+ *      Adding a new intent? Pick the band, don't invent a new one.
+ *
+ *   2. **Match length (DESC).** If two intents tie on priority, the one
+ *      whose regex matched a longer substring wins. Rationale: longer match
+ *      = more specific signal. (Skills that use `check()` instead of regex
+ *      patterns report matchLen=0 and lose this tiebreak by design — their
+ *      `check()` already encodes the specificity.)
+ *
+ *   3. **Declaration order (ASC).** Final stable tiebreak: the intent listed
+ *      earlier in the INTENTS array wins. This makes the resolution fully
+ *      deterministic — no Map/Set ordering surprises across Node versions.
+ *
+ * Bypass: a prompt with a leading `*` or containing `ijfw off` returns null
+ * without entering the resolver. This is the documented escape hatch for
+ * users who want to suppress all routing for one prompt.
+ *
+ * @param {string} prompt
+ * @returns {{intent: string, skill: string, nudge: string} | null}
+ */
 export function detectIntent(prompt) {
   if (typeof prompt !== 'string' || !prompt) return null;
   // Skip if user explicitly bypasses (leading * or `ijfw off`).