sprag-cli 3.58.1 → 3.59.0

package/bin/cli.js

@@ -106,7 +106,7 @@ function tableColor() {
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean', 'cohesion',
   'doc2md', 'delegate', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
-  'seed', 'litellm-budget', 'profile-map', 'feedback',
+  'seed', 'litellm-budget', 'profile-map', 'feedback', 'saved',
 ]);
 
 const USAGE = `sprag — Claude Code and Codex agent harness
@@ -148,6 +148,7 @@ Usage:
   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 saved [reset|undo] show, reset or restore the saved-money counters (--agent codex for Codex)
   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
@@ -305,6 +306,12 @@ async function main() {
     return (await import('../src/commands/seed.js')).run({ args, hasFlag });
   }
 
+  // Subcommand: saved — stopwatch reset for the lifetime "saved" counters.
+  //   sprag saved | saved reset [routing|doc2md|all] | saved undo
+  if (args[0] === 'saved') {
+    return (await import('../src/commands/saved.js')).run({ args, hasFlag });
+  }
+
   // Subcommand: harness — manage the project's CLAUDE.md harness rules.
   //   sprag harness init       # write CLAUDE.md (5 sections) + ratchet.md
   //   sprag harness uninit     # remove harness block from CLAUDE.md (backup kept)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sprag-cli",
-  "version": "3.58.1",
+  "version": "3.59.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": {

package/src/codex-doc2md-ledger.js

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, realpathSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, realpathSync, statSync } from 'node:fs';
 import { extname, join, resolve } from 'node:path';
 import { codexUserDir } from './agent.js';
 import { userDataDir } from './paths.js';
+import { readResetMarks, isBeforeReset } from './saved-reset.cjs';
 
 const hash = (value) => createHash('sha256').update(value).digest('hex');
 const ledgerDir = ({ home = codexUserDir(), dir = userDataDir() } = {}) => join(dir, 'codex-doc2md', hash(resolve(home)));
@@ -26,13 +27,17 @@ export function recordCodexDocument(source, result, opts) {
   } catch { /* Accounting must not prevent document conversion. */ }
 }
 
+// Records carry no timestamp field, so the reset mark is compared with the
+// file's mtime. A source converted again rewrites its record and counts as new.
 export function codexDocumentTotals(opts) {
-  const total = { docs: 0, byExt: [], scope: 'codex-total' };
+  const since = readResetMarks(opts?.dir ?? userDataDir())['codex-docs'];
+  const total = { docs: 0, byExt: [], scope: 'codex-total', since };
   const byExt = new Map();
   try {
     const dir = ledgerDir(opts);
     for (const file of readdirSync(dir).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))) {
       try {
+        if (since !== null && isBeforeReset(statSync(join(dir, file)).mtimeMs, since)) continue;
         const event = JSON.parse(readFileSync(join(dir, file), 'utf8'));
         if (event?.version !== 1 || !['pdf', 'pptx', 'xlsx', 'xls', 'docx', 'fig'].includes(event.ext)) continue;
         total.docs++;

package/src/codex-ledger.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { userDataDir } from './paths.js';
 import { roundUsd } from './savings-ledger.js';
+import { readResetMarks, isBeforeReset } from './saved-reset.cjs';
 import { discoverCodexSessionFiles, parseCodexTurns } from './codex-parser.js';
 import { codexRunCost, codexPriceBook, readCodexPrices } from './codex-cache-policy.js';
 
@@ -262,10 +263,15 @@ export async function refreshCodexLedger({ dir = userDataDir(), home, now = Date
   return ledger;
 }
 
-/** Signed totals over priced runs; unpriced runs are counted, never summed as zero. */
+/**
+ * Signed totals over priced runs; unpriced runs are counted, never summed as zero.
+ * Runs before the `codex-routing` reset mark are left out of every figure,
+ * `runs` and `priced` included; `since` reports the mark.
+ */
 export function codexRoutingSavedTotals({ dir = userDataDir(), now = Date.now() } = {}) {
-  const events = Object.values(loadCodexLedger({ dir }).events);
-  const totals = { week: 0, month: 0, total: 0, runs: events.length, priced: 0 };
+  const since = readResetMarks(dir)['codex-routing'];
+  const events = Object.values(loadCodexLedger({ dir }).events).filter((e) => !isBeforeReset(e.ts, since));
+  const totals = { week: 0, month: 0, total: 0, runs: events.length, priced: 0, since };
   for (const e of events) {
     if (!Number.isFinite(e.usd)) continue;
     totals.priced++;

package/src/commands/codex.js

@@ -23,6 +23,7 @@ Usage: sprag <command> --agent codex [options]
   brief [on|off|status]          Current warnings or prompt-briefing preference
   last / history                Context/rate-limit warnings and handoffs; --days, --session, --project
   handoff [--cwd path]           Write Git state and Codex usage to HANDOFF-*.md
+  saved [reset|undo]             Show, reset or restore the saved-money counters
   delegate on|off|status         Native model routing and SubagentStart guidance
   delegate model <model>         Default target for spawns without an explicit model
   delegate rules                Codex-only category rules; add/rm with explicit scope
@@ -144,6 +145,7 @@ export async function run({ args, version }) {
     return;
   }
   if (cmd === 'delegate') return (await import('./codex-delegate.js')).run({ args, getArg, hasFlag, root });
+  if (cmd === 'saved') return (await import('./saved.js')).run({ args, hasFlag, agent: 'codex' });
   if (cmd === 'seed') return (await import('./seed.js')).run({ args, hasFlag, agent: 'codex', root });
   if (cmd === 'route-scan') {
     const rs = await import('../codex-route-scan.js');

package/src/commands/route-scan.js

@@ -56,9 +56,22 @@ export async function run({ args, hasFlag, numArg }) {
     // which model actually ran it.
     if (args[1] === 'savings') {
       const { loadLedger, delegationSavedTotals } = await import('../savings-ledger.js');
+      // Runs from before `sprag saved reset` are kept in the ledger but not listed.
+      const { readResetMarks, isBeforeReset } = await import('../saved-reset.cjs');
+      const { userDataDir } = await import('../paths.js');
+      const since = readResetMarks(userDataDir()).routing;
       const events = Object.entries(loadLedger().events)
         .map(([key, e]) => ({ key, ...e }))
+        .filter((e) => !isBeforeReset(e.ts, since))
         .sort((a, b) => b.ts - a.ts);
+      if (events.length === 0 && since !== null) {
+        // After a reset an empty list is the expected state, not a setup gap.
+        const at = new Date(since).toLocaleString(lang === 'ko' ? 'ko-KR' : 'en-US');
+        console.log(lang === 'ko'
+          ? `${at}에 카운터를 초기화한 뒤로 기록된 라우팅 절감이 아직 없습니다. 되돌리려면 \`sprag saved undo\` 를 실행하십시오.`
+          : `No routing savings recorded since the counter was reset at ${at}. Run \`sprag saved undo\` to restore it.`);
+        return;
+      }
       if (events.length === 0) {
         console.log(lang === 'ko'
           ? '기록된 라우팅 절감 없음. 승격된 룰이 실제로 위임을 일으킨 뒤 `route-scan --refresh` 를 돌리면 채워집니다.'
@@ -72,6 +85,12 @@ export async function run({ args, hasFlag, numArg }) {
       console.log(lang === 'ko'
         ? `🔀 라우팅 절감 누적 ${money(t.total)}  (최근 7일 ${money(t.week)} · 30일 ${money(t.month)})`
         : `🔀 Routing saved, lifetime ${money(t.total)}  (last 7d ${money(t.week)} · 30d ${money(t.month)})`);
+      if (since !== null) {
+        const at = new Date(since).toLocaleString(lang === 'ko' ? 'ko-KR' : 'en-US');
+        console.log(lang === 'ko'
+          ? `  ${at}에 카운터를 초기화했습니다. 이후 기록만 집계합니다.`
+          : `  Counter reset at ${at}; only later runs are counted.`);
+      }
 
       // Per model-pair rollup first: the "what moved where" question is what
       // this view exists to answer, and it is easier to read than the log.

package/src/commands/saved.js

@@ -0,0 +1,115 @@
+/**
+ * Subcommand: saved — a stopwatch reset for the lifetime "saved" counters.
+ *
+ *   sprag saved                              # totals since the last reset
+ *   sprag saved reset [routing|doc2md|all]   # start counting from now
+ *   sprag saved undo                         # put the previous counters back
+ *   (add --agent codex for the Codex counters: codex-routing, codex-docs)
+ *
+ * Nothing is deleted. A reset only records a timestamp, and the totals count
+ * events from that moment on; see src/saved-reset.cjs.
+ */
+
+const SCOPE_SETS = {
+  claude: ['routing', 'doc2md'],
+  codex: ['codex-routing', 'codex-docs'],
+};
+
+/** Totals since each scope's mark: { usd } for money counters, { docs } for the Codex document counter. */
+async function currentTotals(scope, dir) {
+  if (scope === 'routing') {
+    const { delegationSavedTotals } = await import('../savings-ledger.js');
+    return { usd: delegationSavedTotals(Date.now(), dir).total };
+  }
+  if (scope === 'doc2md') {
+    const { doc2mdSavedTotals } = await import('../doc2md-ledger.cjs');
+    return { usd: doc2mdSavedTotals(dir).total };
+  }
+  if (scope === 'codex-routing') {
+    const { codexRoutingSavedTotals } = await import('../codex-ledger.js');
+    return { usd: codexRoutingSavedTotals({ dir }).total };
+  }
+  const { codexDocumentTotals } = await import('../codex-doc2md-ledger.js');
+  return { docs: codexDocumentTotals({ dir }).docs };
+}
+
+export async function run({ args, hasFlag, agent = 'claude', dir: dirArg }) {
+  const { userLanguage } = await import('../config.js');
+  const { userDataDir } = await import('../paths.js');
+  const { readResetMarks, resetSaved, undoReset } = await import('../saved-reset.cjs');
+  const ko = userLanguage() === 'ko';
+  const dir = dirArg || userDataDir();
+  const scopes = SCOPE_SETS[agent === 'codex' ? 'codex' : 'claude'];
+  const suffix = agent === 'codex' ? ' --agent codex' : '';
+
+  const money = (v) => (v < 0 ? `-$${(-v).toFixed(2)}` : `$${v.toFixed(2)}`);
+  const fmtTotal = (t) => (t.docs !== undefined ? (ko ? `${t.docs}건` : `${t.docs} doc(s)`) : money(t.usd));
+  const fmtTime = (ms) => new Date(ms).toLocaleString(ko ? 'ko-KR' : 'en-US');
+  const label = (scope) => ({
+    routing: ko ? '라우팅 절감' : 'Routing saved',
+    doc2md: ko ? '문서 변환 절감' : 'Document conversion saved',
+    'codex-routing': ko ? 'Codex 라우팅 절감' : 'Codex routing saved',
+    'codex-docs': ko ? 'Codex 문서 변환' : 'Codex documents converted',
+  })[scope];
+
+  const sub = args[1];
+
+  if (sub === undefined) {
+    const marks = readResetMarks(dir);
+    for (const s of scopes) {
+      const t = await currentTotals(s, dir);
+      const since = marks[s] === null
+        ? (ko ? '초기화한 적 없음' : 'not reset')
+        : (ko ? `${fmtTime(marks[s])} 이후` : `since ${fmtTime(marks[s])}`);
+      console.log(`${label(s)}: ${fmtTotal(t)} (${since})`);
+    }
+    return;
+  }
+
+  if (sub === 'reset') {
+    const arg = args[2] || 'all';
+    const base = agent === 'codex' ? { routing: 'codex-routing', doc2md: 'codex-docs' } : { routing: 'routing', doc2md: 'doc2md' };
+    let targets;
+    if (arg === 'all') targets = scopes;
+    else if (scopes.includes(arg)) targets = [arg];
+    else if (base[arg]) targets = [base[arg]];
+    else {
+      console.error(ko
+        ? `알 수 없는 범위입니다: ${arg}. 사용할 수 있는 범위는 ${scopes.join(', ')}, all 입니다.`
+        : `Unknown scope: ${arg}. Valid scopes are ${scopes.join(', ')}, all.`);
+      process.exit(1);
+    }
+    const before = {};
+    for (const s of targets) before[s] = await currentTotals(s, dir);
+    resetSaved(targets, { dir });
+    for (const s of targets) {
+      console.log(ko
+        ? `${label(s)} 카운터를 0으로 초기화했습니다. 이전 합계는 ${fmtTotal(before[s])}입니다.`
+        : `Reset the ${label(s)} counter to zero. The previous total was ${fmtTotal(before[s])}.`);
+    }
+    console.log(ko
+      ? `원장 기록은 지우지 않았습니다. \`sprag saved undo${suffix}\`로 되돌릴 수 있습니다.`
+      : `No ledger data was deleted. Run \`sprag saved undo${suffix}\` to restore the previous counters.`);
+    return;
+  }
+
+  if (sub === 'undo') {
+    const undone = undoReset({ dir });
+    if (!undone) {
+      console.log(ko ? '되돌릴 초기화 기록이 없습니다.' : 'There is no reset to undo.');
+      return;
+    }
+    for (const s of undone.scopes) {
+      const t = await currentTotals(s, dir);
+      console.log(ko
+        ? `${label(s)} 카운터를 되돌렸습니다. 현재 합계는 ${fmtTotal(t)}입니다.`
+        : `Restored the ${label(s)} counter. The total is now ${fmtTotal(t)}.`);
+    }
+    return;
+  }
+
+  console.error(ko
+    ? `알 수 없는 하위 명령입니다: ${sub}. 사용법은 sprag saved [reset|undo] 입니다.`
+    : `Unknown subcommand: ${sub}. Usage: sprag saved [reset|undo].`);
+  process.exit(1);
+}

package/src/doc2md-ledger.cjs

@@ -69,6 +69,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { readResetMarks, isBeforeReset } = require('./saved-reset.cjs');
 
 const WEEK_MS = 7 * 24 * 3600 * 1000;
 const MONTH_MS = 30 * 24 * 3600 * 1000;
@@ -185,13 +186,18 @@ function recordConversion(userDataDir, event) {
  * the lifetime rollup per format, priciest first, then most-converted. Never
  * throws; an unreadable ledger yields zeros, and the statusline hides the
  * chip on a zero.
+ *
+ * Events before the `doc2md` reset mark (`sprag saved reset`) are skipped in
+ * every figure, and `since` reports the mark (null when never reset).
  */
 function doc2mdSavedTotals(userDataDir, now = Date.now()) {
-  const empty = () => ({ week: 0, month: 0, total: 0, docs: 0, tokens: 0, byExt: [] });
+  const since = readResetMarks(userDataDir).doc2md;
+  const empty = () => ({ week: 0, month: 0, total: 0, docs: 0, tokens: 0, byExt: [], since });
   const totals = empty();
   const byExt = new Map();
   try {
     for (const e of Object.values(loadLedger(userDataDir).events)) {
+      if (isBeforeReset(e.ts, since)) continue;
       const usd = Number(e.usd) || 0;
       totals.total += usd;
       totals.docs += 1;

package/src/saved-reset.cjs

@@ -0,0 +1,118 @@
+/**
+ * saved-reset — a stopwatch reset for the lifetime "saved" counters.
+ *
+ * The ledgers are append-only evidence, so a reset must not delete anything.
+ * Instead this file records one timestamp per counter ("mark"), and every
+ * totals function counts only events at or after its mark. Undo pops the
+ * latest reset and puts the previous marks back, so a reset is always
+ * reversible and the underlying ledger data is never touched.
+ *
+ * File: <userDataDir>/saved-reset.json
+ *   { "version": 1,
+ *     "marks": { "routing", "doc2md", "codex-routing", "codex-docs" },  // ms | null
+ *     "history": [ { "at", "scopes": [...], "prev": { "<scope>": ms | null } } ] }
+ *
+ * CJS because doc2md-ledger.cjs reads it; ESM code imports it the same way.
+ * Every caller passes the data directory, so tests can point at a temp dir.
+ *
+ * Best-effort like every other state file here: a missing or unreadable file
+ * reads as "never reset", so a broken marker can only over-count, never hide
+ * events.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VERSION = 1;
+const SCOPES = ['routing', 'doc2md', 'codex-routing', 'codex-docs'];
+/** Cap on remembered resets, so the file cannot grow without bound. */
+const MAX_HISTORY = 50;
+
+const emptyMarks = () => Object.fromEntries(SCOPES.map((s) => [s, null]));
+
+function resetPath(dir) {
+  return path.join(dir, 'saved-reset.json');
+}
+
+const markOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
+function readState(dir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(resetPath(dir), 'utf8'));
+    if (!data || typeof data !== 'object' || data.version !== VERSION) return { marks: emptyMarks(), history: [] };
+    const marks = emptyMarks();
+    for (const s of SCOPES) marks[s] = markOrNull(data.marks && data.marks[s]);
+    const history = Array.isArray(data.history)
+      ? data.history.filter((h) => h && Array.isArray(h.scopes) && h.prev && typeof h.prev === 'object')
+      : [];
+    return { marks, history };
+  } catch {
+    return { marks: emptyMarks(), history: [] };
+  }
+}
+
+/** Atomic write: a temp file renamed over the target, so a reader never sees half a file. */
+function writeState(dir, state) {
+  const file = resetPath(dir);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  const text = JSON.stringify({ version: VERSION, marks: state.marks, history: state.history }) + '\n';
+  try {
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, file);
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
+    fs.writeFileSync(file, text);
+  }
+}
+
+/** Current marks. Never throws; a missing or corrupt file means no reset. */
+function readResetMarks(dir) {
+  return readState(dir).marks;
+}
+
+/**
+ * Reset the given scopes to `now`. Returns the new marks. Unknown scopes are
+ * ignored; the caller validates user input.
+ */
+function resetSaved(scopes, { dir, now = Date.now() } = {}) {
+  const state = readState(dir);
+  const valid = [...new Set(scopes)].filter((s) => SCOPES.includes(s));
+  if (valid.length === 0) return state.marks;
+  const prev = {};
+  for (const s of valid) {
+    prev[s] = state.marks[s];
+    state.marks[s] = now;
+  }
+  state.history.push({ at: now, scopes: valid, prev });
+  if (state.history.length > MAX_HISTORY) state.history.splice(0, state.history.length - MAX_HISTORY);
+  writeState(dir, state);
+  return state.marks;
+}
+
+/**
+ * Undo the latest reset. Returns { scopes, marks } with the restored marks,
+ * or null when there is nothing to undo.
+ */
+function undoReset({ dir } = {}) {
+  const state = readState(dir);
+  const last = state.history.pop();
+  if (!last) return null;
+  for (const s of last.scopes) {
+    if (SCOPES.includes(s)) state.marks[s] = markOrNull(last.prev[s]);
+  }
+  writeState(dir, state);
+  return { scopes: last.scopes, marks: state.marks };
+}
+
+/**
+ * True when an event at `ts` is excluded by `mark`: a mark exists and the
+ * event is older than it. An event with no usable timestamp cannot be shown
+ * to postdate the reset, so it is excluded too.
+ */
+function isBeforeReset(ts, mark) {
+  if (mark === null || mark === undefined) return false;
+  return !Number.isFinite(ts) || ts < mark;
+}
+
+module.exports = { SCOPES, resetPath, readResetMarks, resetSaved, undoReset, isBeforeReset };

package/src/savings-ledger.js

@@ -26,6 +26,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
 import { writeStateFile } from './state-file.js';
+import { readResetMarks, isBeforeReset } from './saved-reset.cjs';
 
 const WEEK_MS = 7 * 24 * 3600 * 1000;
 const MONTH_MS = 30 * 24 * 3600 * 1000;
@@ -140,13 +141,19 @@ export function modelFamily(model) {
  * Rolling totals: last 7 days, last 30 days, and lifetime, plus `pairs` — the
  * lifetime rollup by family-level model change, priciest first. `now` is
  * injectable for tests. Never throws — an unreadable ledger yields zeros.
+ *
+ * Events before the `routing` reset mark (`sprag saved reset`) are skipped
+ * everywhere, and `since` reports the mark (null when never reset). `dir` is
+ * the user data directory the mark is read from.
  */
-export function delegationSavedTotals(now = Date.now()) {
-  const empty = () => ({ week: 0, month: 0, total: 0, pairs: [] });
+export function delegationSavedTotals(now = Date.now(), dir = userDataDir()) {
+  const since = readResetMarks(dir).routing;
+  const empty = () => ({ week: 0, month: 0, total: 0, pairs: [], since });
   const totals = empty();
   const byPair = new Map();
   try {
     for (const e of Object.values(loadLedger().events)) {
+      if (isBeforeReset(e.ts, since)) continue;
       const usd = Number(e.usd);
       if (!Number.isFinite(usd)) continue;
       totals.total += usd;