sprag-cli 3.56.0 → 3.58.0

package/README.ko.md

@@ -36,50 +36,25 @@ Sprag는 Claude Code와 Codex가 남기는 세션 기록을 읽어 반복 실패
 npm i -g sprag-cli   # 예전 이름 claude-token-saver 와 같은 패키지입니다
 ```
 
-## Codex
+## 설치하면 바로 달라지는 것
 
-Codex 기본 훅과 `AGENTS.md` 하네스, 범위별 래칫 규칙,
-한국어 검사, 프롬프트의 문서 경로 자동 변환, 로컬 토큰 보고서를 사용할 수 있습니다.
-Codex가 설치되어 있으면 `npm i -g sprag-cli` 하나로 Codex도 설정하고, 추천 룰을 묻지 않고
-전역으로 등록합니다(단계마다 확인하려면 `sprag install --manual`). Claude Code를 건드리지 않고
-Codex만 쓴다면 다음과 같이 설치하십시오.
+1. `npm i -g sprag-cli` 를 실행합니다. 훅과 상태줄, 추천 룰이 모든 프로젝트에
+   설정되므로 프로젝트마다 따로 설정할 것은 없습니다. 이미 쓰던 상태줄이 있으면
+   둘 다 표시할지, 교체할지, 그대로 둘지 설치 중에 묻습니다.
+2. 아무 프로젝트에서나 Claude Code를 열고 평소처럼 일합니다.
+3. 상태줄을 봅니다. 세션에서 쓴 금액과 아낀 금액이 나오고, 캐시나 컨텍스트,
+   사용량 한도에 문제가 생기면 경고 칩이 줄 맨 앞에 나타납니다.
 
-```bash
-npm i -g sprag-cli --ignore-scripts
-sprag install --agent codex
-sprag --agent codex --days 7
-sprag panel --agent codex  # 별도 터미널에서 실시간 패널 실행
-sprag --statusline --agent codex --text
-sprag doctor --agent codex  # 문제가 생겼을 때만
-sprag route-scan --agent codex
-sprag seed --agent codex
+```
+🔀 Routing saved $44.67  |  opus→sonnet 59× $39.75 · opus→haiku 10× $4.92
+🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 🅷 5/5 · 📦 Ctx 47% of 1M
 ```
 
