sprag-cli 3.55.0 → 3.57.0

package/src/codex-parser.js

@@ -7,16 +7,45 @@ import { codexUserDir } from './agent.js';
 const count = (n) => Number.isSafeInteger(n) && n >= 0 ? n : 0;
 const emptyTotals = () => ({ input: 0, cacheRead: 0, cacheCreation: 0, ephemeral5m: 0, ephemeral1h: 0, output: 0 });
 
+/**
+ * A child spawned with fork_turns "all" writes its own session_meta first,
+ * then a copy of the parent's session_meta and history, then its own work.
+ * The copy belongs to the parent: identity comes from the first session_meta,
+ * and the copied lines are skipped so the parent's request is not counted a
+ * second time. The copy ends at the child's own thread_settings_applied, or
+ * at the first line written after the batch copy, whichever comes first.
+ */
+export function forkedCopyFilter() {
+  let ownId = null, copyStamp = null;
+  return (e) => {
+    const p = e?.payload;
+    if (e?.type === 'session_meta') {
+      const id = p?.id || p?.session_id || null;
+      if (ownId === null) { ownId = id; return false; }
+      // A resumed rollout can repeat its own meta; only another thread's is a copy.
+      if (id && id !== ownId) { copyStamp = e.timestamp ?? null; return true; }
+      return true;
+    }
+    if (copyStamp === null) return false;
+    const own = e?.type === 'event_msg' && p?.type === 'thread_settings_applied' && p.thread_id === ownId;
+    if (own || e?.timestamp !== copyStamp) { copyStamp = null; return false; }
+    return true;
+  };
+}
+
 function updateSnapshot(session, e) {
   const p = e?.payload;
   if (!p || typeof p !== 'object') return;
   const activity = Date.parse(e.timestamp);
   if (Number.isFinite(activity)) session.lastActivity = new Date(activity);
   if (e.type === 'session_meta') {
+    // Callers drop forked copies, so a later meta can only be this thread's own repeat.
+    if (session.sessionId) return;
     session.sessionId = p.id || p.session_id || null;
     session.projectDir = typeof p.cwd === 'string' ? p.cwd : '';
     session.source = p.source ?? null;
     session.isSubagent = typeof p.source === 'object' && p.source !== null && 'subagent' in p.source;
+    session.forkedFrom = typeof p.forked_from_id === 'string' ? p.forked_from_id : null;
     session.branch = typeof p.git?.branch === 'string' ? p.git.branch : null;
     session.provider = typeof p.model_provider === 'string' ? p.model_provider : null;
   }
@@ -63,8 +92,12 @@ export function readCodexSnapshot(filePath, { tailBytes = 256 * 1024 } = {}) {
   const lines = readCodexTailLines(filePath, tailBytes);
   if (!lines) return null;
   const snapshot = {};
+  const copied = forkedCopyFilter();
   for (const line of lines) {
-    try { updateSnapshot(snapshot, JSON.parse(line)); } catch { /* Partial or malformed record. */ }
+    try {
+      const e = JSON.parse(line);
+      if (!copied(e)) updateSnapshot(snapshot, e);
+    } catch { /* Partial or malformed record. */ }
   }
   return snapshot;
 }
@@ -164,7 +197,8 @@ const emptyTurn = (turnId) => ({ turnId, startedAt: null, endedAt: null, aborted
  * structured event described, so a call is never counted twice.
  */
 export async function parseCodexTurns(filePath, { cutoffMs = -Infinity } = {}) {
-  const session = { filePath, sessionId: null, projectDir: '', isSubagent: false, parentThreadId: null, provider: null, turns: [] };
+  const session = { filePath, sessionId: null, projectDir: '', isSubagent: false, parentThreadId: null, forkedFrom: null, provider: null, turns: [] };
+  const copied = forkedCopyFilter();
   const turns = new Map();
   const turnOf = (id) => {
     if (!id) return null;
@@ -184,12 +218,14 @@ export async function parseCodexTurns(filePath, { cutoffMs = -Infinity } = {}) {
     let e;
     try { e = JSON.parse(line); } catch { continue; }
     const p = e?.payload;
-    if (!p || typeof p !== 'object') continue;
+    if (!p || typeof p !== 'object' || copied(e)) continue;
     if (e.type === 'session_meta') {
+      if (session.sessionId) continue;
       session.sessionId = p.id || p.session_id || null;
       session.projectDir = typeof p.cwd === 'string' ? p.cwd : '';
       session.isSubagent = typeof p.source === 'object' && p.source !== null && 'subagent' in p.source;
       session.parentThreadId = p.source?.subagent?.thread_spawn?.parent_thread_id || null;
+      session.forkedFrom = typeof p.forked_from_id === 'string' ? p.forked_from_id : null;
       session.provider = typeof p.model_provider === 'string' ? p.model_provider : null;
       continue;
     }
@@ -303,6 +339,7 @@ export async function parseCodexSessionFile(filePath, { cutoffMs = -Infinity } =
     lastContextTokens: null, rateLimits: null, lastActivity: null, effort: null,
     cacheActivity: null,
   };
+  const copied = forkedCopyFilter();
   let previous = null;
   const stream = createReadStream(filePath, { encoding: 'utf8' });
   const lines = createInterface({ input: stream, crlfDelay: Infinity });
@@ -310,7 +347,7 @@ export async function parseCodexSessionFile(filePath, { cutoffMs = -Infinity } =
     let e;
     try { e = JSON.parse(line); } catch { continue; }
     const p = e?.payload;
-    if (!p) continue;
+    if (!p || copied(e)) continue;
     updateSnapshot(session, e);
     if (e.type !== 'event_msg' || p.type !== 'token_count') continue;
     if (!p.info) continue;

package/src/codex-route-scan.js

@@ -8,7 +8,8 @@ import { discoverCodexSessionFiles, parseCodexTurns } from './codex-parser.js';
 import { categorize, isSkippable, tierOf, calibrateThresholds, MIN_RECURRENCE,
   RESCAN_MIN_INTERVAL_MS, RESCAN_BIG_DELTA_BYTES, RESCAN_MAX_AGE_MS } from './route-scan.js';
 import { codexPromptCategory, loadCodexModelRules } from './codex-delegation.js';
-import { codexRunCost, readCodexPrices } from './codex-cache-policy.js';
+import { codexRunCost, codexPriceBook, isDirectOpenAI, readCodexPrices } from './codex-cache-policy.js';
+import { OPENAI_PRICES_CHECKED_AT } from './openai-prices.js';
 import { refreshCodexLedger } from './codex-ledger.js';
 
 /*
@@ -81,11 +82,12 @@ export async function shouldRescanCodex(cache, { home, days = 14, now = Date.now
  * a rule target, so a gateway that also serves unrelated models (embeddings,
  * other vendors) never has one suggested blind.
  */
-function pickTarget(group, { prices, known }) {
-  const cost = (model) => prices?.provider === group.provider ? codexRunCost(group.tokens, prices.prices[model]) : null;
+function pickTarget(group, { prices, known, home }) {
+  const book = codexPriceBook(group.provider, prices, { home });
+  const cost = (model) => book ? codexRunCost(group.tokens, book.prices[model]) : null;
   const parent = cost(group.from);
   if (parent === null) return { suggestedModel: null, alternatives: [], estSavedUsd: null };
-  const cheaper = Object.keys(prices.prices).filter((m) => m !== group.from && prices.prices[m])
+  const cheaper = Object.keys(book.prices).filter((m) => m !== group.from && book.prices[m])
     .map((m) => ({ model: m, usd: cost(m) })).filter((x) => x.usd !== null && x.usd < parent)
     .sort((a, b) => a.usd - b.usd);
   const eligible = cheaper.filter((x) => known.has(`${group.provider}|${x.model}`));
@@ -151,7 +153,11 @@ export async function runCodexRouteScan({ days = 14, now = Date.now(), home, dir
     (!r.provider || r.provider === g.provider) &&
     (r.scope === 'global' || r.targetRoot === g.projectRoot));
   const known = new Set([...observed, ...rules.filter((r) => r.provider).map((r) => `${r.provider}|${r.model}`)]);
-  if (prices?.provider && cfg?.codex?.delegateTarget?.model) known.add(`${prices.provider}|${cfg.codex.delegateTarget.model}`);
+  const target = cfg?.codex?.delegateTarget?.model;
+  if (target) {
+    if (prices?.provider) known.add(`${prices.provider}|${target}`);
+    if (isDirectOpenAI('openai', { home })) known.add(`openai|${target}`);
+  }
   const prev = readCodexRouteScan({ dir });
   const resolved = new Set(prev?.resolved || []);
   const candidates = [...groups.values()]
@@ -160,9 +166,10 @@ export async function runCodexRouteScan({ days = 14, now = Date.now(), home, dir
     .slice(0, MAX_CANDIDATES)
     .map((g, i) => ({ id: i + 1, signature: g.signature, category: g.category, label: g.label, labelEn: g.labelEn,
       from: g.from, provider: g.provider, projectRoot: g.projectRoot, count: g.count, tiers: g.tiers, example: g.example.slice(0, 160),
-      lastSeen: g.lastSeen || null, suggestedScope: 'project', ...pickTarget(g, { prices, known }) }));
+      lastSeen: g.lastSeen || null, suggestedScope: 'project', ...pickTarget(g, { prices, known, home }) }));
+  const priceCheckedAt = prices?.checkedAt ?? ([...groups.values()].some((g) => isDirectOpenAI(g.provider, { home })) ? OPENAI_PRICES_CHECKED_AT : null);
   const data = { version: 1, scannedAt: new Date(now).toISOString(), days, dataBytes, totalEpisodes: episodes.length,
-    thresholds, observedModels: [...observed], priceCheckedAt: prices?.checkedAt ?? null, candidates, resolved: [...resolved] };
+    thresholds, observedModels: [...observed], priceCheckedAt, candidates, resolved: [...resolved] };
   writeCache(data, dir);
   if (refreshLedger) {
     try { await refreshCodexLedger({ dir, home, now, prices }); } catch { /* The ledger catches up on the next scan. */ }

package/src/codex-rule-health.js

@@ -0,0 +1,41 @@
+import { resolve } from 'node:path';
+import { loadCodexLedger } from './codex-ledger.js';
+import { isFailedRun } from './route-scan.js';
+import { wilsonLowerBound, HEALTH_ERR_RATE, HEALTH_MIN_SAMPLE_DELEGATED } from './model-rules.js';
+
+/**
+ * Measured outcome of one Codex rule, judged as Claude's rule health judges
+ * its delegations: a run fails when interrupted or when its tool-error density
+ * crosses isFailedRun's line, and the rule goes to review only when the Wilson
+ * lower bound of the failure rate clears HEALTH_ERR_RATE over enough runs.
+ */
+export function codexRuleHealth(rule, { events = Object.values(loadCodexLedger().events) } = {}) {
+  const since = Date.parse(rule.createdAt);
+  const runs = events.filter((e) => e && e.category === rule.category && e.from === rule.from && e.to === rule.model &&
+    (!rule.provider || !e.provider || e.provider === rule.provider) && (e.complete || e.aborted) &&
+    (e.scope == null || e.scope === rule.scope) &&
+    // A project run counts only for the project it was recorded in; events from before the field existed cannot be placed.
+    (rule.scope !== 'project' || (typeof e.targetRoot === 'string' && e.targetRoot === rule.targetRoot)) &&
+    // A rule deleted and added again starts a fresh record.
+    (!Number.isFinite(since) || (Number.isFinite(e.ts) && e.ts >= since)));
+  const errs = runs.filter((e) => e.aborted || isFailedRun({ toolErrors: e.toolErrors, calls: e.calls })).length;
+  const saved = runs.filter((e) => Number.isFinite(e.usd)).reduce((sum, e) => sum + e.usd, 0);
+  const review = runs.length >= HEALTH_MIN_SAMPLE_DELEGATED && wilsonLowerBound(errs, runs.length) > HEALTH_ERR_RATE;
+  return { runs: runs.length, errs, rate: runs.length ? errs / runs.length : 0, saved, status: review ? 'review' : 'active' };
+}
+
+/**
+ * Rules in review that apply to the project at `root`: global rules, and
+ * project rules whose targetRoot is `root`; a null `root` lists every rule. `index` is the 1-based number the
+ * rule has in `delegate rules --agent codex`, so every surface names it alike.
+ */
+export function codexRulesInReview({ root, rules, events }) {
+  const here = root ? resolve(root) : null;
+  const out = [];
+  (rules || []).forEach((rule, i) => {
+    if (here && rule.scope === 'project' && rule.targetRoot !== here) return;
+    const health = codexRuleHealth(rule, { events });
+    if (health.status === 'review') out.push({ index: i + 1, rule, health });
+  });
+  return out;
+}

package/src/commands/brief.js

@@ -25,7 +25,10 @@ export async function run({ hasFlag }) {
     const parts = [];
     try {
       const { runBrief } = await import('../brief.js');
-      const out = await runBrief({ sessionId: ctx.session_id, transcriptPath: ctx.transcript_path });
+      // `root` is the session's cwd for the same reason routeHint takes it below:
+      // the settings that name the model and the compaction window are the
+      // project's, not those of whatever directory the hook was spawned in.
+      const out = await runBrief({ sessionId: ctx.session_id, transcriptPath: ctx.transcript_path, root: ctx.cwd || process.cwd() });
       if (out) parts.push(out);
     } catch (e) { debug('brief:hook', e); /* briefing is best-effort — never block a prompt */ }
     // State the matching delegation rule as a fact about this request. Registered
@@ -34,7 +37,7 @@ export async function run({ hasFlag }) {
     // the match here removes both steps. Silent unless it is sure — see
     // src/route-inject.js.
     try {
-      const { routeHint, sessionModelRank } = await import('../route-inject.js');
+      const { routeHint, routeMatch, matchCaps, sessionModelRank } = await import('../route-inject.js');
       // The payload names the session but not its model, so the rank comes from
       // the transcript: without it a Sonnet session is told to delegate to
       // Sonnet, which saves nothing.
@@ -46,8 +49,16 @@ export async function run({ hasFlag }) {
       // differ. Claude Code sends `cwd` for that reason and the PreToolUse hook
       // already reads it (src/delegation-guard.js). A payload without the field
       // leaves root undefined, which is the behaviour this had before.
-      const hint = routeHint(ctx.prompt, { sessionRank, root: ctx.cwd });
+      const match = routeMatch(ctx.prompt, { sessionRank });
+      const hint = routeHint(ctx.prompt, { sessionRank, root: ctx.cwd, match });
       if (hint) parts.push(hint);
+      // The delegation guard repeats these caps to the subagent, so the limit it
+      // works under is the one this hint states. A prompt with no match clears
+      // the record of the turn before it.
+      try {
+        const { recordRouteCaps } = await import('../route-caps.js');
+        recordRouteCaps(ctx.session_id, matchCaps(match));
+      } catch (e) { debug('brief:route-caps', e); }
     } catch (e) { debug('brief:route-hint', e); }
     if (parts.length) console.log(parts.join('\n'));
     return;

package/src/commands/codex-delegate.js

@@ -2,7 +2,9 @@ import { loadConfig, saveConfig } from '../config.js';
 import { configureCodexHooks } from '../codex-installer.js';
 import { validateCodexTarget, loadCodexModelRules, addCodexModelRule, removeCodexModelRule } from '../codex-delegation.js';
 import { findCodexCandidate, resolveCodexCandidate } from '../codex-route-scan.js';
-import { codexRoutingSavedTotals } from '../codex-ledger.js';
+import { codexRoutingSavedTotals, loadCodexLedger } from '../codex-ledger.js';
+import { codexRuleHealth, codexRulesInReview } from '../codex-rule-health.js';
+import { signedUsd } from '../money.js';
 import { codexProviderName } from '../agent.js';
 
 export function run({ args, getArg, hasFlag, root }) {
@@ -13,7 +15,6 @@ export function run({ args, getArg, hasFlag, root }) {
       throw new Error(`${flag} requires a value.`);
     }
   }
-  const rules = loadCodexModelRules();
   if (sub === 'rules') {
     if (args[2] === 'add') {
       if (hasFlag('--global') === hasFlag('--project')) throw new Error('Choose --global or --project for the rule.');
@@ -31,7 +32,15 @@ export function run({ args, getArg, hasFlag, root }) {
     else if (args[2]) throw new Error('Usage: delegate rules [add <category|R<N>> --from <model> --model <model> --global|--project | rm <N>]');
     const rules = loadCodexModelRules();
     if (!rules.length) console.log('No Codex model rules. Claude rules are not imported.');
-    rules.forEach((r, i) => console.log(`#${i + 1} ${r.category} | ${r.from} -> ${r.model} | ${r.scope}${r.targetRoot ? ` ${r.targetRoot}` : ''}`));
+    let events = [];
+    try { events = Object.values(loadCodexLedger().events); } catch { /* No ledger yet: rules list without outcomes. */ }
+    const inReview = new Set(codexRulesInReview({ rules, events, root: null }).map((x) => x.index));
+    rules.forEach((r, i) => {
+      const h = codexRuleHealth(r, { events });
+      const outcome = h.runs ? ` | measured x${h.runs}, err ${Math.round(h.rate * 100)}%, saved ${signedUsd(h.saved, 4)}` : '';
+      const warn = inReview.has(i + 1) ? ` | rule-health: ${h.errs}/${h.runs} runs failed, narrow the condition or remove (delegate rules rm ${i + 1} --agent codex)` : '';
+      console.log(`#${i + 1} ${r.category} | ${r.from} -> ${r.model} | ${r.scope}${r.targetRoot ? ` ${r.targetRoot}` : ''}${outcome}${warn}`);
+    });
     return;
   }
   if (!['on', 'off', 'status', 'model'].includes(sub)) throw new Error('Usage: delegate on|off|status|model <model>|rules --agent codex');
@@ -50,10 +59,13 @@ export function run({ args, getArg, hasFlag, root }) {
   }
   console.log(`Codex delegate: ${cfg.codex?.delegate === true ? 'on' : 'off'} (model routing and guidance)`);
   console.log(`Default target: ${cfg.codex?.delegateTarget?.model || 'inherit (no override)'}`);
-  console.log(`Codex rules: ${rules.length}`);
+  // Turning delegation off must work even when the rule file is damaged.
+  let ruleCount;
+  try { ruleCount = String(loadCodexModelRules().length); } catch (e) { ruleCount = `unreadable (${e.message})`; }
+  console.log(`Codex rules: ${ruleCount}`);
   console.log('Explicit spawn models and custom roles are preserved. Targets must be available from your Codex provider.');
   const saved = codexRoutingSavedTotals();
   console.log(saved.priced
-    ? `Routing saved: $${saved.total.toFixed(4)} over ${saved.priced} priced run(s). Details: sprag route-scan savings --agent codex`
+    ? `Routing saved: ${saved.total < 0 ? '-' : ''}$${Math.abs(saved.total).toFixed(4)} over ${saved.priced} priced run(s). Details: sprag route-scan savings --agent codex`
     : `Routing saved: n/a (${saved.runs ? `${saved.runs} attributed run(s), none priced` : 'no attributed runs yet'}). Review/trust the Sprag hooks in Codex /hooks.`);
 }

package/src/commands/codex.js

@@ -4,6 +4,8 @@ import { initCodexHarness, uninitCodexHarness, codexHarnessStatus } from '../cod
 import { findProjectRoot, harnessPromote, harnessListRules, harnessRmRule, harnessPrune } from '../harness.js';
 import { loadConfig, saveConfig } from '../config.js';
 import { resolve } from 'node:path';
+import { debug } from '../debug.js';
+import { signedUsd } from '../money.js';
 
 const HELP = `Sprag / Codex
 
@@ -19,7 +21,7 @@ Usage: sprag <command> --agent codex [options]
   doctor [--format json]         Config, hooks, harness, logs, and capabilities
   capabilities [--format json]   Support matrix, including native/unsupported areas
   brief [on|off|status]          Current warnings or prompt-briefing preference
-  last / history                Codex warning history; --days, --session, --project
+  last / history                Context/rate-limit warnings and handoffs; --days, --session, --project
   handoff [--cwd path]           Write Git state and Codex usage to HANDOFF-*.md
   delegate on|off|status         Native model routing and SubagentStart guidance
   delegate model <model>         Default target for spawns without an explicit model
@@ -149,13 +151,15 @@ export async function run({ args, version }) {
     if (args[1] === 'savings') {
       const { refreshCodexLedger, loadCodexLedger, codexRoutingSavedTotals } = await import('../codex-ledger.js');
       if (hasFlag('--refresh')) await refreshCodexLedger();
+      // The prompt hook runs this detached to price finished delegations.
+      if (hasFlag('--quiet')) return;
       const events = Object.entries(loadCodexLedger().events).map(([id, e]) => ({ id, ...e })).sort((a, b) => b.ts - a.ts);
       const totals = codexRoutingSavedTotals();
       if (format === 'json') { console.log(JSON.stringify({ agent: 'codex', totals, events }, null, 2)); return; }
       const money = (usd) => Number.isFinite(usd) ? `${usd < 0 ? '-' : ''}$${Math.abs(usd).toFixed(4)}` : 'n/a (unpriced)';
       console.log(`Codex routing saved: ${totals.priced ? `${money(totals.week)} (7d) / ${money(totals.total)} total` : 'n/a'} | ${totals.runs} attributed run(s), ${totals.runs - totals.priced} unpriced`);
       for (const e of events.slice(0, 20)) {
-        console.log(`${new Date(e.ts).toISOString().slice(0, 16)} ${e.source}${e.category ? `/${e.category}` : ''} ${e.from} -> ${e.to} ${money(e.usd)}${e.complete ? '' : ' (incomplete)'}`);
+        console.log(`${new Date(e.ts).toISOString().slice(0, 16)} ${e.source}${e.category ? `/${e.category}` : ''} ${e.from} -> ${e.to} ${money(e.usd)}${e.aborted ? ' (interrupted: whole cost counted as a loss)' : e.complete ? '' : ' (incomplete)'}`);
       }
       console.log('Counterfactual: the child run\'s own tokens priced at the parent model. Only Sprag-routed spawns with a recorded route id count.');
       return;
@@ -172,7 +176,7 @@ export async function run({ args, version }) {
     if (hasFlag('--refresh') || !cache) {
       // Prices live in the gateway snapshot; refresh it when stale so candidates can name a target.
       const { readCodexPrices, refreshCodexPrices } = await import('../codex-cache-policy.js');
-      if (!readCodexPrices()) { try { await refreshCodexPrices(); } catch { /* Candidates still list; targets need --model. */ } }
+      if (!readCodexPrices()) { try { await refreshCodexPrices(); } catch (e) { debug('codex:prices', e); } }
       cache = await rs.runCodexRouteScan({ days });
     }
     if (hasFlag('--quiet')) return;
@@ -181,7 +185,7 @@ export async function run({ args, version }) {
     console.log(`Codex route-scan: ${cache.totalEpisodes} turns in ${cache.days} days, scanned ${cache.scannedAt}${cache.priceCheckedAt ? '' : ' | prices unavailable'}`);
     if (!open.length) console.log('No recurring delegable pattern. Needs 3+ similar simple turns per project and parent model.');
     for (const c of open) {
-      const target = c.suggestedModel ? `-> ${c.suggestedModel}${Number.isFinite(c.estSavedUsd) ? ` (~$${c.estSavedUsd.toFixed(4)} over ${c.count} turns)` : ''}`
+      const target = c.suggestedModel ? `-> ${c.suggestedModel}${Number.isFinite(c.estSavedUsd) ? ` (~${signedUsd(c.estSavedUsd, 4)} over ${c.count} turns)` : ''}`
         : `-> choose --model${c.alternatives.length ? ` (priced cheaper: ${c.alternatives.join(', ')})` : ''}`;
       console.log(`R${c.id} ${c.category} x${c.count} [T2 ${c.tiers.T2} / T1 ${c.tiers.T1}] ${c.provider || 'unknown provider'} / ${c.from} ${target}`);
       console.log(`   ${c.projectRoot}`);
@@ -225,7 +229,7 @@ export async function run({ args, version }) {
       sessionId: getArg('--session'), project: getArg('--project') || getArg('-p') });
     if (cmd === 'last') events = events.slice(-1);
     if (format === 'json') { console.log(JSON.stringify({ agent: 'codex', events }, null, 2)); return; }
-    if (!events.length) console.log('No Codex warning history in this window. Records are written by the trusted prompt hook.');
+    if (!events.length) console.log('No Codex warning history in this window. The trusted prompt hook records context and rate-limit warnings; handoffs are recorded when written.');
     else if (hasFlag('--list')) console.log([...new Set(events.map((event) => event.at.slice(0, 10)))].reverse().join('\n'));
     else for (const event of events) {
       console.log(terminalText(`${event.at} [${event.sessionId}] ${event.message}`));
@@ -239,6 +243,11 @@ export async function run({ args, version }) {
     const cwd = getArg('--cwd') || process.cwd();
     const data = await createPanelReader({ root: findProjectRoot(resolve(cwd), { agent: 'codex' }), sessionId: getArg('--session'), days: numArg('--days', { dflt: 7, min: 0 }) })();
     const result = writeHandoff({ cwd, agent: 'codex', session: data.session });
+    try {
+      const { recordCodexHistoryEvent } = await import('../codex-brief.js');
+      recordCodexHistoryEvent({ sessionId: data.session?.sessionId, project: cwd, key: 'handoff',
+        message: `Handoff written: ${result.path}` });
+    } catch (e) { debug('codex:handoff-record', e); }
     console.log(`Handoff written: ${result.path}`);
     console.log('Fill in the remaining-work sections, then ask the next Codex session to read this file.');
     return;
@@ -324,7 +333,7 @@ export async function run({ args, version }) {
     })() : { read: createCodexBudgetReader() };
     if (hasFlag('--once')) {
       const provider = codexBudgetProvider();
-      if (provider) { try { readBudget.set(await fetchCodexBudget(provider)); } catch { /* No verified budget. */ } }
+      if (provider) { try { readBudget.set(await fetchCodexBudget(provider)); } catch (e) { debug('codex:budget', e); } }
     }
     const { createInlinePanelResizer } = await import('../codex-panel-runner.js');
     const rawInterval = getArg('--interval');
@@ -340,7 +349,7 @@ export async function run({ args, version }) {
         readCachePolicy: hasFlag('--once') ? async (session) => {
           const { readCodexCachePolicy } = await import('../codex-cache-policy.js');
           try { return readCodexCachePolicy(session) || await refreshCodexCachePolicy(session); }
-          catch { return null; }
+          catch (e) { debug('codex:cache-policy', e); return null; }
         } : createCodexCachePolicyReader(), hasFlag }),
       interval: interval * 1000, once: hasFlag('--once'),
       color: !hasFlag('--no-color') && !process.env.NO_COLOR && !!process.stdout.isTTY, version, compact: hasFlag('--compact'),
@@ -377,7 +386,7 @@ export async function run({ args, version }) {
       }
       const out = await codexHookOutput(getArg('--event'), payload);
       if (out) console.log(JSON.stringify(out));
-    } catch { /* Hook failures must not break the agent loop. */ }
+    } catch (e) { debug('codex:hook', e); /* Hook failures must not break the agent loop. */ }
     return;
   }
   if (cmd === 'install') {
@@ -396,7 +405,7 @@ export async function run({ args, version }) {
       const { preparePresetRatchet } = await import('../preset-ratchet.js');
       const p = preparePresetRatchet({ agent: 'codex' });
       console.log(`Codex preset rules: ${p.file} (${p.rules} registered${p.moved ? `, ${p.moved} moved from ratchet.md` : ''})`);
-    } catch { /* Presets are optional; `seed` still registers them. */ }
+    } catch (e) { debug('codex:preset', e); /* Presets are optional; `seed` still registers them. */ }
     console.log('Open /hooks in Codex and review/trust the Sprag hooks before they can run.');
     console.log(`Panel auto-start: ${panelAuto ? 'registered with the other hooks' : 'off'}. Hook registration is complete; runtime activation is not verified.`);
     console.log('After approval, start or resume Codex and run: sprag panel doctor --agent codex');
@@ -508,7 +517,8 @@ export async function run({ args, version }) {
     console.log(`Cache: ${doc2md.cacheDir()}`);
     try {
       for (const hook of codexHookStatus().filter((h) => ['PreToolUse', 'UserPromptSubmit'].includes(h.event))) console.log(`${hook.event}: ${hook.registered ? 'registered' : 'missing/outdated'}`);
-    } catch {
+    } catch (e) {
+      debug('codex:hook-status', e);
       console.log('Hooks: cannot read Codex hooks.json; file left unchanged. Run sprag doctor --agent codex for diagnostics.');
     }
     console.log('Prompt conversion, supported reads, and document/cache write guards require trusted hooks. Review in Codex /hooks.');

package/src/commands/harness.js

@@ -106,6 +106,12 @@ export async function run({ args, hasFlag }) {
       for (const p of r.backedUp) console.log(`Backed up: ${p}`);
       for (const p of r.wrote) console.log(`Wrote:     ${p}`);
       for (const p of r.skipped) console.log(`Skipped:   ${p}`);
+      if (r.brokenBlock) {
+        // Nothing was written to CLAUDE.md, so claiming success would hide it.
+        console.log('\n🅷 Harness not initialized: repair the block markers in CLAUDE.md, then run this again.');
+        process.exitCode = 1;
+        return;
+      }
       console.log('\n🅷 Harness initialized. Statusline will show 🅷 5/5 on next refresh.');
       return;
     }

package/src/commands/route-scan.js

@@ -10,6 +10,7 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 import { readStdinJson } from '../stdin-payload.js';
 import { debug } from '../debug.js';
+import { signedUsd } from '../money.js';
 
 /**
  * Whether the user turned doc2md on.
@@ -65,7 +66,7 @@ export async function run({ args, hasFlag, numArg }) {
         return;
       }
       const t = delegationSavedTotals();
-      const money = (v) => `$${v.toFixed(2)}`;
+      const money = (v) => (v < 0 ? `-$${(-v).toFixed(2)}` : `$${v.toFixed(2)}`); // sign before the symbol
       // Lifetime leads (it is what the breakdown below adds up to); the
       // rolling windows follow as context rather than as competing headlines.
       console.log(lang === 'ko'
@@ -154,8 +155,8 @@ export async function run({ args, hasFlag, numArg }) {
         // two mean opposite things (no data vs. data showing no value).
         const measured = r.delegatedRuns
           ? (lang === 'ko'
-            ? `실제 위임 ${r.delegatedRuns}건 · 에러율 ${Math.round((r.delegatedErrRate || 0) * 100)}% · 절감 ~$${(r.savedUsd || 0).toFixed(2)}`
-            : `measured ×${r.delegatedRuns} · err ${Math.round((r.delegatedErrRate || 0) * 100)}% · saved ~$${(r.savedUsd || 0).toFixed(2)}`)
+            ? `실제 위임 ${r.delegatedRuns}건 · 에러율 ${Math.round((r.delegatedErrRate || 0) * 100)}% · 절감 ~${signedUsd(r.savedUsd || 0)}`
+            : `measured ×${r.delegatedRuns} · err ${Math.round((r.delegatedErrRate || 0) * 100)}% · saved ~${signedUsd(r.savedUsd || 0)}`)
           : (sessionRank !== null && !rs.worthDelegating(r.tier, sessionRank)
             ? (lang === 'ko'
               ? `이 규칙은 현재 기본 모델(${sessionModel}) 기준으로는 적용되지 않습니다. 세션 모델이 이미 위임 목표와 같은 급이어서 절감이 발생하지 않습니다.`

package/src/compact-window.js

@@ -111,6 +111,10 @@ export function isOneMillionModel(model) {
   return typeof model === 'string' && ONE_M_RE.test(model);
 }
 
+// A window Claude Code itself reported for the session (statusline payload).
+// Anything this large can only be the 1M window.
+export const LIVE_1M_MIN = 900_000;
+
 /** Effective autoCompactWindow, with the source that won. */
 export function effectiveWindow(root) {
   const env = process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW;
@@ -137,10 +141,14 @@ export function effectiveWindow(root) {
  *
  * `reason` names why it is not ok: 'unset' (no autoCompactWindow anywhere) or
  * 'too-large' (set, but above 700k — still lets context run away).
+ *
+ * `liveWindow` is the window Claude Code reported for the running session. The
+ * model id alone misses every model that is 1M without a `[1m]` suffix, so a
+ * reported size settles it whenever the caller has one.
  */
-export function compactWindowStatus({ root = process.cwd() } = {}) {
+export function compactWindowStatus({ root = process.cwd(), liveWindow = null } = {}) {
   const { model, source: modelSource } = resolveModelId(root);
-  const is1m = isOneMillionModel(model);
+  const is1m = isOneMillionModel(model) || (Number.isFinite(liveWindow) && liveWindow >= LIVE_1M_MIN);
   const win = effectiveWindow(root);
   const base = {
     model,
@@ -163,10 +171,10 @@ export function compactWindowStatus({ root = process.cwd() } = {}) {
  * Statusline chip text, or null when there is nothing to say. Kept to the same
  * short shape as the other 🅷⚠ warnings so the line stays single-width.
  */
-export function compactWindowWarningForStatusline(root = process.cwd(), cfg = null) {
+export function compactWindowWarningForStatusline(root = process.cwd(), cfg = null, { liveWindow = null } = {}) {
   if (cfg && cfg.compactWindow && cfg.compactWindow.enabled === false) return null;
   try {
-    const s = compactWindowStatus({ root });
+    const s = compactWindowStatus({ root, liveWindow });
     return s.ok ? null : 'compact-window?';
   } catch (e) {
     debug('compact-window:statusline', e);

package/src/config.js

@@ -9,10 +9,11 @@
  *   Linux:   $XDG_CONFIG_HOME/claude-token-saver/config.json or ~/.config/...
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 import { labelPreference } from './statusline-mode.js';
+import { writeStateFile } from './state-file.js';
 
 const CONFIG_DIR = userDataDir();
 const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
@@ -31,8 +32,7 @@ export function loadConfig() {
 }
 
 export function saveConfig(cfg) {
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n');
+  writeStateFile(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n');
 }
 
 // Each keyword maps to a single statusline option toggle.

package/src/cost.js

@@ -91,8 +91,11 @@ function detectPricingTier(model) {
 
   if (m.includes('haiku')) {
     if (/haiku[-_.]?4[-_.]?5/.test(m)) return 'claude-haiku-4-5';
-    if (/haiku[-_.]?3[-_.]?5/.test(m)) return 'claude-haiku-3-5';
-    if (/haiku[-_.]?3\b/.test(m)) return 'claude-haiku-3';
+    // The 3.x ids put the version first (`claude-3-5-haiku-20241022`,
+    // `claude-3-haiku-20240307`), so both orders are matched. With only the
+    // family-first order, 3.5 Haiku fell through to the 4.5 rate.
+    if (/haiku[-_.]?3[-_.]?5|3[-_.]?5[-_.]?haiku/.test(m)) return 'claude-haiku-3-5';
+    if (/haiku[-_.]?3\b|\b3[-_.]?haiku/.test(m)) return 'claude-haiku-3';
     return 'claude-haiku-4-5';
   }
 
@@ -197,7 +200,8 @@ function tokensToMillions(n) {
  *   ephemeral1h      — portion of cacheCreation billed at 1h rate (2x input)
  *   output           — output tokens
  */
-export function estimateCost(totals, model) {
+export function estimateCost(totals, model, { price } = {}) {
+  if (price) return estimateCostAtPrice(totals, price);
   const tier = detectPricingTier(model);
   const p = PRICING[tier];
 
@@ -248,20 +252,73 @@ export function estimateCost(totals, model) {
   };
 }
 
+/**
+ * Same shape as the list-price estimate, but priced at a gateway's per-token
+ * rates (LiteLLM /model/info). A token class the gateway does not price makes
+ * the whole estimate unknown (null) rather than free or list-priced.
+ */
+function estimateCostAtPrice(totals, price) {
+  const write5m = totals.ephemeral5m ?? 0;
+  const write1h = totals.ephemeral1h ?? 0;
+  const untracked = Math.max(0, (totals.cacheCreation ?? 0) - write5m - write1h);
+  const read = totals.cacheRead ?? 0;
+  if (read > 0 && price.cacheRead == null) return null;
+  if (write5m + untracked > 0 && price.cacheWrite == null) return null;
+  if (write1h > 0 && price.cacheWrite1h == null) return null;
+  if (price.input == null || price.output == null) return null;
+  const perM = (rate) => (rate ?? 0) * 1e6;
+  const input = perM(price.input), output = perM(price.output), cacheRead = perM(price.cacheRead);
+  const cacheWrite5m = perM(price.cacheWrite), cacheWrite1h = perM(price.cacheWrite1h);
+
+  const actual =
+    tokensToMillions(totals.input) * input +
+    tokensToMillions(write5m + untracked) * cacheWrite5m +
+    tokensToMillions(write1h) * cacheWrite1h +
+    tokensToMillions(read) * cacheRead +
+    tokensToMillions(totals.output) * output;
+  const totalInput = totals.input + (totals.cacheCreation ?? 0) + read;
+  const noCacheCost = tokensToMillions(totalInput) * input + tokensToMillions(totals.output) * output;
+
+  // The 5m scenario needs a 5m write rate; without one it is not computable, so
+  // it collapses to the actual cost and the "extra cost" row stays hidden.
+  let scenario5mCost = actual;
+  if (price.cacheWrite != null) {
+    const extra5mCreation = write1h * 2;
+    scenario5mCost =
+      tokensToMillions(totals.input) * input +
+      tokensToMillions(write5m + write1h + untracked + extra5mCreation) * cacheWrite5m +
+      tokensToMillions(Math.max(0, read - extra5mCreation)) * cacheRead +
+      tokensToMillions(totals.output) * output;
+  }
+
+  return {
+    tier: 'gateway',
+    actual: round(actual),
+    noCacheCost: round(noCacheCost),
+    savings: round(noCacheCost - actual),
+    savingsRate: noCacheCost > 0 ? (noCacheCost - actual) / noCacheCost : 0,
+    scenario5mCost: round(scenario5mCost),
+    extraCostIf5m: round(scenario5mCost - actual),
+    extraCostIf5mApplicable: price.cacheWrite != null && write1h > 0,
+  };
+}
+
 /**
  * Price a set of sessions each at its own model and sum. One estimateCost over
  * the summed totals priced every token at whichever session came first in the
  * list — sorted by mtime, so a haiku scratch session touched earliest set the
  * rate for a day of Fable work and understated the saving about tenfold.
  * Sessions whose model has no known rate are skipped, as month-spend does.
+ * `estimate` lets a caller price by path (see claude-price.js); null skips a session.
  */
-export function estimateCostAcross(sessions) {
+export function estimateCostAcross(sessions, estimate = estimateCost) {
   const acc = { actual: 0, noCacheCost: 0, scenario5mCost: 0, extraCostIf5mApplicable: false };
   const tiers = new Map();
   for (const s of sessions || []) {
     if (!s?.totals) continue;
     let c;
-    try { c = estimateCost(s.totals, s.model); } catch { continue; }
+    try { c = estimate(s.totals, s.model); } catch { continue; }
+    if (!c) continue;
     acc.actual += c.actual;
     acc.noCacheCost += c.noCacheCost;
     acc.scenario5mCost += c.scenario5mCost;