sprag-cli 3.59.0 → 3.61.0

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

package/src/update-check.js

@@ -8,6 +8,14 @@
  * answer is older than the check interval it spawns a detached, unref'd child
  * that refreshes the cache for the *next* render. Nothing awaits the network.
  *
+ * The cached answer is also treated as stale when the running version moved
+ * past the `latest` it holds: installing 3.59 proves a cache that says 3.57 is
+ * behind the registry, and waiting out the interval left a fresh install
+ * unaware of releases that shipped in the meantime. Only that case counts. A
+ * downgrade, or a dev checkout rendering next to the global install, changes
+ * the running version without telling us anything about the registry, and
+ * reading it as stale made two copies re-check on every alternation.
+ *
  * State lives next to the other user-data files:
  *   { checkedAt: <ms>, latest: "3.25.0", current: "3.24.0",
  *     dismissedVersion: "3.25.0"|undefined,
@@ -42,6 +50,12 @@ const CANONICAL_NAME = 'sprag-cli';
 const LEGACY_NAME = 'claude-token-saver';
 const IS_LEGACY = PKG_NAME === LEGACY_NAME;
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24h — the registry is not a health endpoint
+/**
+ * Interval for the SessionStart caller. Session start happens a few times a day
+ * rather than several times a second, so it can afford to look more often than
+ * the statusline's 24h default and notice a release the same afternoon.
+ */
+export const SESSION_START_CHECK_INTERVAL_MS = 3 * 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 5000;
 
 export function updateStatePath() {
@@ -89,12 +103,25 @@ export function isNewer(a, b) {
   return false;
 }
 
+/** `opts.intervalMs` when it is a usable duration, else the 24h default. */
+function checkInterval(opts) {
+  const ms = opts && opts.intervalMs;
+  return typeof ms === 'number' && Number.isFinite(ms) && ms >= 0 ? ms : CHECK_INTERVAL_MS;
+}
+
 /**
  * The read-only accessor every render path uses.
  *
+ * `stale` means "worth asking the registry again": the cached answer is older
+ * than the interval, or this copy was installed after the answer was recorded
+ * and is already newer than the `latest` it names. A cache that never recorded
+ * a version (written by an older release) is judged by age alone.
+ *
+ * @param {string} currentVersion
+ * @param {{intervalMs?: number}} [opts] - how old a cached answer may get; defaults to 24h
  * @returns {{current: string, latest: string|null, available: boolean, dismissed: boolean, stale: boolean}}
  */
-export function updateStatus(currentVersion) {
+export function updateStatus(currentVersion, opts) {
   if (updateCheckDisabled()) {
     return { current: currentVersion, latest: null, available: false, dismissed: false, stale: false };
   }
@@ -102,6 +129,12 @@ export function updateStatus(currentVersion) {
   const latest = typeof s.latest === 'string' ? s.latest : null;
   const available = !!latest && isNewer(latest, currentVersion);
   const age = Date.now() - (Number(s.checkedAt) || 0);
+  // Both halves are needed. The version test alone would stay true while the
+  // registry is unreachable, since the stamp below refreshes `current` but not
+  // `latest`; requiring a change since the stamp stops that from re-spawning
+  // on every render.
+  const versionChanged = typeof s.current === 'string' && s.current !== currentVersion;
+  const outrunCache = versionChanged && (!latest || isNewer(currentVersion, latest));
   return {
     current: currentVersion,
     latest,
@@ -110,7 +143,7 @@ export function updateStatus(currentVersion) {
     // of the session briefing until a newer one ships — otherwise "no thanks"
     // means "ask me again in five minutes", forever.
     dismissed: available && s.dismissedVersion === latest,
-    stale: age >= CHECK_INTERVAL_MS,
+    stale: outrunCache || age >= checkInterval(opts),
     // Only when they describe THIS version. A cache written for an earlier
     // release would otherwise sell the wrong upgrade. Language is not checked
     // here: a mismatch is corrected by the next refresh, and showing the other
@@ -123,14 +156,21 @@ export function updateStatus(currentVersion) {
  * Fire the background refresh when the cached answer has aged out. Returns
  * immediately in every case; the child is detached and unref'd so it cannot
  * hold the statusline process open.
+ *
+ * @param {string} currentVersion
+ * @param {{intervalMs?: number, spawnImpl?: Function}} [opts] - `intervalMs` as for
+ *   updateStatus; `spawnImpl` replaces child_process.spawn (tests only)
  */
-export function maybeSpawnUpdateCheck(currentVersion) {
+export function maybeSpawnUpdateCheck(currentVersion, opts) {
   if (updateCheckDisabled()) return false;
-  const { stale } = updateStatus(currentVersion);
+  const { stale } = updateStatus(currentVersion, opts);
   if (!stale) return false;
+  const spawnChild = (opts && opts.spawnImpl) || spawn;
   // Stamp the attempt before spawning. Without this, an offline machine
   // re-spawns a doomed child on every single statusline render — several per
-  // second — because the cache never gets a fresh timestamp.
+  // second — because the cache never gets a fresh timestamp. The stamp carries
+  // `current` too, which is what stops an upgrade from reading as stale again
+  // on the very next render.
   try {
     writeUpdateState({ ...readUpdateState(), checkedAt: Date.now(), current: currentVersion });
   } catch (e) {
@@ -138,7 +178,7 @@ export function maybeSpawnUpdateCheck(currentVersion) {
     return false;
   }
   try {
-    spawn(process.execPath, [cliEntryPath(), 'update-check', '--refresh', '--quiet'], {
+    spawnChild(process.execPath, [cliEntryPath(), 'update-check', '--refresh', '--quiet'], {
       detached: true,
       stdio: 'ignore',
       // Without this Windows flashes a console window, and this one