-설치 후 Codex의 `/hooks`에서 새 훅을 검토하고 신뢰해야 실행됩니다. Codex가 요구하는
-절차입니다. 명령의 기본 대상은 여전히 Claude Code이며, `--agent codex`를 붙이면 Codex를 고릅니다. Codex에서도 세션 브리핑, 경고 이력, 인수인계
-파일을 지원합니다. `sprag delegate on --agent codex`로 모델 위임과 하위 에이전트
-지침 전달을 켤 수 있습니다. 상태 표시는 Sprag 터미널 상태줄과 패널을 사용하십시오.
-Codex 기본 상태줄은 셸 명령을 실행하지 않습니다. 반복된 단순 작업은 위임 후보로,
-반복된 도구 실패는 래칫 후보로 제안합니다. 규칙을 등록하려면 사용자의 승인이 필요하며,
-`seed`로 호환되는 기본 규칙을 선택할 수도 있습니다.
-`sprag route-scan savings --agent codex`는 Sprag가 위임한 실행만 집계하고,
-일치하는 LiteLLM 단가가 있을 때 예상 차액을 계산합니다. 청구 금액을 측정한 값은 아니며,
-단가를 확인하지 못하면 `n/a`로 표시합니다. Codex 문서 누계는 Claude 추정치와 분리합니다.
-아래의 기존 절감 수치는 Claude Code 기록이며 Codex 벤치마크가 아닙니다.
-[Codex 지원 범위와 제한](https://sprag.io/docs/ko/codex/)이나
-`sprag capabilities --agent codex`에서 기능별 지원 여부를 확인하십시오.
-
-| 기능 | Claude Code | Codex |
-|---|---|---|
-| 세션 지침 | `CLAUDE.md`와 훅 | `AGENTS.md`와 기본 훅 |
-| 실시간 상태 | 기본 상태줄에 명령 등록 | 별도 패널 또는 tmux 구성 |
-| 규칙 후보 | Claude 기록과 모델 등급 프리셋 | Codex 기록과 호환 래칫 프리셋 |
-| 모델 위임 | Haiku·Sonnet 등급 규칙 | 공급자 모델 ID와 범위별 규칙 |
-| 위임 원장 | Claude 실행별 예상 차액 | LiteLLM 단가와 하위 실행별 예상 차액 |
-
-두 연동을 함께 설치할 수 있습니다. `--agent codex`를 붙이지 않으면 기존 Claude 동작을 유지합니다.
+Sprag는 사용자가 고른 모델을 바꾸지 않습니다. 분석은 로컬 세션 기록만 읽으며,
+추가 모델 호출이나 API 키가 필요하지 않습니다. `sprag uninstall` 은 설치 때
+추가한 것을 모두 지우고, 함께 표시하던 기존 상태줄을 되돌려 놓습니다.
 
-![statusline 예시. 첫 줄은 라우팅 절감액, 둘째 줄은 문서 변환 절감액, 셋째 줄은 진단 칩입니다](https://raw.githubusercontent.com/rootstudioyaml/sprag/main/docs/statusline.png)
+Codex를 쓴다면 아래 [Codex](#codex) 절을 보십시오.
 
 ## 작동 방식
 
@@ -181,11 +156,56 @@ JetBrains IDE 내장 터미널에서는 이모지 대신 한 칸 글리프로
 
 래칫 규칙과 위임 규칙은 늘어나는 방식이 다릅니다. 래칫 규칙은 사람이 저지른 실수에서 나오므로 계속 늘어납니다. 위임 규칙은 멈춥니다. 기준이 알아보는 작업 유형이 정해져 있어서, 유형마다 규칙이 하나 생기면 더 승격할 것이 없습니다.
 
+## Codex
+
+Codex 기본 훅과 `AGENTS.md` 하네스, 범위별 래칫 규칙,
+한국어 검사, 프롬프트의 문서 경로 자동 변환, 로컬 토큰 보고서를 사용할 수 있습니다.
+Codex가 설치되어 있으면 `npm i -g sprag-cli` 하나로 Codex도 설정하고, 추천 룰을 묻지 않고
+전역으로 등록합니다(단계마다 확인하려면 `sprag install --manual`). Claude Code를 건드리지 않고
+Codex만 쓴다면 다음과 같이 설치하십시오.
+
+```bash
+npm i -g sprag-cli --ignore-scripts
+sprag install --agent codex
+sprag --agent codex --days 7
+sprag panel --agent codex  # 별도 터미널에서 실시간 패널 실행
+sprag --statusline --agent codex --text
+sprag doctor --agent codex  # 문제가 생겼을 때만
+sprag route-scan --agent codex
+sprag seed --agent codex
+```
+
+설치 후 Codex의 `/hooks`에서 새 훅을 검토하고 신뢰해야 실행됩니다. Codex가 요구하는
+절차입니다. 명령의 기본 대상은 여전히 Claude Code이며, `--agent codex`를 붙이면 Codex를 고릅니다. Codex에서도 세션 브리핑, 경고 이력, 인수인계
+파일을 지원합니다. `sprag delegate on --agent codex`로 모델 위임과 하위 에이전트
+지침 전달을 켤 수 있습니다. 상태 표시는 Sprag 터미널 상태줄과 패널을 사용하십시오.
+Codex 기본 상태줄은 셸 명령을 실행하지 않습니다. 반복된 단순 작업은 위임 후보로,
+반복된 도구 실패는 래칫 후보로 제안합니다. 규칙을 등록하려면 사용자의 승인이 필요하며,
+`seed`로 호환되는 기본 규칙을 선택할 수도 있습니다.
+`sprag route-scan savings --agent codex`는 Sprag가 위임한 실행만 집계하고,
+일치하는 LiteLLM 단가가 있을 때 예상 차액을 계산합니다. 청구 금액을 측정한 값은 아니며,
+단가를 확인하지 못하면 `n/a`로 표시합니다. Codex 문서 누계는 Claude 추정치와 분리합니다.
+아래의 기존 절감 수치는 Claude Code 기록이며 Codex 벤치마크가 아닙니다.
+[Codex 지원 범위와 제한](https://sprag.io/docs/ko/codex/)이나
+`sprag capabilities --agent codex`에서 기능별 지원 여부를 확인하십시오.
+
+| 기능 | Claude Code | Codex |
+|---|---|---|
+| 세션 지침 | `CLAUDE.md`와 훅 | `AGENTS.md`와 기본 훅 |
+| 실시간 상태 | 기본 상태줄에 명령 등록 | 별도 패널 또는 tmux 구성 |
+| 규칙 후보 | Claude 기록과 모델 등급 프리셋 | Codex 기록과 호환 래칫 프리셋 |
+| 모델 위임 | Haiku·Sonnet 등급 규칙 | 공급자 모델 ID와 범위별 규칙 |
+| 위임 원장 | Claude 실행별 예상 차액 | LiteLLM 단가와 하위 실행별 예상 차액 |
+
+두 연동을 함께 설치할 수 있습니다. `--agent codex`를 붙이지 않으면 기존 Claude 동작을 유지합니다.
+
+![statusline 예시. 첫 줄은 라우팅 절감액, 둘째 줄은 문서 변환 절감액, 셋째 줄은 진단 칩입니다](https://raw.githubusercontent.com/rootstudioyaml/sprag/main/docs/statusline.png)
+
 ## 자주 쓰는 명령
 
 | 명령 | 하는 일 |
 |---|---|
-| `sprag` | 최근 1일 진단 리포트 |
+| `sprag` | 최근 30일 진단 리포트 |
 | `sprag handoff` | 한도에 막히기 전에 작업 상태를 백업 |
 | `sprag route-scan` | 내 기록에서 위임 후보 찾기 (LLM 호출 0회) |
 | `sprag route-scan savings` | 라우팅 절감 원장 조회 |

package/README.md

@@ -48,51 +48,27 @@ existing credentials. The CLI requires Node.js 18+ and one TOML parser dependenc
 npm i -g sprag-cli   # Claude Code, plus Codex when it is installed
 ```
 
-## Codex
+## After you install
 
-Native hooks, an `AGENTS.md` harness, scoped ratchet rules, Korean lint,
-document conversion, token reports, and a session-bound companion panel.
-`npm i -g sprag-cli` sets Codex up too when it is installed, with the rule
-presets registered globally and nothing asked (`sprag install --manual` asks at
-each step). For a Codex-only install that leaves Claude Code alone:
+1. Run `npm i -g sprag-cli`. Hooks, the statusline and the starter rules are set
+   up for every project; there is nothing to configure per project. If you
+   already have a statusline, the install asks whether to show both, replace
+   yours, or keep yours.
+2. Open Claude Code in any project and work as usual.
+3. Watch the statusline. It shows what the session spent and saved, and a
+   warning chip leads the line when the cache, the context or a rate limit
+   needs attention:
 
-```bash
-npm i -g sprag-cli --ignore-scripts
-sprag install --agent codex
-sprag --agent codex --days 7
-sprag panel --agent codex  # live companion in a separate terminal
-sprag --statusline --agent codex --text
-sprag doctor --agent codex  # troubleshooting only
-sprag route-scan --agent codex
-sprag seed --agent codex
+```
+🔀 Routing saved $44.67  |  opus→sonnet 59× $39.75 · opus→haiku 10× $4.92
+🧠 Cache hit 98.8% · ⏳ Cache expires 59:46 · 🅷 5/5 · 📦 Ctx 47% of 1M
 ```
 
-Review and trust the new hooks in Codex's `/hooks` menu; Codex requires that
-step. Commands still default to Claude Code; add `--agent codex` to pick Codex.
-Codex also supports session briefings, warning history, handoffs, and opt-in
-model routing and subagent guidance (`sprag delegate on --agent codex`). The native Codex footer
-does not accept shell commands; Sprag provides a terminal statusline and panel.
-Recurring simple turns become route candidates; repeated tool failures become
-ratchet candidates. Both require your approval before a rule is registered.
-`seed` offers compatible starter rules with separate Codex decisions.
-`sprag route-scan savings --agent codex` records only Sprag-routed child runs
-and estimates their price difference when matching LiteLLM prices are available.
-It is not a billing measurement. Unknown prices remain `n/a`, and Codex document
-counts stay separate from Claude estimates. The historical dollar figures below
-are from Claude Code, not a Codex benchmark. See [Codex support and limits](https://sprag.io/docs/codex/), or run
-`sprag capabilities --agent codex` for the support matrix.
-
-| Workflow | Claude Code | Codex |
-|---|---|---|
-| Session instructions | `CLAUDE.md` and hooks | `AGENTS.md` and native hooks |
-| Live telemetry | Native statusline command | Companion panel or tmux layout |
-| Rule candidates | Claude transcripts and tier presets | Codex rollouts and compatible ratchet presets |
-| Model routing | Haiku/Sonnet tier rules | Explicit provider model IDs and scoped rules |
-| Routing ledger | Claude run estimates | Attributed child estimates with LiteLLM prices |
-
-Both integrations coexist. Commands without `--agent codex` retain Claude behavior.
+Sprag never swaps the model you picked. Analysis reads your local session
+logs only, with no extra model calls and no API key. `sprag uninstall` removes
+everything it added and restores a statusline it merged with.
 
-![statusline example: routing savings on row 1, document conversion savings on row 2, diagnostics on row 3](https://raw.githubusercontent.com/rootstudioyaml/sprag/main/docs/statusline.png)
+Using Codex? See [Codex](#codex) below.
 
 ## How it works
 
@@ -225,11 +201,57 @@ The two counts grow differently. Ratchet rules come from mistakes a person made,
 so they keep coming. Delegation rules stop: the criteria recognize a fixed set of
 work types, and once each has a rule there is nothing left to promote.
 
+## Codex
+
+Native hooks, an `AGENTS.md` harness, scoped ratchet rules, Korean lint,
+document conversion, token reports, and a session-bound companion panel.
+`npm i -g sprag-cli` sets Codex up too when it is installed, with the rule
+presets registered globally and nothing asked (`sprag install --manual` asks at
+each step). For a Codex-only install that leaves Claude Code alone:
+
+```bash
+npm i -g sprag-cli --ignore-scripts
+sprag install --agent codex
+sprag --agent codex --days 7
+sprag panel --agent codex  # live companion in a separate terminal
+sprag --statusline --agent codex --text
+sprag doctor --agent codex  # troubleshooting only
+sprag route-scan --agent codex
+sprag seed --agent codex
+```
+
+Review and trust the new hooks in Codex's `/hooks` menu; Codex requires that
+step. Commands still default to Claude Code; add `--agent codex` to pick Codex.
+Codex also supports session briefings, warning history, handoffs, and opt-in
+model routing and subagent guidance (`sprag delegate on --agent codex`). The native Codex footer
+does not accept shell commands; Sprag provides a terminal statusline and panel.
+Recurring simple turns become route candidates; repeated tool failures become
+ratchet candidates. Both require your approval before a rule is registered.
+`seed` offers compatible starter rules with separate Codex decisions.
+`sprag route-scan savings --agent codex` records only Sprag-routed child runs
+and estimates their price difference when matching LiteLLM prices are available.
+It is not a billing measurement. Unknown prices remain `n/a`, and Codex document
+counts stay separate from Claude estimates. The historical dollar figures below
+are from Claude Code, not a Codex benchmark. See [Codex support and limits](https://sprag.io/docs/codex/), or run
+`sprag capabilities --agent codex` for the support matrix.
+
+| Workflow | Claude Code | Codex |
+|---|---|---|
+| Session instructions | `CLAUDE.md` and hooks | `AGENTS.md` and native hooks |
+| Live telemetry | Native statusline command | Companion panel or tmux layout |
+| Rule candidates | Claude transcripts and tier presets | Codex rollouts and compatible ratchet presets |
+| Model routing | Haiku/Sonnet tier rules | Explicit provider model IDs and scoped rules |
+| Routing ledger | Claude run estimates | Attributed child estimates with LiteLLM prices |
+
+Both integrations coexist. Commands without `--agent codex` retain Claude behavior.
+
+![statusline example: routing savings on row 1, document conversion savings on row 2, diagnostics on row 3](https://raw.githubusercontent.com/rootstudioyaml/sprag/main/docs/statusline.png)
+
 ## Day-to-day commands
 
 | 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,16 +575,26 @@ 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');
           persistSnapshot({ caps, model });
         } catch (e) { debug('caps-cache:persist', e); }
       }
-      console.log(formatNoSession(
+      const { withBaseStatusline } = await import('../src/statusline-base.js');
+      console.log(withBaseStatusline(formatNoSession(
         { caps, model, effort, windowLabel, version: PKG_VERSION, update: readUpdateChip() },
         { color: colorOk, mode: labelMode },
-      ));
+      )));
       return;
     }
     // JSON mode stays JSON. A caller that asked for machine-readable output
@@ -618,6 +651,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 +773,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 +797,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,9 +899,13 @@ async function main() {
     });
   } else {
     const { formatReport } = await import('../src/formatters/table.js');
-    output = formatReport(data);
+    output = formatReport(data, { color: tableColor() });
   }
 
+  if (format === 'statusline') {
+    const { withBaseStatusline } = await import('../src/statusline-base.js');
+    output = withBaseStatusline(output);
+  }
   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,7 +1,7 @@
 {
   "name": "sprag-cli",
-  "version": "3.56.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.",
+  "version": "3.58.0",
+  "description": "Lower your Claude Code bill without changing how you work: simple tasks go to cheaper models, documents go in as compact Markdown, and the statusline shows spend and savings live. Works with Codex too.",
   "type": "module",
   "bin": {
     "sprag": "bin/cli.js",
@@ -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",
@@ -33,34 +33,22 @@
     "node": ">=18"
   },
   "keywords": [
-    "sprag",
-    "ratchet",
-    "harness",
-    "ai-agent",
-    "claude",
     "claude-code",
-    "codex",
-    "openai-codex",
-    "agents-md",
+    "claude",
     "anthropic",
-    "model-routing",
-    "llm-router",
-    "delegation",
-    "subagent",
-    "haiku",
-    "cost-savings",
+    "codex",
+    "token-usage",
     "token-saver",
     "reduce-tokens",
-    "token-usage",
-    "prompt-caching",
-    "cache",
-    "statusline",
-    "cli",
-    "1m-context",
-    "claude-code-statusline",
+    "cost-savings",
     "claude-code-cost",
-    "model-fitting",
-    "agent-harness"
+    "claude-code-statusline",
+    "statusline",
+    "model-routing",
+    "subagent",
+    "prompt-caching",
+    "haiku",
+    "cli"
   ],
   "license": "Apache-2.0",
   "repository": {

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`));
 }