sprag-cli 3.58.1 → 3.60.0

package/src/reply-language.cjs

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * reply-language — catches an English reply to a Korean prompt.
+ *
+ * The model sometimes answers a Korean prompt in English, typically right
+ * after a long stretch of English work (commit messages, release notes). The
+ * slip is decidable by counting letters, so it gets a Stop hook instead of
+ * another sentence in the guidance.
+ *
+ * The thresholds were measured on 2,204 Korean-prompt turns from 14 days of
+ * real transcripts: 8 flagged, all 8 true positives, no false positives.
+ * Loosening any of them reopens false positives on replies that are Korean
+ * prose around code and English identifiers, so change them only with a new
+ * measurement.
+ *
+ * CommonJS, no dependencies: this runs on every Stop, so it must stay cheap.
+ */
+
+const { openSync, readSync, fstatSync, closeSync } = require('node:fs');
+
+// Only the tail of the transcript matters, and transcripts grow to hundreds
+// of megabytes. If the last real prompt is further back than this, the turn is
+// a long agentic run and we skip it rather than pay for reading it all.
+const TAIL_BYTES = 2 * 1024 * 1024;
+
+const ENGLISH_REQUESTED = /영어로|영문으로|in English/i;
+
+// A user entry that is not something the person typed.
+const NOT_A_PROMPT_PREFIX = ['<command-name', '<local-command', '<command-message', '<task-notification', 'Caveat:'];
+
+/**
+ * Strip what is legitimately not prose in the reader's language: injected
+ * reminders, code, URLs and paths. Code and paths are Latin by nature, so
+ * counting them would flag every Korean reply that quotes a command.
+ */
+function cleanText(t) {
+  return String(t ?? '')
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, ' ')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`]*`/g, ' ')
+    .replace(/https?:\/\/\S+/g, ' ')
+    .replace(/(?:~|\.{0,2})?\/[\w.\-/]+/g, ' ');
+}
+
+function letterCounts(text) {
+  const cleaned = cleanText(text);
+  const h = (cleaned.match(/[가-힣]/g) || []).length;
+  const l = (cleaned.match(/[A-Za-z]/g) || []).length;
+  return { h, l, ratio: h + l === 0 ? 0 : h / (h + l) };
+}
+
+function isKoreanPrompt(text) {
+  const { h, ratio } = letterCounts(text);
+  return h >= 4 && ratio >= 0.3;
+}
+
+function isEnglishReply(text) {
+  const { l, ratio } = letterCounts(text);
+  return l >= 80 && ratio < 0.15;
+}
+
+function textBlocks(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+    .map((b) => b.text)
+    .join('\n');
+}
+
+/**
+ * The text of a real user prompt, or null when the entry is a tool result, a
+ * meta entry, or machinery posing as a user message.
+ */
+function realPromptText(entry) {
+  if (entry.type !== 'user' || entry.isMeta) return null;
+  const content = entry.message?.content;
+  if (Array.isArray(content) && content.some((b) => b && b.type === 'tool_result')) return null;
+  if (typeof content !== 'string' && !Array.isArray(content)) return null;
+  const text = textBlocks(content);
+  const head = text.trimStart();
+  if (NOT_A_PROMPT_PREFIX.some((p) => head.startsWith(p))) return null;
+  if (text.includes('[Subagent hand-back]') || text.includes('<agent-message')) return null;
+  return text;
+}
+
+/**
+ * The last turn in a list of JSONL lines: the final real user prompt and the
+ * assistant text the user sees after it. A tool_result resets the reply,
+ * because text written before a tool call is narration, not the answer.
+ * Returns null when there is no prompt. Unparsable lines and sidechain
+ * (subagent) entries are skipped.
+ */
+function lastTurn(lines) {
+  let prompt = null;
+  let reply = [];
+  for (const line of lines) {
+    if (!line) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!entry || typeof entry !== 'object' || entry.isSidechain) continue;
+    if (entry.type === 'user') {
+      const content = entry.message?.content;
+      if (Array.isArray(content) && content.some((b) => b && b.type === 'tool_result')) {
+        reply = [];
+        continue;
+      }
+      const text = realPromptText(entry);
+      if (text !== null) {
+        prompt = text;
+        reply = [];
+      }
+    } else if (entry.type === 'assistant') {
+      const text = textBlocks(entry.message?.content);
+      if (text) reply.push(text);
+    }
+  }
+  if (prompt === null) return null;
+  return { prompt, reply: reply.join('\n') };
+}
+
+function readTailLines(path) {
+  const fd = openSync(path, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buf = Buffer.alloc(size - start);
+    let got = 0;
+    while (got < buf.length) {
+      const n = readSync(fd, buf, got, buf.length - got, start + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    const lines = buf.subarray(0, got).toString('utf8').split('\n');
+    // A window that starts mid-file begins inside a line, so drop that stub.
+    if (start > 0) lines.shift();
+    return lines;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * null when the reply is fine (or cannot be judged), otherwise the measured
+ * ratios so a caller can report them. Never throws.
+ */
+function checkReplyLanguage(transcriptPath) {
+  try {
+    if (!transcriptPath) return null;
+    const turn = lastTurn(readTailLines(transcriptPath));
+    if (!turn) return null;
+    if (ENGLISH_REQUESTED.test(turn.prompt)) return null;
+    if (!isKoreanPrompt(turn.prompt) || !isEnglishReply(turn.reply)) return null;
+    const u = letterCounts(turn.prompt);
+    const r = letterCounts(turn.reply);
+    return { userHangulRatio: u.ratio, replyHangulRatio: r.ratio, replyLatin: r.l };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { checkReplyLanguage, cleanText, isKoreanPrompt, isEnglishReply, lastTurn };

package/src/route-inject.js

@@ -22,10 +22,16 @@
  *   - the text trips EDIT_RE (implement, add, fix …): editing is not delegable
  *     however much the sentence also says "install" or "check"
  *   - no registered rule covers that category
+ *   - the request is an explanation question ("어떻게 동작해", "뭐야", "how does
+ *     …") whose only category evidence is one weight-1 keyword. "sprag 설치만으로
+ *     … 도구에서 어떻게 쓰이는거지?" scored run on the bare word 설치 and was told
+ *     to hand a question about how the tool behaves to a command-running haiku.
+ *     Answering it takes the main model's knowledge, not a command. The read
+ *     category is exempt: explaining is what it is for.
  * A hint that fires on the wrong request costs more than one that stays quiet.
  */
 
-import { categorize, ESCALATE_RE, EDIT_RE, worthDelegating } from './route-scan.js';
+import { categorizeScored, ESCALATE_RE, EDIT_RE, worthDelegating } from './route-scan.js';
 import { loadModelRules, budgetCapPhrase, ruleBudget } from './model-rules.js';
 import { agentPhrase, agentPhraseEn } from './agents.js';
 import { userLanguage } from './config.js';
@@ -44,6 +50,34 @@ export function looksPasted(text) {
 /** Shortest text worth classifying; below this a prompt is an ack, not a task. */
 const MIN_LEN = 8;
 
+/**
+ * A question that asks for an explanation ("어떻게 쓰이는거지?", "뭐야", "how
+ * does it work"). "왜" is not here: ESCALATE_RE already routes it to the top
+ * tier. Kept to the shapes that ask HOW or WHAT something is — a bare "?" or a
+ * sentence-final "-지?" is too common in ordinary commands to count.
+ */
+const EXPLAIN_Q_RE = /어떻게\s*(?:쓰|사용|동작|작동|해야|하면|하는|하지|하죠|되는\s*(?:거|건|걸|것))|어떤\s*식으로|어떨\s*때|뭐야|뭐지|무엇|무슨\s*(?:의미|뜻)|\bhow\s+(?:does|do)\b|\bwhat\s+(?:is|does)\b/i;
+/**
+ * "어떻게 돼 / 됐 / 되고 있" asks for the current state of something, which is
+ * a check request however it is phrased. EXPLAIN_Q_RE does not list these, and
+ * this guard keeps it that way if "어떻게 되는 거" is ever matched next to one.
+ */
+const STATE_Q_RE = /어떻게\s*(?:돼|됐|됬|되어\s*있|되고\s*있)/;
+/** The category rests on exactly one weight-1 keyword. */
+const WEAK_SCORE = 1;
+/**
+ * The category whose job is to explain. Its weight-1 keywords (설명, 알려줘,
+ * 뭐야 …) share one pattern, so a question shape adds no evidence against it,
+ * and the registered rule names "4번 보정이 뭐야" as its own example.
+ */
+const EXPLAINING_CATEGORY = 'read';
+
+/** True for a question that asks how something works or what it is. */
+export function isExplainQuestion(text) {
+  const t = String(text || '');
+  return EXPLAIN_Q_RE.test(t) && !STATE_Q_RE.test(t);
+}
+
 /**
  * Price rank of whatever model is answering this session, or null when it
  * cannot be established.
@@ -98,8 +132,14 @@ export function routeMatch(text, { rules, sessionRank = null } = {}) {
   // delegable, and with no tool calls yet only the wording can say so.
   if (EDIT_RE.test(t)) return null;
 
-  const cat = categorize(t, null);
-  if (!cat) return null;
+  const scored = categorizeScored(t, null);
+  if (!scored) return null;
+  const cat = scored.cat;
+  // A category carried by one weak keyword is a guess, and an explanation
+  // question is the case where the guess is most often wrong: "설치" inside a
+  // question about how a tool works is not a request to install anything.
+  // Two or more points (a command, or several keywords) keep the old verdict.
+  if (scored.score === WEAK_SCORE && cat.id !== EXPLAINING_CATEGORY && isExplainQuestion(t)) return null;
   // Length alone makes a paste offline, where the tool mix confirms it. At
   // prompt time a long text is as often a written spec as a pasted log, and a
   // spec is not haiku work — so it must also look pasted: many lines, or the

package/src/route-scan.js

@@ -29,6 +29,7 @@ import { modelRank, isRecognizedModelId, TIER_TARGET_RANK, tierForRank } from '.
 import { sessionCost } from './claude-price.js';
 import { learnProfileMapping, resetModelAliasCache } from './model-alias.js';
 import { modelRuleBaseText } from './model-rules.js';
+import { readResetMarks, isBeforeReset } from './saved-reset.cjs';
 
 // ── Tier bands (docs/TIER_CRITERIA.md §3) ────────────────────────────────
 // T2 (haiku): finished in few calls, tiny output, near-zero mutation, no
@@ -235,7 +236,21 @@ export function mungeProjectPath(p) {
  * id); no behavior AND no keyword hit → null (nothing delegable to name).
  */
 export function categorize(text, toolCounts) {
-  if (text.length >= PASTE_MIN_LEN) return CATEGORIES.find((c) => c.id === 'paste');
+  const scored = categorizeScored(text, toolCounts);
+  return scored ? scored.cat : null;
+}
+
+/**
+ * categorize() plus the winning category's keyword score, for a caller that
+ * must tell a request the keywords claim firmly from one that a single
+ * weight-1 word dragged into a category. `score` is 0 when the category came
+ * from the paste gate or from the tool-mix fallback, where no keyword won.
+ * categorize() delegates here, so the two can never disagree on the category.
+ *
+ * @returns {{cat: object, score: number}|null}
+ */
+export function categorizeScored(text, toolCounts) {
+  if (text.length >= PASTE_MIN_LEN) return { cat: CATEGORIES.find((c) => c.id === 'paste'), score: 0 };
   const pool = behaviorPool(toolCounts);
   const eligible = pool
     ? pool.ids.map((id) => CATEGORIES.find((c) => c.id === id))
@@ -246,8 +261,8 @@ export function categorize(text, toolCounts) {
     const s = keywordScore(c, text);
     if (s > bestScore) { best = c; bestScore = s; }
   }
-  if (best) return best;
-  if (pool?.fallback) return CATEGORIES.find((c) => c.id === pool.fallback);
+  if (best) return { cat: best, score: bestScore };
+  if (pool?.fallback) return { cat: CATEGORIES.find((c) => c.id === pool.fallback), score: 0 };
   return null;
 }
 
@@ -465,6 +480,35 @@ export function windowBytes(files) {
   return total;
 }
 
+/**
+ * Fold one measured delegation into its aggregate (`stats`: key → { runs,
+ * errRuns, outTokens, savedUsd }).
+ *
+ * The two kinds of figure answer different questions. runs / errRuns / outTokens
+ * feed rule-health, which judges whether a rule keeps failing, so they cover the
+ * whole scan window whatever `sprag saved reset` did. savedUsd is money the user
+ * zeroed on purpose: it counts only runs dated at or after `resetMark` (the
+ * routing mark), by the same isBeforeReset the ledger totals use. The date is
+ * the one the ledger stamps on its event (end, else start), so a run that was
+ * still going when the user reset lands on the same side in both totals. A run
+ * with no usable time cannot be shown to postdate the reset, so it is left out
+ * too. An unpriced run (non-finite `saved`) adds nothing either way.
+ *
+ * @param {Map<string, object>} stats
+ * @param {string} key "tier|category|project"
+ * @param {{startedAt: number|null, endedAt?: number|null, out?: number}} run
+ * @param {number|null} saved price difference for this run
+ * @param {number|null} [resetMark] ms timestamp of the routing reset, or null
+ */
+export function tallyDelegatedRun(stats, key, run, saved, resetMark = null) {
+  const d = stats.get(key) || { runs: 0, errRuns: 0, outTokens: 0, savedUsd: 0 };
+  d.runs += 1;
+  if (isFailedRun(run)) d.errRuns += 1;
+  d.outTokens += run.out || 0;
+  if (Number.isFinite(saved) && !isBeforeReset(run.endedAt ?? run.startedAt, resetMark)) d.savedUsd += saved;
+  stats.set(key, d);
+}
+
 export async function runRouteScan({ days = 14 } = {}) {
   const files = await discoverSessionFiles({ days });
 
@@ -599,14 +643,10 @@ export async function runRouteScan({ days = 14 } = {}) {
   const delegatedStats = new Map(); // "tier|category|project" → outcome aggregate
   let unresolvedRuns = 0;           // delegated runs dropped for an unpriceable model id
   const unresolvedModels = new Set();
-  const bumpDelegated = (key, run, saved) => {
-    const d = delegatedStats.get(key) || { runs: 0, errRuns: 0, outTokens: 0, savedUsd: 0 };
-    d.runs += 1;
-    if (isFailedRun(run)) d.errRuns += 1;
-    d.outTokens += run.out || 0;
-    if (Number.isFinite(saved)) d.savedUsd += saved; // unpriced runs add nothing
-    delegatedStats.set(key, d);
-  };
+  // `sprag saved reset routing` zeroes the money, not the rule-health sample:
+  // see tallyDelegatedRun. readResetMarks never throws (no file = no reset).
+  const routingMark = readResetMarks(userDataDir()).routing;
+  const bumpDelegated = (key, run, saved) => tallyDelegatedRun(delegatedStats, key, run, saved, routingMark);
   // Ledger events feed the statusline's weekly/monthly "Routing saved"
   // totals. Keyed by run transcript path so overlapping re-scans upsert the
   // same event instead of double-counting it.

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

@@ -1,8 +1,9 @@
 /**
  * savings-ledger — per-run delegation saving events with timestamps.
  *
- * model-rules.json stores `savedUsd` as a scan-window snapshot per rule, which
- * is right for rule-health but cannot answer "how much did routing save this
+ * model-rules.json stores `savedUsd` as a scan-window snapshot per rule (only
+ * the runs dated after the last `sprag saved reset routing`), which is right
+ * for rule-health but cannot answer "how much did routing save this
  * week / this month / ever". This ledger keeps one event per subagent run,
  * keyed by the run's transcript path so re-scans over overlapping windows
  * upsert instead of double-counting.
@@ -26,6 +27,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 +142,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;

package/src/session-cache.js

@@ -18,9 +18,10 @@
  * and misses return identically shaped objects).
  */
 
-import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
+import { writeViaTmp, runHousekeeping, sweepStaleTmp } from './state-file.js';
 import { debug } from './debug.js';
 
 const CACHE_PATH = join(userDataDir(), 'session-cache.json');
@@ -185,12 +186,19 @@ export function saveCache(cache) {
     for (const [path, e] of Object.entries(cache.entries)) {
       if (e && typeof e.mtimeMs === 'number' && e.mtimeMs >= cutoff) entries[path] = e;
     }
-    const tmp = `${CACHE_PATH}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify({ version: CACHE_VERSION, entries }) + '\n');
-    renameSync(tmp, CACHE_PATH);
+    writeViaTmp(`${CACHE_PATH}.${process.pid}.tmp`, CACHE_PATH, JSON.stringify({ version: CACHE_VERSION, entries }) + '\n');
   } catch (e) {
     debug('session-cache:save', e); // best-effort — never block a report
   }
+  // This runs on nearly every statusline render, so it is the natural place to
+  // notice temp files that killed processes left in the data directory. The
+  // sweep itself runs at most once a day (see runHousekeeping).
+  try {
+    const dir = userDataDir();
+    runHousekeeping(dir, { 'stale-tmp': () => sweepStaleTmp(dir) });
+  } catch (e) {
+    debug('session-cache:housekeeping', e);
+  }
 }
 
 export function sessionCachePath() {

package/src/state-file.js

@@ -11,8 +11,11 @@
  * that does not parse is copied aside before it is replaced.
  */
 
-import { writeFileSync, renameSync, readFileSync, existsSync, mkdirSync, copyFileSync, rmSync } from 'node:fs';
-import { dirname } from 'node:path';
+import {
+  writeFileSync, renameSync, readFileSync, existsSync, mkdirSync, copyFileSync, rmSync,
+  readdirSync, lstatSync, unlinkSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
 
 /** Where an unreadable state file is kept. One slot: the first copy holds the data worth recovering. */
 export const corruptCopyPath = (file) => `${file}.corrupt`;
@@ -41,3 +44,97 @@ export function writeStateFile(file, text) {
     writeFileSync(file, text);
   }
 }
+
+/**
+ * Write `data` to `tmp`, then rename it over `file`. A failure at either step
+ * removes `tmp` before the error goes on, so a full disk or a rename refused
+ * by the OS does not leave a stray `<file>.<pid>.tmp` behind. The caller picks
+ * `tmp` (pid, uuid, ...) and decides what a failure means; this only makes
+ * sure the failure cleans up after itself. `unlink` errors are ignored: the
+ * original error is the one worth reporting.
+ */
+export function writeViaTmp(tmp, file, data, options) {
+  try {
+    writeFileSync(tmp, data, options);
+    renameSync(tmp, file);
+  } catch (e) {
+    try { rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
+    throw e;
+  }
+}
+
+/** A temp file older than this was left by a process that died mid-write. */
+export const STALE_TMP_AGE_MS = 60 * 60 * 1000;
+/** `session-cache.json.52038.tmp`: the `<state file>.<pid>.tmp` shape the writers above use. */
+const PID_TMP_NAME = /^.+\.json\.\d+\.tmp$/;
+
+/**
+ * Remove temp files that a killed process left in `dir` (top level only).
+ *
+ * Only `<name>.json.<digits>.tmp` older than an hour goes: a younger one may
+ * belong to a writer that is between its write and its rename right now, and
+ * anything with another shape is not ours to judge. Symlinks are skipped
+ * rather than followed.
+ *
+ * @returns {number} how many files were removed
+ */
+export function sweepStaleTmp(dir, { now = Date.now(), maxAgeMs = STALE_TMP_AGE_MS } = {}) {
+  let names;
+  try { names = readdirSync(dir); } catch { return 0; }
+  let removed = 0;
+  for (const name of names) {
+    if (!PID_TMP_NAME.test(name)) continue;
+    const path = join(dir, name);
+    try {
+      const st = lstatSync(path);
+      if (!st.isFile() || now - st.mtimeMs <= maxAgeMs) continue;
+      unlinkSync(path);
+      removed += 1;
+    } catch { /* already gone, or not ours to remove */ }
+  }
+  return removed;
+}
+
+const HOUSEKEEPING_FILE = 'housekeeping.json';
+export const HOUSEKEEPING_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Run directory clean-up jobs at most once per `intervalMs` each, however
+ * often this is called. Callers sit on hot paths (the statusline saves its
+ * cache on nearly every render; the Codex panel writes state every couple of
+ * seconds), and a `readdir` there would cost far more than the files it
+ * removes. The last run of each job is kept in `housekeeping.json` beside the
+ * data: one small read per call, and the directory is listed only when a job
+ * is actually due.
+ *
+ * The run is stamped BEFORE the job starts. A job that throws, or a stamp that
+ * cannot be written, then costs one skipped day rather than a retry on every
+ * call. A stamp that cannot be written skips the jobs entirely for the same
+ * reason.
+ *
+ * @param {string} dir
+ * @param {Record<string, () => void>} jobs - name -> job; names key the stamps
+ * @returns {string[]} names of the jobs that ran
+ */
+export function runHousekeeping(dir, jobs, { now = Date.now(), intervalMs = HOUSEKEEPING_INTERVAL_MS } = {}) {
+  const file = join(dir, HOUSEKEEPING_FILE);
+  let marks = {};
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) marks = parsed;
+  } catch { /* first run, or an unreadable stamp file: everything is due */ }
+  // A stamp in the future (clock moved back) would otherwise silence the job
+  // until the clock catches up; treat it as due.
+  const due = Object.keys(jobs).filter((name) => {
+    const age = now - Number(marks[name]);
+    return !(Number.isFinite(age) && age >= 0 && age < intervalMs);
+  });
+  if (!due.length) return [];
+  const next = { ...marks };
+  for (const name of due) next[name] = now;
+  try { writeStateFile(file, JSON.stringify(next) + '\n'); } catch { return []; }
+  for (const name of due) {
+    try { jobs[name](); } catch { /* clean-up is best effort */ }
+  }
+  return due;
+}