sprag-cli 3.56.0 → 3.57.0

package/README.ko.md

@@ -185,7 +185,7 @@ JetBrains IDE 내장 터미널에서는 이모지 대신 한 칸 글리프로
 
 | 명령 | 하는 일 |
 |---|---|
-| `sprag` | 최근 1일 진단 리포트 |
+| `sprag` | 최근 30일 진단 리포트 |
 | `sprag handoff` | 한도에 막히기 전에 작업 상태를 백업 |
 | `sprag route-scan` | 내 기록에서 위임 후보 찾기 (LLM 호출 0회) |
 | `sprag route-scan savings` | 라우팅 절감 원장 조회 |

package/README.md

@@ -229,7 +229,7 @@ work types, and once each has a rule there is nothing left to promote.
 
 | Command | What it does |
 |---|---|
-| `sprag` | Last-1-day diagnostic report |
+| `sprag` | Last-30-day diagnostic report |
 | `sprag handoff` | Back work up to markdown before a cap blocks you |
 | `sprag route-scan` | Find delegation candidates in your own history (0 LLM calls) |
 | `sprag route-scan savings` | The routing-savings ledger |

package/bin/cli.js

@@ -36,12 +36,13 @@ import {
   extractContextUsage,
   extractEffort,
   extractModel,
+  extractSessionId,
   extractTranscriptPath,
 } from '../src/stdin-payload.js';
 
 import { effortChipLevel } from '../src/ultracode.js';
 
-import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
+import { parseAllSessions, sessionsSince, getLastUserMessageTime } from '../src/parser.js';
 import {
   dailyTrend,
   ttlBreakdown,
@@ -92,6 +93,15 @@ function readUpdateChip() {
   }
 }
 
+/**
+ * Whether the table report may use ANSI codes. The formatter looked at NO_COLOR
+ * alone, so `--no-color` did nothing there and a piped report (`sprag | less`,
+ * a redirect to a file) carried escape codes into its output.
+ */
+function tableColor() {
+  return !hasFlag('--no-color') && !process.env.NO_COLOR && !!process.stdout.isTTY;
+}
+
 // Subcommands this build knows how to run. Used only by the guard below.
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
@@ -131,6 +141,16 @@ Usage:
   sprag last               most recent warning + how to handle it
   sprag history            recent warning transitions
   sprag handoff            write a session handoff file
+  sprag mode [keywords]    statusline preferences (icon/text, en/ko, window, ttl)
+  sprag seed               register the bundled starter rules, one answer at a time
+  sprag korean on|off|status     Korean writing guidance + write-time check
+  sprag cohesion on|off|status   English sentence-connection guidance
+  sprag doc2md on|off|<file>     convert documents to Markdown before the model reads them
+  sprag delegate on|off|status   add bounds and context to Task/Agent delegation prompts
+  sprag compact-window     audit or pin autoCompactWindow for 1M sessions
+  sprag litellm-budget     LiteLLM gateway key budget and spend
+  sprag update-check       is a newer version out?
+  sprag brief --hook       internal: the UserPromptSubmit hook entry point
   sprag feedback "<msg>"   file a bug report / feature request (no browser needed)
   sprag upgrade            install the latest release
   sprag --install-hook     install cache-monitor PostToolUse hook
@@ -434,7 +454,7 @@ async function main() {
     const { buildTableDemoData } = await import('../src/demo.js');
     const { formatReport } = await import('../src/formatters/table.js');
     const data = buildTableDemoData({ version: PKG_VERSION });
-    console.log(formatReport(data));
+    console.log(formatReport(data, { color: tableColor() }));
     return;
   }
 
