claude-code-session-manager 0.119.1 → 0.121.0

package/src/main/lib/remoteTranscriptTail.cjs

@@ -2,6 +2,7 @@
 
 // Bounded-tail reader for Claude Code JSONL transcripts: the last N human-readable
 // chat messages (user prompts + assistant text) without reading the whole file.
+// Also builds the phone's conversation page (exchanges + live tail) in pure code.
 // Top-level (no domain fits: epic/ transcripts are path-only; util/ is domain-free).
 // Transcripts reach hundreds of MB, so cost is O(maxBytes), never O(file).
 
@@ -11,6 +12,10 @@ const DEFAULT_LIMIT = 30;
 const MAX_LIMIT = 100;
 const DEFAULT_MAX_BYTES = 524288;
 const MAX_TEXT_CHARS = 4000;
+const MAX_PROMPT_CHARS = 2000;
+const MAX_RESULT_CHARS = 16000;
+const MAX_LIVE_MESSAGES = 20;
+const MAX_PAGE_TEXT_BYTES = 100000; // relay closes any message over 256 KB
 
 /** Join the plain-text parts of a message `content` (string or block array). */
 function textOf(content) {
@@ -22,8 +27,12 @@ function textOf(content) {
     .join('\n');
 }
 
+function cap(text, max) {
+  return text.length > max ? text.slice(0, max - 1) + '…' : text;
+}
+
 function truncate(text) {
-  return text.length > MAX_TEXT_CHARS ? text.slice(0, MAX_TEXT_CHARS - 1) + '…' : text;
+  return cap(text, MAX_TEXT_CHARS);
 }
 
 /** Parse one JSONL line into a chat message, or null when it is not one. */
@@ -87,4 +96,62 @@ async function readRecentChatMessages(filePath, { limit = DEFAULT_LIMIT, maxByte
   }
 }
 
-module.exports = { readRecentChatMessages };
+/**
+ * Pure: build one phone-ready conversation page from exchanges (NEWEST-FIRST,
+ * callers fetch `limit + 1` so `hasMore` is derivable) plus the live transcript tail.
+ * @param {{ exchanges?: any[], tail?: any[], limit?: number, before?: number }} [opts]
+ * @returns {{ messages: Array<{ role: string, text: string, ts: string|null, uuid: string|null, live?: true }>, hasMore: boolean, nextBefore: number|null }}
+ *   messages oldest-first: history, then live.
+ */
+function buildRemoteConversation({ exchanges = [], tail = [], limit = 10, before = 0 } = {}) {
+  const n = Math.floor(Number(limit));
+  const lim = Number.isFinite(n) && n >= 1 ? n : 10;
+  const b = Math.max(0, Math.floor(Number(before)) || 0);
+  const valid = (Array.isArray(exchanges) ? exchanges : []).filter((e) => e && typeof e === 'object' && typeof e.ts === 'string');
+  const candidates = valid.slice(0, lim);
+  let hasMore = valid.length > lim;
+  let budget = MAX_PAGE_TEXT_BYTES;
+  const size = (text) => Buffer.byteLength(text, 'utf8');
+
+  // Live tail (first page only): newest-first until the budget is hit.
+  const live = [];
+  if (b === 0 && Array.isArray(tail)) {
+    const newest = valid.reduce((m, e) => Math.max(m, Date.parse(e.ts) || 0), 0);
+    const fresh = tail.filter((m) => {
+      if (!m || typeof m !== 'object' || typeof m.text !== 'string') return false;
+      if (!valid.length) return true;
+      const t = typeof m.ts === 'string' ? Date.parse(m.ts) : NaN;
+      return Number.isFinite(t) && t > newest;
+    });
+    for (const m of fresh.slice(-MAX_LIVE_MESSAGES).reverse()) {
+      const bytes = size(m.text);
+      if (bytes > budget) break;
+      budget -= bytes;
+      live.push({ role: m.role, text: m.text, ts: m.ts ?? null, uuid: m.uuid ?? null, live: true });
+    }
+    live.reverse();
+  }
+
+  // History: whole exchanges newest-first, oldest dropped when over budget.
+  const history = [];
+  let returned = 0;
+  for (const e of candidates) {
+    const pair = [];
+    const prompt = typeof e.prompt === 'string' ? e.prompt.trim() : '';
+    const result = typeof e.result === 'string' ? e.result.trim() : '';
+    if (prompt) pair.push({ role: 'user', text: cap(prompt, MAX_PROMPT_CHARS), ts: e.ts, uuid: `ex:${e.ts}:u` });
+    if (result) pair.push({ role: 'assistant', text: cap(result, MAX_RESULT_CHARS), ts: e.ts, uuid: `ex:${e.ts}:a` });
+    const bytes = pair.reduce((s, m) => s + size(m.text), 0);
+    if (bytes > budget) {
+      hasMore = true;
+      break;
+    }
+    budget -= bytes;
+    history.unshift(...pair);
+    returned++;
+  }
+
+  return { messages: [...history, ...live], hasMore, nextBefore: hasMore ? b + returned : null };
+}
+
+module.exports = { readRecentChatMessages, buildRemoteConversation };

package/src/main/lib/scheduler/queueHistory.cjs

@@ -111,9 +111,72 @@ function partitionJobs(jobs, nowMs, opts = {}) {
   return { hot, toArchive };
 }
 
+const SLIM_ARRAY_FIELDS = ['preRunDirtyPaths', 'guardBaseline', 'leftoverPaths'];
+const SALVAGE_PATCH_MAX_BYTES = 2048;
+// Dedupe only needs recent rows: a crash-replay re-submits the batch that was
+// just appended, so the tail of the file always contains its keys.
+const DEDUPE_TAIL_BYTES = 2 * 1024 * 1024;
+
 /**
- * Append-only JSONL write, deduped by slug+runId against what's already on
- * disk. The dedupe exists for crash-safety: reconcile() appends BEFORE
+ * Pure: returns a copy of `row` with the bulky snapshot arrays
+ * (preRunDirtyPaths, guardBaseline, leftoverPaths) replaced by `<field>Count`,
+ * and a salvagePatch string over 2 KB replaced by `salvagePatchBytes`. Every
+ * other field passes through unchanged. Rows without those fields are
+ * returned as-is (same shape, no extra keys).
+ */
+function slimHistoryRow(row) {
+  if (!row || typeof row !== 'object') return row;
+  let out = row;
+  const slim = () => (out === row ? (out = { ...row }) : out);
+  for (const f of SLIM_ARRAY_FIELDS) {
+    if (Array.isArray(row[f])) {
+      const o = slim();
+      o[`${f}Count`] = row[f].length;
+      delete o[f];
+    }
+  }
+  if (typeof row.salvagePatch === 'string') {
+    const bytes = Buffer.byteLength(row.salvagePatch, 'utf8');
+    if (bytes > SALVAGE_PATCH_MAX_BYTES) {
+      const o = slim();
+      o.salvagePatchBytes = bytes;
+      delete o.salvagePatch;
+    }
+  }
+  return out;
+}
+
+/** Text of the last `maxBytes` of a file, cut to whole lines ('' if absent). */
+async function readTailText(target, maxBytes) {
+  let fh;
+  try {
+    fh = await fsp.open(target, 'r');
+  } catch (e) {
+    if (e.code === 'ENOENT') return '';
+    throw e;
+  }
+  try {
+    const { size } = await fh.stat();
+    if (size === 0) return '';
+    const len = Math.min(maxBytes, size);
+    const start = size - len;
+    const buf = Buffer.alloc(len);
+    await fh.read(buf, 0, len, start);
+    let text = buf.toString('utf8');
+    if (start > 0) {
+      // Window may begin mid-line; drop the partial first fragment.
+      const nl = text.indexOf('\n');
+      text = nl === -1 ? '' : text.slice(nl + 1);
+    }
+    return text;
+  } finally {
+    await fh.close();
+  }
+}
+
+/**
+ * Append-only JSONL write, deduped by slug+runId against the last 2 MB of
+ * what's already on disk. Rows are slimmed (slimHistoryRow) before writing. The dedupe exists for crash-safety: reconcile() appends BEFORE
  * dropping archived jobs from state.jobs, so a crash between those two steps
  * replays the same batch through partitionJobs on the next boot — dedupe
  * here is what stops that replay from double-writing history.
@@ -133,12 +196,7 @@ async function appendHistory(entries) {
 
   let appended = 0;
   for (const [target, group] of byPath) {
-    let existingText = '';
-    try {
-      existingText = await fsp.readFile(target, 'utf8');
-    } catch (e) {
-      if (e.code !== 'ENOENT') throw e;
-    }
+    const existingText = await readTailText(target, DEDUPE_TAIL_BYTES);
 
     const existingKeys = new Set();
     if (existingText) {
@@ -156,7 +214,7 @@ async function appendHistory(entries) {
     if (fresh.length === 0) continue;
 
     await fsp.mkdir(path.dirname(target), { recursive: true });
-    const text = fresh.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    const text = fresh.map((e) => JSON.stringify(slimHistoryRow(e))).join('\n') + '\n';
     await fsp.appendFile(target, text, 'utf8');
     appended += fresh.length;
   }
@@ -407,6 +465,7 @@ module.exports = {
   historyPath,
   partitionJobs,
   appendHistory,
+  slimHistoryRow,
   readHistory,
   historyTerminalBySlug,
   completedSlugsForCwd,

package/src/main/lib/scheduler/runLogRetention.cjs

@@ -24,21 +24,32 @@
  * directory from being fully removed, but never blocks removal of a claimed
  * slug's own files.
  *
- * SAFETY MODEL (the point of this module — see the PRD that added it):
+ * FILE KINDS. Each (runId, slug) entry owns two kinds of file:
+ *   - BULK: `<slug>.log`, `<slug>.supervisor.json`, `<slug>*.patch`,
+ *     `root-cause-<slug>.md` — the space hogs.
+ *   - METADATA: `<slug>.meta.json`, `<slug>.verdicts.json`,
+ *     `<slug>.outcome.json` — tiny; terminalRunOutcome.cjs reads the newest
+ *     run's copies as the re-run guard fallback.
+ *
+ * SEMANTICS (age-driven):
  *   - Retention is ON by default (DEFAULT_RUN_LOG_RETENTION) when settings
  *     carry no `schedulerRunLogRetention`. An explicit `enabled: false` (or a
  *     config with no non-empty policy) opts out: computeReport, and
  *     applyRetention when opted out, only READ the filesystem.
- *   - An entry belonging to a job that is currently live — status `pending`
- *     (queued), `running`, `needs_review`, or `investigating` (the exact
- *     literals scheduler.cjs uses; see LIVE_STATUSES) — is never eligible,
- *     regardless of age or count policy.
- *   - The most recent entry for any given slug is never eligible, even past
- *     an age cap — every PRD keeps at least its latest evidence.
- *   - Age and count policies are COMBINABLE and combine conservatively
- *     (AND): when both are set, an entry must clear both floors to be
- *     eligible. A policy is a safety floor, not a removal trigger — setting
- *     one dimension should never make the other one weaker.
+ *   - A LIVE entry (status pending/running/needs_review/investigating — see
+ *     LIVE_STATUSES) loses nothing, regardless of age or count.
+ *   - With `maxAgeDays` set, age alone decides: a non-live entry older than
+ *     maxAgeDays loses its BULK files even when it is the slug's newest/only
+ *     run. `keepPerSlug` applies within the age window only — entries younger
+ *     than maxAgeDays are always kept, so it never rescues an old entry.
+ *   - With only `keepPerSlug` set (no maxAgeDays), bulk files of entries ranked
+ *     beyond the newest N are eligible.
+ *   - METADATA is removed only from entries that are bulk-eligible AND not the
+ *     slug's newest run: the newest run of every slug always keeps its
+ *     meta/verdicts/outcome files.
+ *   - A directory left holding only definition-of-done-*.md files (batch-keyed,
+ *     claimed by no entry) whose mtime is older than maxAgeDays is removed with
+ *     them; a directory left empty is removed.
  */
 
 const fs = require('node:fs');
@@ -135,19 +146,26 @@ function scanRunEntries(runsDir) {
     const metaFiles = files.filter((f) => f.endsWith(META_SUFFIX));
     for (const metaFile of metaFiles) {
       const slug = metaFile.slice(0, -META_SUFFIX.length);
-      const relatedNames = files.filter(
-        (f) => f === metaFile || f === `${slug}.log` || f === `${slug}.supervisor.json` || f === `root-cause-${slug}.md`
-      );
+      const isBulk = (f) =>
+        f === `${slug}.log` ||
+        f === `${slug}.supervisor.json` ||
+        f === `root-cause-${slug}.md` ||
+        (f.startsWith(`${slug}.`) && f.endsWith('.patch'));
+      const isMetadata = (f) =>
+        f === metaFile || f === `${slug}.verdicts.json` || f === `${slug}.outcome.json`;
+      const relatedNames = files.filter((f) => isBulk(f) || isMetadata(f));
 
       let sizeBytes = 0;
       let mtimeMs = null;
       const filePaths = [];
+      const fileInfos = [];
       for (const name of relatedNames) {
         const fp = path.join(dir, name);
         filePaths.push(fp);
         try {
           const st = fs.statSync(fp);
           sizeBytes += st.size;
+          fileInfos.push({ path: fp, size: st.size, kind: isBulk(name) ? 'bulk' : 'metadata' });
           if (mtimeMs === null || st.mtimeMs > mtimeMs) mtimeMs = st.mtimeMs;
         } catch {
           // file vanished mid-scan — skip its contribution
@@ -168,6 +186,7 @@ function scanRunEntries(runsDir) {
         slug,
         dir,
         files: filePaths,
+        fileInfos,
         sizeBytes,
         timeMs: recordedAtMs ?? mtimeMs ?? 0,
       });
@@ -206,10 +225,23 @@ function computeEligibility(entries, policy, opts) {
     const isMostRecent = rank === 0;
     const isLive = liveKeys.has(`${e.slug}|${e.runId}`);
     const ageDays = (now - e.timeMs) / DAY_MS;
-    const ageOk = maxAgeDays == null || ageDays > maxAgeDays;
-    const countOk = keepPerSlug == null || rank >= keepPerSlug;
-    const eligible = hasPolicy && !isLive && !isMostRecent && ageOk && countOk;
-    return { ...e, ageDays, rank, isMostRecent, isLive, eligible };
+    // Age alone decides when set; keepPerSlug only governs count-only policies.
+    const retained = maxAgeDays != null ? !(ageDays > maxAgeDays) : !(rank >= keepPerSlug);
+    const bulkEligible = hasPolicy && !isLive && !retained;
+    const metaEligible = bulkEligible && !isMostRecent;
+    const infos = e.fileInfos || [];
+    const removeFiles = infos.filter((f) => (f.kind === 'bulk' ? bulkEligible : metaEligible));
+    return {
+      ...e,
+      ageDays,
+      rank,
+      isMostRecent,
+      isLive,
+      bulkEligible,
+      metaEligible,
+      removeFiles,
+      eligible: removeFiles.length > 0,
+    };
   });
 }
 
@@ -228,27 +260,66 @@ function computeReport(runsDir, policy, opts) {
   const oldestRunAt = entries.length ? Math.min(...entries.map((e) => e.timeMs)) : null;
 
   const eligible = evaluated.filter((e) => e.eligible);
-  const eligibleBytes = eligible.reduce((sum, e) => sum + e.sizeBytes, 0);
+  let bulkBytes = 0;
+  let metadataBytes = 0;
+  for (const e of eligible) {
+    for (const f of e.removeFiles) {
+      if (f.kind === 'bulk') bulkBytes += f.size;
+      else metadataBytes += f.size;
+    }
+  }
+
+  // A directory is fully removable when, after the eligible files are
+  // unlinked, nothing remains except definition-of-done reports older than
+  // maxAgeDays (which go with it). Any other leftover (a non-eligible entry's
+  // files, an unclaimed file, a young DoD report) keeps the directory alive.
+  const maxAgeDays = policy && policy.maxAgeDays;
+  const removing = new Set();
+  for (const e of eligible) for (const f of e.removeFiles) removing.add(f.path);
 
-  // A directory is fully removable only when every file physically present
-  // in it belongs to an eligible entry — an unclaimed file (a DoD report, or
-  // a slug entry that isn't eligible) keeps the directory itself alive even
-  // though the eligible entries' own files can still be unlinked.
+  let allDirs;
+  try {
+    allDirs = fs.readdirSync(runsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => path.join(runsDir, d.name));
+  } catch {
+    allDirs = [];
+  }
   const removableDirs = [];
-  for (const dir of dirSet) {
+  const dodFiles = [];
+  for (const dir of allDirs) {
     let actualFiles;
     try {
       actualFiles = fs.readdirSync(dir);
     } catch {
       continue;
     }
-    if (actualFiles.length === 0) continue;
-    const claimedEligible = new Set();
-    for (const e of evaluated) {
-      if (e.dir !== dir || !e.eligible) continue;
-      for (const fp of e.files) claimedEligible.add(path.basename(fp));
+    if (actualFiles.length === 0) continue; // empty orphans: sweepOrphanDirs
+    const dirDod = [];
+    let removable = true;
+    for (const f of actualFiles) {
+      const fp = path.join(dir, f);
+      if (removing.has(fp)) continue;
+      if (maxAgeDays != null && /^definition-of-done-.*\.md$/.test(f)) {
+        try {
+          const st = fs.statSync(fp);
+          if ((now - st.mtimeMs) / DAY_MS > maxAgeDays) {
+            dirDod.push({ path: fp, size: st.size, kind: 'metadata' });
+            continue;
+          }
+        } catch {
+          // vanished — treat as gone
+          continue;
+        }
+      }
+      removable = false;
+      break;
+    }
+    if (removable) {
+      removableDirs.push(dir);
+      for (const d of dirDod) {
+        dodFiles.push(d);
+        metadataBytes += d.size;
+      }
     }
-    if (actualFiles.every((f) => claimedEligible.has(f))) removableDirs.push(dir);
   }
 
   return {
@@ -262,16 +333,30 @@ function computeReport(runsDir, policy, opts) {
       oldestRunAt,
     },
     eligible,
-    eligibleSummary: { count: eligible.length, bytes: eligibleBytes },
+    eligibleSummary: {
+      count: eligible.length,
+      bytes: bulkBytes + metadataBytes,
+      bulkBytes,
+      metadataBytes,
+    },
+    dodFiles,
     removableDirs,
   };
 }
 
 /**
- * The effective retention config: the caller's `schedulerRunLogRetention`
- * when present, else DEFAULT_RUN_LOG_RETENTION.
+ * The effective retention config: ops-retention.json `runLogs` when stored,
+ * else the caller's `schedulerRunLogRetention` when present, else DEFAULT_RUN_LOG_RETENTION.
  */
 function resolveRetentionConfig(settings) {
+  // Machine-level ops-retention.json wins over the legacy scheduler-machine.json key.
+  // Lazy require: opsRetentionSettings requires this module (preview).
+  try {
+    const stored = require('../opsRetentionSettings.cjs').readStored();
+    if (stored && stored.runLogs) return { enabled: true, policy: { ...stored.runLogs } };
+  } catch {
+    // unreadable settings never block retention — fall through to legacy/default
+  }
   const cfg = settings && settings.schedulerRunLogRetention;
   return cfg == null ? DEFAULT_RUN_LOG_RETENTION : cfg;
 }
@@ -409,16 +494,17 @@ function applyRetention(runsDir, settings, opts) {
   let freedBytes = 0;
   const errors = [];
 
-  for (const entry of report.eligible) {
-    for (const fp of entry.files) {
-      try {
-        const st = fs.statSync(fp);
-        fs.unlinkSync(fp);
-        removedFiles += 1;
-        freedBytes += st.size;
-      } catch (e) {
-        if (e && e.code !== 'ENOENT') errors.push({ path: fp, error: e.message });
-      }
+  const toRemove = [];
+  for (const entry of report.eligible) for (const f of entry.removeFiles) toRemove.push(f.path);
+  for (const f of report.dodFiles) toRemove.push(f.path);
+  for (const fp of toRemove) {
+    try {
+      const st = fs.statSync(fp);
+      fs.unlinkSync(fp);
+      removedFiles += 1;
+      freedBytes += st.size;
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') errors.push({ path: fp, error: e.message });
     }
   }
 

package/src/main/lib/scheduler/schedulerBatch.cjs

@@ -430,9 +430,12 @@ function enqueueTimestamp(job) {
  * nothing. A single project can therefore never drain every free slot while
  * another project with eligible work gets none in the same tick.
  *   1. fewest jobs currently `running` in that project, ascending;
- *   2. tiebreak: the oldest pending job's enqueue timestamp
+ *   2. tiebreak: the oldest DISPATCHABLE pending job's enqueue timestamp
  *      (enqueueTimestamp — createdAt → queuedAt → statusHistory → startedAt),
- *      ascending, unprovable ages last;
+ *      ascending, unprovable ages last. Rows blocked by an unfinished
+ *      dependsOn do NOT count (a project with only blocked rows gets
+ *      Infinity). 2026-10-18: Game-Academy's dep-blocked 02:16Z row kept it
+ *      ahead of Self's runnable 02:50Z rows, so it took every freed slot.
  *   3. final deterministic tiebreak: the project cwd string.
  *
  * WHY NOT THE PRD NUMBER. The previous sort key was each project's lowest
@@ -576,8 +579,9 @@ function pickNextBatch(allJobs, running, freeSlots, quietOpts = {}) {
       projectJobs.filter((j) => running.has(j.slug)).map((j) => j.slug),
     );
     const runningCount = projectJobs.filter((j) => j.status === 'running').length;
+    const satisfied = satisfiedSlugsFor(cwd);
     const oldestPendingMs = projectJobs
-      .filter(pickable)
+      .filter((j) => pickable(j) && !findBlockingDep(j, projectJobs, satisfied))
       .reduce((min, j) => Math.min(min, enqueueTimestamp(j)), Infinity);
     candidates.push({ cwd, view, runningSlugsInProject, runningCount, oldestPendingMs, active: true });
   }

package/src/main/lib/scheduler/staleTmpSweep.cjs

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * staleTmpSweep.cjs — reaps tmp files leaked by dead writers in scheduled-plans/
+ * (`queue.json.tmp-<pid>-*`, `.max-allocated-group.tmp-<pid>-*`) and prunes
+ * `scheduled-plans/runs-archive/` by age.
+ *
+ * Safety: a tmp file is removed only when it is older than minAgeMs AND the pid
+ * embedded in its name is not alive. `queue.json.bak*` files are never deleted —
+ * they are reported only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const TMP_RE = /\.tmp-(\d+)-/;
+
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM = process exists but belongs to someone else → alive.
+    return !!e && e.code === 'EPERM';
+  }
+}
+
+function sweepStaleTmp(dir, opts) {
+  const o = opts || {};
+  const minAgeMs = typeof o.minAgeMs === 'number' ? o.minAgeMs : 3600000;
+  const now = typeof o.now === 'number' ? o.now : Date.now();
+  const isPidAlive = typeof o.isPidAlive === 'function' ? o.isPidAlive : defaultIsPidAlive;
+  const dryRun = o.dryRun === true;
+  const result = { removedFiles: 0, freedBytes: 0, removed: [], backups: [], errors: [] };
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') result.errors.push(e.message);
+    return result;
+  }
+  for (const name of names) {
+    if (name.startsWith('queue.json.bak')) {
+      result.backups.push(name);
+      continue;
+    }
+    const m = TMP_RE.exec(name);
+    if (!m) continue;
+    const full = path.join(dir, name);
+    try {
+      const st = fs.statSync(full);
+      if (!st.isFile() || now - st.mtimeMs <= minAgeMs) continue;
+      if (isPidAlive(Number(m[1]))) continue;
+      if (!dryRun) fs.unlinkSync(full);
+      result.removedFiles += 1;
+      result.freedBytes += st.size;
+      result.removed.push(name);
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') result.errors.push(`${name}: ${e.message}`);
+    }
+  }
+  return result;
+}
+
+function sizeOf(p, st) {
+  if (!st.isDirectory()) return st.size;
+  let total = 0;
+  let kids = [];
+  try { kids = fs.readdirSync(p); } catch { return 0; }
+  for (const k of kids) {
+    try { total += sizeOf(path.join(p, k), fs.lstatSync(path.join(p, k))); } catch { /* raced */ }
+  }
+  return total;
+}
+
+// Lazy require: opsRetentionSettings requires this module (preview), so a
+// top-level require here would be circular.
+function defaultRunsArchiveDays() {
+  try {
+    return require('../opsRetentionSettings.cjs').read().runsArchiveDays;
+  } catch {
+    return 30;
+  }
+}
+
+function pruneRunsArchive(archiveDir, opts) {
+  const o = opts || {};
+  const maxAgeDays = typeof o.maxAgeDays === 'number' ? o.maxAgeDays : defaultRunsArchiveDays();
+  const dryRun = o.dryRun === true;
+  const now = typeof o.now === 'number' ? o.now : Date.now();
+  const result = { removedFiles: 0, freedBytes: 0, removed: [], errors: [] };
+  let names;
+  try {
+    names = fs.readdirSync(archiveDir);
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') result.errors.push(e.message);
+    return result;
+  }
+  for (const name of names) {
+    const full = path.join(archiveDir, name);
+    try {
+      const st = fs.lstatSync(full);
+      if (now - st.mtimeMs <= maxAgeDays * DAY_MS) continue;
+      const bytes = sizeOf(full, st);
+      if (!dryRun) fs.rmSync(full, { recursive: true, force: true });
+      result.removedFiles += 1;
+      result.freedBytes += bytes;
+      result.removed.push(name);
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') result.errors.push(`${name}: ${e.message}`);
+    }
+  }
+  return result;
+}
+
+module.exports = { sweepStaleTmp, pruneRunsArchive };