sprag-cli 3.59.0 → 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/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.

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;
+}

package/src/statusline-data.js

@@ -0,0 +1,97 @@
+/**
+ * Statusline data helpers that need more than a number from the payload.
+ *
+ * bin/cli.js assembles the report data inline and cannot be imported (it runs
+ * on load), so the two derivations below live here where a test can reach them.
+ * Both read only what the render has already loaded or one small JSON file the
+ * statusline reads anyway; neither scans a transcript.
+ */
+
+import { resolve } from 'node:path';
+import { modelFamily } from './savings-ledger.js';
+import { loadModelRules } from './model-rules.js';
+
+/** Longest family name shown before it is cut. Keeps an opaque gateway id from taking the line. */
+const FAMILY_MAX = 14;
+
+const shortFamily = (name) => (name.length > FAMILY_MAX ? `${name.slice(0, FAMILY_MAX - 1)}…` : name);
+
+/**
+ * The subagent runs of the session the statusline is drawing for.
+ *
+ * The parser already attaches each session's subagent runs (`subagentRuns`,
+ * one entry per run with its own model), so this only finds the right session
+ * among those loaded and tallies them by model family. The session is matched
+ * by transcript path first, then by session id, because Claude Code reports
+ * both and either can be absent or spelled differently (a symlinked home).
+ *
+ * The runs are those the analysis window kept, so a session older than the
+ * window (`sprag mode` default is one day) reports only its recent runs.
+ *
+ * Families come from `modelFamily`, which returns an unmapped model id as it
+ * is rather than folding it into a neighbour; the name is shortened here so an
+ * ARN cannot flood the line.
+ *
+ * @param {Array} sessions parseAllSessions result
+ * @param {{ transcriptPath?: string|null, sessionId?: string|null }} [ids]
+ * @returns {{ total: number, families: Array<{ family: string, runs: number }> }|null}
+ *   null when the session cannot be found or ran no subagents
+ */
+export function sessionSubagentSummary(sessions, { transcriptPath = null, sessionId = null } = {}) {
+  if (!Array.isArray(sessions) || (!transcriptPath && !sessionId)) return null;
+  let hit = null;
+  if (transcriptPath) {
+    const want = resolve(transcriptPath);
+    hit = sessions.find((s) => s && s.filePath && resolve(s.filePath) === want) || null;
+  }
+  if (!hit && sessionId) {
+    // A resumed conversation can leave more than one file under one id; the
+    // most recently active is the one still being written.
+    const end = (s) => (s.endTime ? new Date(s.endTime).getTime() || 0 : 0);
+    hit = sessions
+      .filter((s) => s && s.sessionId === sessionId)
+      .sort((a, b) => end(b) - end(a))[0] || null;
+  }
+  const runs = hit && Array.isArray(hit.subagentRuns) ? hit.subagentRuns : [];
+  if (runs.length === 0) return null;
+  const byFamily = new Map();
+  for (const r of runs) {
+    const name = shortFamily(modelFamily(r && r.model));
+    byFamily.set(name, (byFamily.get(name) || 0) + 1);
+  }
+  const families = [...byFamily.entries()]
+    .map(([family, n]) => ({ family, runs: n }))
+    .sort((a, b) => b.runs - a.runs || a.family.localeCompare(b.family));
+  return { total: runs.length, families };
+}
+
+/**
+ * How many delegation rules apply in this project, and how many of those are
+ * flagged for review.
+ *
+ * "Apply" is the same test the `rule-health` warning uses: a global rule, or a
+ * project rule whose target is this root. A rule switched `off` is not counted.
+ * Review is `status === 'review'`, which is what model-rules.js renders as its
+ * `⚠ rule-health` marker (the marker itself is a local closure there, so the
+ * condition is restated rather than imported).
+ *
+ * @param {string} projectRoot
+ * @returns {{ total: number, review: number }}
+ */
+export function delegationRuleStats(projectRoot) {
+  let rules = [];
+  try {
+    rules = loadModelRules().rules;
+  } catch {
+    return { total: 0, review: 0 };
+  }
+  let total = 0;
+  let review = 0;
+  for (const r of rules) {
+    if (!r || r.status === 'off') continue;
+    if (r.scope !== 'global' && r.targetRoot !== projectRoot) continue;
+    total += 1;
+    if (r.status === 'review') review += 1;
+  }
+  return { total, review };
+}