@@ -529,7 +549,10 @@ async function main() {
   const excludeSessionPath =
     getArg('--exclude-session') || process.env.CACHE_MONITOR_EXCLUDE_SESSION || undefined;
 
-  const sessions = await parseAllSessions({ days, projectFilter });
+  // The statusline also reports this month's spend. Naming the month start here
+  // lets the one pass over the transcripts trim boundary sessions to it too.
+  const monthSince = isStatusline ? (await import('../src/month-spend.js')).monthStartMs() : undefined;
+  const sessions = await parseAllSessions({ days, projectFilter, sinceMs: monthSince });
 
   if (sessions.length === 0) {
     // Statusline must always emit a single line (no multi-line help spam every
@@ -552,6 +575,15 @@ async function main() {
       // Resolved the same way as on the populated line below, so the chip does
       // not change its mind about the level when the analysis window empties.
       const effort = effortChipLevel(extractEffort(stdinJson), extractTranscriptPath(stdinJson));
+      // Recorded here too: a fresh session can render before it has any request
+      // in the analysis window, and its first prompt is briefed from this.
+      const ctxLive = extractContextUsage(stdinJson);
+      if (ctxLive?.size) {
+        try {
+          const { recordLiveWindow } = await import('../src/ctx-window-cache.js');
+          recordLiveWindow(extractSessionId(stdinJson), ctxLive.size);
+        } catch (e) { debug('ctx-window-cache:record', e); }
+      }
       if (caps || model) {
         try {
           const { persistSnapshot } = await import('../src/caps-cache.js');
@@ -618,6 +650,16 @@ async function main() {
     ? effortChipLevel(extractEffort(stdinJson), extractTranscriptPath(stdinJson))
     : extractEffort(stdinJson);
   const ctxLive = extractContextUsage(stdinJson);
+  // The prompt-submit briefing has no payload field for the window, so it reads
+  // back what this render was told (see src/ctx-window-cache.js).
+  if (isStatusline && ctxLive?.size) {
+    try {
+      const { recordLiveWindow } = await import('../src/ctx-window-cache.js');
+      recordLiveWindow(extractSessionId(stdinJson), ctxLive.size);
+    } catch (e) {
+      debug('ctx-window-cache:record', e);
+    }
+  }
   if (isStatusline && (caps || model)) {
     try {
       const { persistSnapshot } = await import('../src/caps-cache.js');
@@ -730,28 +772,23 @@ async function main() {
   if (isStatusline) {
     try {
       const { monthSpend, monthStartMs } = await import('../src/month-spend.js');
-      const daysNeeded = (Date.now() - monthStartMs()) / 86400000;
+      const since = monthStartMs();
+      const daysNeeded = (Date.now() - since) / 86400000;
       const monthSessions = days >= daysNeeded
         ? sessions
-        : await parseAllSessions({ days: Math.max(1, Math.ceil(daysNeeded)), projectFilter });
-      monthSpendInfo = monthSpend(monthSessions);
+        : await parseAllSessions({ days: Math.max(1, Math.ceil(daysNeeded)), projectFilter, sinceMs: since });
+      // 월 경계에 걸친 세션은 월초 이후 요청만 남긴다. 그러지 않으면 1일 자정을
+      // 넘긴 세션의 전월분이 이번 달 지출에 그대로 들어온다.
+      monthSpendInfo = monthSpend(await sessionsSince(monthSessions, since));
     } catch (e) {
       debug('month-spend', e);
     }
   }
 
-  // What delegation has measurably saved, read straight from the registry
-  // route-scan maintains. A lookup, never a scan: the statusline re-renders
-  // every few seconds and a scan parses tens of MB of transcripts.
-  let delegationSaved = 0;
-  try {
-    const { delegationSavedUsd } = await import('../src/model-rules.js');
-    delegationSaved = delegationSavedUsd();
-  } catch (e) {
-    debug('model-rules:saved', e); // an unreadable registry just hides the chip
-  }
   // Rolling week/month/lifetime totals from the delegation ledger — the
   // statusline's headline line. Falls back to null (chip hidden) on any error.
+  // A lookup, never a scan: the statusline re-renders every few seconds and a
+  // scan parses tens of MB of transcripts.
   let delegationTotals = null;
   try {
     const { delegationSavedTotals } = await import('../src/savings-ledger.js');
@@ -759,6 +796,10 @@ async function main() {
   } catch (e) {
     debug('savings-ledger:totals', e);
   }
+  // The single-line layout shows the same lifetime figure as the headline
+  // line. It used to sum the rule registry instead, a scan-window snapshot
+  // priced against another baseline, so one label carried two amounts.
+  const delegationSaved = Number(delegationTotals?.total) || 0;
   // Document conversions, same shape as the delegation totals: a lifetime sum
   // plus a document count. A lookup of a small JSON file, never a scan.
   let doc2mdTotals = null;
@@ -857,7 +898,7 @@ async function main() {
     });
   } else {
     const { formatReport } = await import('../src/formatters/table.js');
-    output = formatReport(data);
+    output = formatReport(data, { color: tableColor() });
   }
 
   console.log(output);

package/bin/postinstall.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+/**
+ * npm `postinstall` entry point: runs `sprag install` for a global install and
+ * says why it did not for anything else. See src/postinstall.js.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { postinstallDecision } from '../src/postinstall.js';
+
+const decision = postinstallDecision(process.env);
+if (!decision.run) {
+  console.log(`sprag: setup skipped (${decision.reason}). Run \`sprag install\` to register the hooks and the statusline.`);
+  process.exit(0);
+}
+const cli = join(dirname(fileURLToPath(import.meta.url)), 'cli.js');
+spawnSync(process.execPath, [cli, 'install'], { stdio: 'inherit' });
+// A failed setup must not fail the package install: the CLI is still usable
+// and `sprag install` can be run again by hand.
+process.exit(0);

package/docs/CODEX.ko.md

@@ -114,7 +114,11 @@ Codex 0.159.2에서는 `spawn_agent`가 `PreToolUse`를 거치지 않습니다(
 "사용자가 위임을 요청했다"는 뜻으로 읽게 합니다. 자식은 `fork_turns "none"`으로 뜨고, 부모는
 같은 일을 직접 하지 않고 `wait_agent`(제한 시간 120초 이상)로 자식이 끝나기를 기다립니다. 귀속은
 자식이 route id를 되받아 적는 것에 기대지 않습니다. 대신 `SubagentStart`가 대기 중인 기록(같은
-부모 세션, 같은 목표 모델, 30분 이내)에 새로 뜬 자식을 매칭해 묶습니다.
+부모 세션, 같은 목표 모델, 30분 이내)에 새로 뜬 자식을 매칭해 묶습니다. 어떤 자식도 가져가지
+않은 안내는 부모 세션에 다음 프롬프트가 들어올 때 닫히므로, 나중에 다른 이유로 뜬 자식이 그
+안내의 절감으로 잡히지 않습니다. 같은 프롬프트 시점에 아직 장부에 반영되지 않은 위임 실행도
+별도 프로세스로 계산하므로, `Routing saved`는 다음 route-scan을 기다리지 않고 위임 뒤 첫
+프롬프트에서 갱신됩니다.
 
 이 안내는 부모 세션의 컨텍스트가 `codex.delegateMinContext`(기본 60000 토큰) 아래면 붙지
 않습니다. 2026-09-30 실측에서 작은 세션은 스폰·대기·검증이라는 조율 비용이 자식이 아끼는

package/docs/CODEX.md

@@ -166,6 +166,11 @@ with `fork_turns "none"`, then wait for it (`wait_agent` with a timeout of at le
 route id back: `SubagentStart` binds the id to whichever spawned child matches
 the pending route (same parent thread, same target model, within 30 minutes),
 so a route is credited even when the child's own first message never repeats it.
+A hint that no child claimed is closed when the parent's next prompt arrives, so
+a child spawned later for some other reason is not credited to it. That same
+prompt also prices any delegated run the ledger has not joined yet, in a
+detached process, so `Routing saved` follows a delegation by one prompt instead
+of waiting for the next route scan.
 
 The hint is withheld below `codex.delegateMinContext` (default 60000 input
 tokens, read from the parent's own rollout). Measured 2026-09-30: a small

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.56.0",
+  "version": "3.57.0",
   "description": "Cut the tokens Claude Code and Codex spend: routes simple work to cheaper models, converts documents to compact Markdown, and shows spend and savings live. Ratchet rules and Korean writing checks included.",
   "type": "module",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "deploy": "node scripts/deploy.mjs",
     "docs:statusline": "node scripts/docs-statusline.mjs",
-    "postinstall": "node bin/cli.js install || true",
+    "postinstall": "node bin/postinstall.js || true",
     "publish:legacy": "node scripts/publish-legacy.mjs",
     "release:notes": "node scripts/release-notes.mjs",
     "site:docs": "node scripts/build-site-docs.mjs",

package/src/agents.js

@@ -20,12 +20,26 @@ const AGENT_MODEL = {
   'haiku-runner': 'haiku',
   'haiku-translate': 'haiku',
   'sonnet-worker': 'sonnet',
+  // A T1 rule names its target by tier alone (`agent: 'sonnet'`), with no
+  // preset agent behind it. Without these the phrase fell through to the
+  // haiku default, and a sonnet rule told the session to delegate to haiku.
+  sonnet: 'sonnet',
+  haiku: 'haiku',
 };
 
-/** True when `<name>.md` exists in the project or user agents directory. */
+/**
+ * True when `<name>.md` exists in the project or user agents directory.
+ *
+ * `root: null` asks about the user directory alone. Text that every project
+ * reads (the global ratchet-model.md) has to be worded from what every project
+ * can see: checked against the current directory, the same rule read
+ * `haiku-explore(model: haiku)` when the scan ran in a project that defines
+ * the agent and `model: haiku` when it ran anywhere else, and each flip
+ * rewrote a file sitting in the prompt-cache prefix of every session.
+ */
 export function agentExists(name, root = process.cwd()) {
   if (!name) return false;
-  return existsSync(join(root, '.claude', 'agents', `${name}.md`)) ||
+  return (root !== null && existsSync(join(root, '.claude', 'agents', `${name}.md`))) ||
     existsSync(join(claudeUserDir(), 'agents', `${name}.md`));
 }
 

package/src/brief.js

@@ -29,6 +29,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, openSync,
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 import { resolveModelId, isOneMillionModel, effectiveWindow } from './compact-window.js';
+import { liveWindowFor } from './ctx-window-cache.js';
 
 // Context tiers as a fraction of the session's context window. Tier 1 warns
 // (compaction/cost territory ahead), tier 2 urges wrapping up. A session only
@@ -83,14 +84,21 @@ function saveState(state, now) {
  *
  * `observedMax` stays as a floor: it proves a 1M window even when the model id
  * is unreadable (env override, settings we do not resolve).
+ *
+ * `liveWindow` outranks both. It is the size Claude Code reported to the
+ * statusline for this session, so the briefing and the statusline count against
+ * the same window. The model id cannot stand in for it: a model that is 1M
+ * without a `[1m]` suffix reads as 200k there.
  */
-export function ctxWindowFor(observedMax = 0, root = process.cwd()) {
+export function ctxWindowFor(observedMax = 0, root = process.cwd(), { liveWindow = null } = {}) {
   let modelWindow = observedMax > WINDOW_1M_MIN_INPUT ? 1_000_000 : 200_000;
+  const reported = Number.isFinite(liveWindow) && liveWindow > 0;
+  if (reported) modelWindow = liveWindow;
   let window = modelWindow;
   let compactCapped = false;
   try {
     const { model } = resolveModelId(root);
-    if (isOneMillionModel(model)) modelWindow = window = 1_000_000;
+    if (!reported && isOneMillionModel(model)) modelWindow = window = 1_000_000;
     const cap = effectiveWindow(root).value;
     if (cap !== null && cap < window) {
       window = cap;
@@ -104,7 +112,7 @@ export function ctxWindowFor(observedMax = 0, root = process.cwd()) {
  * Last request's input size for THIS session, from the transcript tail.
  * Reads at most TAIL_BYTES — prompt-submit hooks must stay fast.
  */
-export function sessionCtx(transcriptPath, { root = process.cwd() } = {}) {
+export function sessionCtx(transcriptPath, { root = process.cwd(), liveWindow = null } = {}) {
   let size;
   try { size = statSync(transcriptPath).size; } catch { return null; }
   const start = Math.max(0, size - TAIL_BYTES);
@@ -130,7 +138,7 @@ export function sessionCtx(transcriptPath, { root = process.cwd() } = {}) {
     if (total > 0) { input = total; maxInput = Math.max(maxInput, total); }
   }
   if (input == null) return null;
-  const { window, modelWindow, compactCapped } = ctxWindowFor(maxInput, root);
+  const { window, modelWindow, compactCapped } = ctxWindowFor(maxInput, root, { liveWindow });
   return { input, window, modelWindow, compactCapped, pct: input / window };
 }
 
@@ -166,14 +174,15 @@ export function seedSessionBriefed(sessionId, signatures, now = Date.now()) {
  * (recorded via seedSessionBriefed) are skipped; every other fresh signature
  * is emitted, including on the session's first event.
  */
-export async function runBrief({ sessionId, transcriptPath, now = Date.now() }) {
+export async function runBrief({ sessionId, transcriptPath, root = process.cwd(), now = Date.now() }) {
   if (!sessionId) return null;
+  const liveWindow = liveWindowFor(sessionId);
   const state = loadState();
   const s = state.sessions[sessionId] || { ctxTier: 0, briefed: [] };
   const items = [];
 
   // ── context tier crossing (per-session) ──
-  const ctx = transcriptPath ? sessionCtx(transcriptPath) : null;
+  const ctx = transcriptPath ? sessionCtx(transcriptPath, { root, liveWindow }) : null;
   if (ctx) {
     const tier = ctxTierOf(ctx.pct);
     // The tier is not monotonic: auto-compaction drops the live context back to
@@ -238,7 +247,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
   // never needed. 200k sessions are exempt (their window is already <= 200k).
   try {
     const cw = await import('./compact-window.js');
-    const st = cw.compactWindowStatus({ root: process.cwd() });
+    const st = cw.compactWindowStatus({ root, liveWindow });
     if (!st.ok) {
       const sig = `compact-window|${st.reason}`;
       const briefed = new Set(s.briefed || []);
@@ -246,7 +255,7 @@ export async function runBrief({ sessionId, transcriptPath, now = Date.now() })
         briefed.add(sig);
         s.briefed = [...briefed];
         const now = st.window ? `현재 ${fmtK(st.window)}` : '현재 미설정';
-        items.push(`1M 컨텍스트 모델(${st.model})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: sprag compact-window set --global|--project [--value ${fmtK(st.recommendedMax)}] (기본 ${fmtK(st.recommended)}, 적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
+        items.push(`1M 컨텍스트 모델(${st.model || 'Claude Code 기본 모델'})인데 autoCompactWindow가 ${now}입니다 — 자동 압축이 80만 토큰 근처에서야 걸려 그전까지 모든 요청이 전체 컨텍스트를 재과금합니다. 1M은 너무 크니 ${fmtK(st.recommendedMin)}~${fmtK(st.recommendedMax)} 범위를 권장합니다(그 범위 안이면 경고하지 않습니다). 1M 창 자체는 그대로 두고 압축 시점만 앞당깁니다. 등록: sprag compact-window set --global|--project [--value ${fmtK(st.recommendedMax)}] (기본 ${fmtK(st.recommended)}, 적용 범위는 사용자에게 확인) / 끄기: compact-window off`);
       }
     }
   } catch { /* settings unreadable — other briefings above still apply */ }

package/src/claude-price.js

@@ -16,10 +16,31 @@ export function sessionCost(totals, model, { env = process.env, now } = {}) {
   return price ? estimateCost(totals, model, { price }) : null;
 }
 
-/** Like estimateCostAcross, plus how many sessions had no price and were left out. */
+/** One priced part per model that spent tokens, or the whole at its one model. */
+function partsByModel(x) {
+  if (!x.modelTotals) return [{ totals: x.totals, model: x.model }];
+  return Object.entries(x.modelTotals).map(([model, totals]) => ({ totals, model }));
+}
+
+/**
+ * What a session's cost is made of: the session itself and each subagent run
+ * it spawned (parser.js attaches them as `subagentRuns`). A run has its own
+ * model, so it is priced on its own instead of at the session's rate, and a
+ * session or run that switched model is split again so each model's tokens
+ * meet that model's rate. `own` marks the parts that are the session itself.
+ */
+export function pricedParts(session) {
+  if (!session) return [];
+  return [
+    ...partsByModel(session).map((part) => ({ ...part, own: true })),
+    ...(session.subagentRuns || []).flatMap(partsByModel),
+  ];
+}
+
+/** Like estimateCostAcross, plus how many priced parts (a session, a subagent run, or one model's share of either) had no price and were left out. */
 export function sessionCostAcross(sessions, opts = {}) {
   let unpriced = 0;
-  const total = estimateCostAcross(sessions, (totals, model) => {
+  const total = estimateCostAcross((sessions || []).flatMap(pricedParts), (totals, model) => {
     const c = sessionCost(totals, model, opts);
     if (!c) unpriced++;
     return c;

package/src/codex-brief.js

@@ -1,10 +1,14 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, renameSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { codexUserDir } from './agent.js';
 import { userDataDir } from './paths.js';
 import { readCodexSnapshot } from './codex-parser.js';
+import { loadCodexModelRules } from './codex-delegation.js';
+import { loadCodexLedger } from './codex-ledger.js';
+import { codexRulesInReview } from './codex-rule-health.js';
 
+const RESET_TOLERANCE_S = 300;
 const hash = (value) => createHash('sha256').update(value).digest('hex');
 const stateDir = (dir) => join(dir, 'codex', hash(codexUserDir()), 'sessions');
 const fresh = (value, now) => {
@@ -45,7 +49,7 @@ function readState(file) {
 }
 
 /** One file per home/session keeps unrelated sessions out of the same dedup state. */
-export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now(), dir = userDataDir() } = {}) {
+export function runCodexBrief({ sessionId, transcriptPath, cwd, root: projectRoot, now = Date.now(), dir = userDataDir() } = {}) {
   if (typeof sessionId !== 'string' || !sessionId) return null;
   const snapshot = readCodexSnapshot(transcriptPath);
   if (!snapshot || (snapshot.sessionId && snapshot.sessionId !== sessionId)) return null;
@@ -54,6 +58,35 @@ export function runCodexBrief({ sessionId, transcriptPath, cwd, now = Date.now()
   const file = join(directory, `${hash(sessionId)}.json`);
   const state = readState(file);
   const active = Array.isArray(state.active) ? state.active.filter((sig) => typeof sig === 'string') : [];
+  // Codex rewrites resets_at by about a second between records, so a limit
+  // already announced for the same window keeps its first signature.
+  for (const issue of issues) {
+    const m = /^limit:(primary|secondary):(\d+(?:\.\d+)?)$/.exec(issue.signature);
+    if (!m) continue;
+    const resetsAt = Number(m[2]);
+    const known = active.find((sig) => {
+      const k = /^limit:(primary|secondary):(\d+(?:\.\d+)?)$/.exec(sig);
+      return k && k[1] === m[1] && Math.abs(Number(k[2]) - resetsAt) <= RESET_TOLERANCE_S;
+    });
+    if (known) issue.signature = known;
+  }
+  // A failing model rule is announced once per session; the lines never block the other warnings.
+  try {
+    // The hook passes the project root its rule matching uses; a prompt sent from
+    // a subdirectory must still see the project's rules.
+    const root = resolve(projectRoot || cwd || snapshot.projectDir || '.');
+    const rules = loadCodexModelRules({ dir });
+    if (rules.length) {
+      const events = Object.values(loadCodexLedger({ dir }).events);
+      for (const { index, rule, health } of codexRulesInReview({ root, rules, events })) {
+        issues.push({ key: 'rule-health', tier: 1,
+          signature: `rule-health:${rule.scope}:${rule.targetRoot ?? ''}:${rule.category}:${rule.from}:${rule.model}:${rule.createdAt ?? ''}`,
+          level: 'warning',
+          message: `Codex model rule #${index} (${rule.category}, ${rule.from} -> ${rule.model}) failed ${health.errs} of ${health.runs} measured runs.`,
+          advice: `Narrow or remove it: sprag delegate rules rm ${index} --agent codex` });
+      }
+    }
+  } catch { /* An unreadable rule file or ledger only skips this line. */ }
   const next = issues.filter((issue) => !active.includes(issue.signature) &&
     !(issue.key === 'context' && issue.tier === 1 && active.includes('context:2')));
   // Missing or stale measurements do not resolve an earlier warning. A fresh

package/src/codex-delegation.js

@@ -54,7 +54,10 @@ export function addCodexModelRule({ category, model, effort, from, scope, root,
   const rules = loadCodexModelRules({ dir });
   const targetRoot = scope === 'project' ? resolve(root) : null;
   const rule = { category, model, effort, from, scope, targetRoot, ...(provider ? { provider } : {}), status: 'active', createdAt: new Date().toISOString() };
-  const old = rules.findIndex((r) => r.category === category && r.from === from && r.scope === scope && r.targetRoot === targetRoot && r.provider === provider);
+  // A rule saved without a provider has no `provider` key, and a caller with
+  // none passes null. Compared as they are, undefined !== null, so re-adding
+  // the same rule stacked a duplicate instead of replacing it.
+  const old = rules.findIndex((r) => r.category === category && r.from === from && r.scope === scope && r.targetRoot === targetRoot && (r.provider ?? null) === (provider ?? null));
   if (old < 0) rules.push(rule); else rules[old] = rule;
   saveRules(rules, dir);
   return rule;
@@ -126,7 +129,8 @@ export function codexRouteHint(payload, opts = {}) {
   try {
     record({ id, parentSessionId: payload?.session_id ?? null, turnId: payload?.turn_id ?? null, via: 'prompt',
       source: 'rule', category: rule.category, scope: rule.scope, from: payload?.model, to: rule.model,
-      provider, effort: rule.effort ?? null, contextTokens: ctx }, { dir: opts.dir });
+      provider, effort: rule.effort ?? null, contextTokens: ctx,
+      targetRoot: rule.targetRoot ?? null, ruleCreatedAt: rule.createdAt ?? null }, { dir: opts.dir });
   } catch { /* Accounting is optional; the hint still applies. */ }
   return `[Sprag model routing] This request matches the approved ${rule.category} rule (route ${id}). `
     + `Spawn one sub-agent with model ${rule.model}${rule.effort ? `, reasoning_effort ${rule.effort}` : ''} and fork_turns "none". `
@@ -160,7 +164,7 @@ function customRole(role, root, home) {
 
 // Kept for Codex versions that do send spawn_agent through PreToolUse; on
 // 0.159.2 the hook never fires for it, so codexRouteHint above is the live path.
-export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules, dir = userDataDir(), record = recordCodexDelegation } = {}) {
+export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd || process.cwd(), home = codexUserDir(), rules: given, dir = userDataDir(), record = recordCodexDelegation } = {}) {
   if (cfg.codex?.delegate !== true) return null;
   const tool = payload?.tool_name?.replace(/^(?:functions|tools)\./, '');
   if (!['spawn_agent', 'Agent'].includes(tool)) return null;
@@ -169,6 +173,9 @@ export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd ||
   const role = input.agent_type || 'default';
   if (!['default', 'worker', 'explorer'].includes(role) || customRole(role, payload.cwd || root, home)) return null;
   const explicit = Object.hasOwn(input, 'model');
+  // An unreadable rule file must not stop the default target or the spawn itself.
+  let rules = given;
+  if (!rules) { try { rules = loadCodexModelRules({ dir }); } catch { rules = []; } }
   const provider = payload.model_provider || codexProviderName({ home });
   const rule = explicit ? null : matchCodexModelRule(input.message, { model: payload.model, provider, root, rules });
   const target = rule || (!explicit && cfg.codex?.delegateTarget);
@@ -184,7 +191,8 @@ export function codexDelegationTool(payload, { cfg = {}, root = payload?.cwd ||
       try {
         record({ id, parentSessionId: typeof payload.session_id === 'string' ? payload.session_id : null,
           source: rule ? 'rule' : 'default', category: rule?.category ?? null, scope: rule?.scope ?? null,
-          from: payload.model, to: target.model, provider, effort: updatedInput.reasoning_effort ?? null }, { dir });
+          from: payload.model, to: target.model, provider, effort: updatedInput.reasoning_effort ?? null,
+          ...(rule ? { targetRoot: rule.targetRoot ?? null, ruleCreatedAt: rule.createdAt ?? null } : {}) }, { dir });
         routeLine = `\n<!-- sprag:codex:route id=${id} -->`;
       } catch { /* Accounting is optional; the route itself still applies. */ }
     }

package/src/codex-harness.js

@@ -14,14 +14,22 @@ const sections = [
   ['Default Safe Path', 'Ask before destructive or external actions unless already authorized. Proceed with reads, local edits, and tests within the granted permissions.'],
 ];
 
+const scopeDir = (root, scope) => (scope === 'global' ? codexUserDir() : root);
+
 export function codexHarnessPaths(root, scope = 'project') {
-  const dir = scope === 'global' ? codexUserDir() : root;
+  const dir = scopeDir(root, scope);
   // Codex reads the override instead of AGENTS.md when it is non-empty.
   const override = join(dir, 'AGENTS.override.md');
   const file = existsSync(override) && readFileSync(override, 'utf8').trim() ? override : join(dir, 'AGENTS.md');
   return { file, ratchet: scope === 'global' ? join(dir, 'ratchet.md') : join(dir, '.codex', 'ratchet.md') };
 }
 
+/** Every instruction file of a scope that init may have written to, active or not. */
+function harnessFiles(root, scope) {
+  const dir = scopeDir(root, scope);
+  return [join(dir, 'AGENTS.override.md'), join(dir, 'AGENTS.md')];
+}
+
 export function codexHarnessBlock() {
   return `${CODEX_BEGIN}\n## Sprag Harness\n\n${sections.map(([name, text], i) => `### ${i + 1}. ${name}\n${text}`).join('\n\n')}\n\nRead the global and project Codex ratchet files before working when present. Run \`sprag harness list --agent codex --global\` and \`sprag harness list --agent codex --project\` to retrieve them. These are instructions, not Claude-style @ imports.\nUse \`sprag doc2md <file> --agent codex\` before reading PDF, Office, or Figma documents. Delegate only through available Codex tools and configured roles; do not assume Claude model names or Task/Agent arguments. A [Sprag model routing] note on a request means the user has asked for that request to be delegated: spawn the sub-agent it describes (its model, reasoning_effort, fork_turns "none", and a self-contained message ending with the route line it gives), wait for it to finish instead of doing the same task yourself, then verify the result before replying.\n${CODEX_END}\n`;
 }
@@ -40,8 +48,11 @@ export function initCodexHarness({ root, scope = 'project' }) {
   const existing = existsSync(paths.file) ? readFileSync(paths.file, 'utf8') : '';
   const span = range(existing);
   const block = codexHarnessBlock();
+  // Trailing newlines are dropped before the separator is added, so the gap
+  // above the block is always one blank line however the file ended.
+  const body = existing.replace(/\n+$/, '');
   const next = span ? existing.slice(0, span[0]) + block.trimEnd() + existing.slice(span[1])
-    : existing + (existing ? '\n\n' : '') + block;
+    : body + (body ? '\n\n' : '') + block;
   mkdirSync(dirname(paths.file), { recursive: true });
   if (next !== existing) {
     if (existing) writeFileSync(`${paths.file}.bak-${Date.now()}`, existing);
@@ -54,15 +65,38 @@ export function initCodexHarness({ root, scope = 'project' }) {
   return paths;
 }
 
+/**
+ * The file without the block, and without the blank lines init put around it.
+ * Cutting the block alone left those behind, so each install and uninstall
+ * added three more.
+ */
+function withoutBlock(text, [begin, end]) {
+  const before = text.slice(0, begin).replace(/\n+$/, '');
+  const after = text.slice(end).replace(/^\n+/, '');
+  if (!before) return after;
+  return after ? `${before}\n\n${after}` : `${before}\n`;
+}
+
+/**
+ * Removes the block from every file of the scope that holds one. The active
+ * file alone is not enough: init writes AGENTS.md, and an AGENTS.override.md
+ * created afterwards becomes the active file while the block stays in the
+ * other one, where a later uninit never looked.
+ */
 export function uninitCodexHarness({ root, scope = 'project' }) {
   const { file } = codexHarnessPaths(root, scope);
-  if (!existsSync(file)) return { file, removed: false };
-  const existing = readFileSync(file, 'utf8');
-  const span = range(existing);
-  if (!span) return { file, removed: false };
-  writeFileSync(`${file}.bak-${Date.now()}`, existing);
-  writeFileSync(file, existing.slice(0, span[0]) + existing.slice(span[1]));
-  return { file, removed: true };
+  const cleaned = [];
+  for (const candidate of harnessFiles(root, scope)) {
+    if (!existsSync(candidate)) continue;
+    const existing = readFileSync(candidate, 'utf8');
+    const span = range(existing);
+    if (!span) continue;
+    writeFileSync(`${candidate}.bak-${Date.now()}`, existing);
+    writeFileSync(candidate, withoutBlock(existing, span));
+    cleaned.push(candidate);
+  }
+  if (!cleaned.length) return { file, removed: false };
+  return { file: cleaned.includes(file) ? file : cleaned[0], removed: true, ...(cleaned.length > 1 ? { files: cleaned } : {}) };
 }
 
 export function codexHarnessStatus({ root, scope = 'project' }) {