atris 3.30.12 → 3.31.0

package/lib/next-moves.js

@@ -21,6 +21,27 @@ function norm(title) {
   return String(title == null ? '' : title).trim().toLowerCase();
 }
 
+function titleKey(title) {
+  return norm(String(title == null ? '' : title).replace(/\s+/g, ' ').replace(/^title\s*:\s*/i, ''));
+}
+
+function isGenericInboxPlaceholder(title) {
+  const key = titleKey(title);
+  return /^(dogfood tick|autopilot tick|mission tick|run (one )?tick|tick|test idea|sample idea|placeholder idea|idea|todo|tbd)$/.test(key);
+}
+
+function cleanInboxMoveTitle(title) {
+  const raw = String(title == null ? '' : title).trim();
+  if (!raw) return null;
+  const titleLine = raw.match(/^title\s*:\s*(.+)$/i);
+  if (/^(task|status|action|tag|member|actor|proof|verify|checked|saved|changed|result|files?|commands?)\s*:/i.test(raw)) {
+    return null;
+  }
+  const cleaned = titleLine ? titleLine[1].trim() : raw;
+  if (isGenericInboxPlaceholder(cleaned)) return null;
+  return cleaned;
+}
+
 // Short, stable id so a kill on Tuesday still suppresses the same move on
 // Wednesday. Pure function of (source, title).
 function moveId(source, title) {
@@ -33,7 +54,8 @@ function moveId(source, title) {
   return `m_${(h >>> 0).toString(36)}`;
 }
 
-const WEIGHT = { roadmap: 100, task: 60, inbox: 40 };
+const WEIGHT = { roadmap: 100, mission: 90, endgame: 80, task: 60, inbox: 40 };
+const SELF_IMPROVEMENT_SEED_TITLE = 'Create the next proof-backed self-improvement task';
 
 // One section-boundary shape for every reader and writer: tolerate a header
 // suffix (e.g. "(priority)"), stop at a sibling/parent heading (## or #) or a
@@ -93,17 +115,119 @@ function readActiveTasks(root) {
   const tasks = Array.isArray(proj && proj.tasks) ? proj.tasks : [];
   return tasks
     .filter((t) => t && t.title && ['open', 'claimed'].includes(String(t.status || '').toLowerCase()))
+    .filter((t) => !isInternalNextMoveTask(t))
     .map((t) => ({
       title: String(t.title).trim(),
       why: `task in flight (${t.status}${t.claimed_by ? `, ${t.claimed_by}` : ''})`,
       source: 'task',
+      task_id: t.id || null,
       ref: t.display_id || t.id || null,
       weight: WEIGHT.task,
     }));
 }
 
+function isInternalNextMoveTask(task) {
+  const title = String(task?.title || '').trim();
+  const tags = [task?.tag, ...(Array.isArray(task?.tags) ? task.tags : [])]
+    .filter(Boolean)
+    .map((tag) => String(tag).toLowerCase());
+  return tags.includes('agent-xp') || /^mission xp\s*:/i.test(title);
+}
+
+function readHandledTaskTitles(root) {
+  const text = safeRead(path.join(root, '.atris', 'state', 'tasks.projection.json'));
+  if (!text) return [];
+  let proj;
+  try { proj = JSON.parse(text); } catch { return []; }
+  const tasks = Array.isArray(proj && proj.tasks) ? proj.tasks : [];
+  return tasks
+    .filter((t) => t && t.title && ['review', 'done'].includes(String(t.status || '').toLowerCase()))
+    .map((t) => String(t.title).trim())
+    .filter(Boolean);
+}
+
+function readJsonLines(file) {
+  const text = safeRead(file);
+  if (!text) return [];
+  return text.split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+function readActiveMissions(root) {
+  const rows = readJsonLines(path.join(root, '.atris', 'state', 'missions.jsonl'));
+  const latest = new Map();
+  for (const row of rows) {
+    if (row && row.id) latest.set(row.id, row);
+  }
+  return Array.from(latest.values())
+    .filter((m) => m && m.objective && !['complete', 'stopped', 'paused'].includes(String(m.status || '').toLowerCase()))
+    .map((m) => ({
+      title: String(m.objective).trim(),
+      why: `active mission (${m.status || 'unknown'}${m.owner ? `, ${m.owner}` : ''})`,
+      source: 'mission',
+      ref: m.id || null,
+      weight: m.status === 'blocked' ? WEIGHT.mission + 5 : WEIGHT.mission,
+    }));
+}
+
+function activeEndgameTaskCount(root) {
+  const text = safeRead(path.join(root, '.atris', 'state', 'tasks.projection.json'));
+  if (!text) return 0;
+  let proj;
+  try { proj = JSON.parse(text); } catch { return 0; }
+  const tasks = Array.isArray(proj && proj.tasks) ? proj.tasks : [];
+  return tasks.filter((t) => {
+    if (!t) return false;
+    const status = String(t.status || '').toLowerCase();
+    const tags = [t.tag, ...(Array.isArray(t.tags) ? t.tags : [])].filter(Boolean).map((tag) => String(tag).toLowerCase());
+    return tags.includes('endgame') && ['open', 'claimed', 'review'].includes(status);
+  }).length;
+}
+
+function todoKeepsEndgameActive(root) {
+  const text = safeRead(path.join(root, 'atris', 'TODO.md'));
+  if (!text) return true;
+  if (activeEndgameTaskCount(root) > 0) return true;
+
+  let sawEndgameHeader = false;
+  let section = '';
+  for (const raw of text.split(/\r?\n/)) {
+    const heading = raw.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      section = heading[1].trim().toLowerCase();
+      if (section === 'endgame') sawEndgameHeader = true;
+      continue;
+    }
+    if (!/\[endgame\]/i.test(raw)) continue;
+    if (['backlog', 'in progress', 'review'].includes(section)) return true;
+  }
+  return !sawEndgameHeader;
+}
+
+function readEndgameMove(root) {
+  if (!todoKeepsEndgameActive(root)) return [];
+  let state = null;
+  try { state = JSON.parse(safeRead(path.join(root, 'atris', 'brain', 'state.json'))); } catch { state = null; }
+  const horizon = String(state?.endgame?.horizon || '').trim();
+  if (!horizon) return [];
+  return [{
+    title: horizon,
+    why: state?.endgame?.source ? `endgame: ${state.endgame.source}` : 'endgame horizon from compiled brain',
+    source: 'endgame',
+    weight: WEIGHT.endgame,
+  }];
+}
+
 function inboxItemsFrom(text) {
-  return parseInboxTitles(text).map((title) => ({ title, why: 'fresh idea in today\'s inbox', source: 'inbox', weight: WEIGHT.inbox }));
+  return parseInboxTitles(text)
+    .map(cleanInboxMoveTitle)
+    .filter(Boolean)
+    .map((title) => ({ title, why: 'fresh idea in today\'s inbox', source: 'inbox', weight: WEIGHT.inbox }));
 }
 
 // Most recent journal under atris/logs/YYYY/, parsed for ## Inbox items. Used to
@@ -132,6 +256,8 @@ function todayInboxItems(root) {
 function gatherCandidates(root = process.cwd()) {
   return [
     ...readRoadmapOpenItems(root),
+    ...readActiveMissions(root),
+    ...readEndgameMove(root),
     ...readActiveTasks(root),
     ...latestInboxItems(root),
   ];
@@ -144,16 +270,25 @@ function gatherCandidates(root = process.cwd()) {
 // only suppressed for IDEAS (roadmap/inbox), never for a real `task`, so killing
 // or approving an idea can't hide a genuine in-flight task that happens to share
 // the title.
-function pickNextMoves(candidates, { limit = 3, killedIds = [], killedTitles = [], approvedIds = [], approvedTitles = [] } = {}) {
+function pickNextMoves(candidates, {
+  limit = 3,
+  killedIds = [],
+  killedTitles = [],
+  approvedIds = [],
+  approvedTitles = [],
+  handledTaskTitles = [],
+} = {}) {
   const blockedIds = new Set([...killedIds, ...approvedIds]);
-  const blockedTitles = new Set([...killedTitles, ...approvedTitles].map(norm));
+  const blockedTitles = new Set([...killedTitles, ...approvedTitles].map(titleKey));
+  const handledTitles = new Set(handledTaskTitles.map(titleKey));
   const seen = new Set();
   return candidates
-    .map((c) => ({ ...c, id: moveId(c.source, c.title), _key: norm(c.title) }))
+    .map((c) => ({ ...c, id: moveId(c.source, c.title), _key: titleKey(c.title) }))
     .filter((c) => {
       if (!c._key) return false;
       if (blockedIds.has(c.id)) return false;
       if (c.source !== 'task' && blockedTitles.has(c._key)) return false;
+      if (c.source !== 'task' && handledTitles.has(c._key)) return false;
       return true;
     })
     .sort((a, b) => (b.weight || 0) - (a.weight || 0))
@@ -166,6 +301,63 @@ function pickNextMoves(candidates, { limit = 3, killedIds = [], killedTitles = [
     .slice(0, limit);
 }
 
+function cleanSuggestedTargetTitle(text) {
+  const clean = String(text || '')
+    .replace(/[`*_#>]+/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/[.!?:;,]+$/g, '');
+  if (!clean) return '';
+  return clean.charAt(0).toUpperCase() + clean.slice(1);
+}
+
+function suggestedTargetFromReportText(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const match = lines[index].match(/^\s*Suggested target:\s*(.+?)\s*$/i);
+    if (match) return cleanSuggestedTargetTitle(match[1]);
+  }
+  return '';
+}
+
+function latestSuggestedTarget(root = process.cwd()) {
+  const reportsDir = path.join(root, 'atris', 'reports');
+  let files;
+  try {
+    files = fs.readdirSync(reportsDir).filter((file) => /\.md$/i.test(file)).sort().reverse();
+  } catch {
+    return '';
+  }
+  for (const file of files) {
+    const target = suggestedTargetFromReportText(safeRead(path.join(reportsDir, file)));
+    if (target) return target;
+  }
+  return '';
+}
+
+function addMissionOnlyFallback(moves, limit = 3, root = process.cwd()) {
+  if (!Array.isArray(moves) || moves.length !== 1 || limit <= 1) return moves;
+  const mission = moves[0];
+  if (!mission || mission.source !== 'mission') return moves;
+  const suggested = latestSuggestedTarget(root);
+  const target = suggested && !isGenericInboxPlaceholder(suggested)
+    ? suggested
+    : SELF_IMPROVEMENT_SEED_TITLE;
+  return [
+    mission,
+    {
+      title: target,
+      why: target === SELF_IMPROVEMENT_SEED_TITLE
+        ? 'active mission has no concrete task queued'
+        : 'latest proof timeline suggested this self-improvement target',
+      source: 'mission',
+      ref: mission.ref || null,
+      weight: WEIGHT.mission - 35,
+      id: moveId('mission', target),
+    },
+  ].slice(0, limit);
+}
+
 const DECISIONS_FILE = ['.atris', 'state', 'moves.decisions.jsonl'];
 
 function decisionsPath(root) {
@@ -336,20 +528,34 @@ function pickRoadmapSeed(root = process.cwd()) {
 // so the ranking inputs live in one place.
 function nextMoves(root = process.cwd(), limit = 3) {
   const { killedIds, killedTitles, approvedIds, approvedTitles } = readDecisions(root);
-  return pickNextMoves(gatherCandidates(root), { limit, killedIds, killedTitles, approvedIds, approvedTitles });
+  const handledTaskTitles = readHandledTaskTitles(root);
+  const picked = pickNextMoves(gatherCandidates(root), { limit, killedIds, killedTitles, approvedIds, approvedTitles, handledTaskTitles });
+  return addMissionOnlyFallback(picked, limit, root);
 }
 
 module.exports = {
   moveId,
   norm,
+  titleKey,
+  isGenericInboxPlaceholder,
   WEIGHT,
+  SELF_IMPROVEMENT_SEED_TITLE,
+  cleanSuggestedTargetTitle,
+  suggestedTargetFromReportText,
+  latestSuggestedTarget,
   parseInboxTitles,
+  cleanInboxMoveTitle,
   readRoadmapOpenItems,
+  readActiveMissions,
+  readEndgameMove,
   readActiveTasks,
+  isInternalNextMoveTask,
+  readHandledTaskTitles,
   latestInboxItems,
   todayInboxItems,
   gatherCandidates,
   pickNextMoves,
+  addMissionOnlyFallback,
   nextMoves,
   readDecisions,
   recordDecision,

package/lib/pulse.js

@@ -85,6 +85,21 @@ function buildPulseScorecardRow(input = {}) {
   };
 }
 
+function buildInterruptedPulseReceipt(input = {}) {
+  const signal = input.signal || 'signal';
+  return buildPulseReceipt({
+    tickIndex: input.tickIndex,
+    phase: 'finished',
+    actor: 'pulse_signal',
+    actorOk: false,
+    actorReason: String(signal).toLowerCase(),
+    what: `tick interrupted by ${signal}`,
+    elapsedMs: input.startedAt ? Date.now() - input.startedAt : input.elapsedMs,
+    prevTickStale: input.prevTickStale,
+    reward: -1,
+  });
+}
+
 // The heartbeat's full composition (mirrors the /loop skill): run the due
 // mission to continue an existing goal; if none is due, fall back to an
 // autopilot tick — that path is where proposeCandidateHorizons AUTHORS a new
@@ -198,6 +213,61 @@ function shellSingleQuote(value) {
   return `'${String(value || '').replace(/'/g, "'\\''")}'`;
 }
 
+function normalizeCronCadence(value = DEFAULT_CADENCE_CRON) {
+  const raw = String(value || DEFAULT_CADENCE_CRON).trim();
+  if (!raw) return DEFAULT_CADENCE_CRON;
+  if (raw.toLowerCase() === 'hourly') return DEFAULT_CADENCE_CRON;
+  if (raw.toLowerCase() === 'daily') return '23 2 * * *';
+  if (raw.split(/\s+/).length === 5) return raw;
+
+  const minutes = raw.match(/^(\d+)\s*(m|min|mins|minute|minutes)$/i);
+  if (minutes) {
+    const n = Number(minutes[1]);
+    if (Number.isInteger(n) && n >= 1 && n <= 59) return `*/${n} * * * *`;
+    throw new Error(`invalid cadence "${raw}": minute cadence must be 1m-59m or a 5-field cron`);
+  }
+
+  const hours = raw.match(/^(\d+)\s*(h|hr|hrs|hour|hours)$/i);
+  if (hours) {
+    const n = Number(hours[1]);
+    if (Number.isInteger(n) && n >= 1 && n <= 23) return `23 */${n} * * *`;
+    if (n === 24) return '23 0 * * *';
+    throw new Error(`invalid cadence "${raw}": hour cadence must be 1h-24h or a 5-field cron`);
+  }
+
+  throw new Error(`invalid cadence "${raw}": use 13m, 2h, hourly, daily, or a 5-field cron`);
+}
+
+function normalizeExpiryDuration(input = {}) {
+  const hasHours = input.hours !== undefined && input.hours !== null && String(input.hours).trim() !== '';
+  if (hasHours) {
+    const hours = Number(input.hours);
+    if (Number.isFinite(hours) && hours > 0) {
+      return {
+        source: 'hours',
+        hours,
+        days: null,
+        seconds: Math.ceil(hours * 60 * 60),
+      };
+    }
+    throw new Error(`invalid hours "${input.hours}": use a positive number of hours`);
+  }
+
+  const rawDays = input.days === undefined || input.days === null || String(input.days).trim() === ''
+    ? 7
+    : input.days;
+  const days = Number(rawDays);
+  if (Number.isFinite(days) && days > 0) {
+    return {
+      source: 'days',
+      hours: null,
+      days,
+      seconds: Math.ceil(days * 24 * 60 * 60),
+    };
+  }
+  throw new Error(`invalid days "${rawDays}": use a positive number of days`);
+}
+
 function runnerEnvAliasExport({ genericName, legacyName, value }) {
   if (!value) return '';
   return [
@@ -365,7 +435,7 @@ echo "done: $(date -Iseconds) exit=$?" >> "$log"
 function buildCrontabLine(opts = {}) {
   const { cron = DEFAULT_CADENCE_CRON, scriptPath, marker = PULSE_MARKER } = opts;
   if (!scriptPath) throw new Error('buildCrontabLine: scriptPath is required');
-  return `${cron} ${scriptPath} # ${marker}`;
+  return `${normalizeCronCadence(cron)} ${scriptPath} # ${marker}`;
 }
 
 module.exports = {
@@ -382,7 +452,9 @@ module.exports = {
   pulseLockDir,
   buildPulseReceipt,
   buildPulseScorecardRow,
+  buildInterruptedPulseReceipt,
   scoreTick,
+  normalizeExpiryDuration,
   shouldWriteScorecard,
   shouldFallbackToAutopilot,
   findOrphanStarts,
@@ -398,4 +470,5 @@ module.exports = {
   releaseLock,
   buildTickScript,
   buildCrontabLine,
+  normalizeCronCadence,
 };

package/lib/runner-command.js

@@ -3,14 +3,12 @@
 // Shared worker-spawn builder for the autonomous loops (missions, autopilot, run).
 //
 // Autonomous ticks must target a LIVE model. Inheriting the CLI's persisted
-// selection is fragile: a *versioned* id (e.g. claude-fable-5) silently dies
-// when that version is retired, and every tick then errors as a generic
-// 'claude-error' with no clue why (lesson: retired-model-kills-loop-silently,
-// CLI-245). Precedence: explicit model -> ATRIS_RUNNER_MODEL env ->
-// ATRIS_RUNNER_PROFILE -> legacy ATRIS_CLAUDE_MODEL env -> 'opus' alias. The
-// CLI resolves aliases to the latest live model, so an alias never retires out
-// from under the loop.
-const DEFAULT_CLAUDE_RUNNER_MODEL = 'opus';
+// selection is fragile: the local Claude Code `opus` alias can resolve to
+// different Opus releases across machines and account rollouts. Pin the default
+// so autonomous runs are reproducible, while keeping explicit per-run/env knobs
+// first in precedence. Precedence: explicit model -> ATRIS_RUNNER_MODEL env ->
+// ATRIS_RUNNER_PROFILE -> legacy ATRIS_CLAUDE_MODEL env -> pinned default.
+const DEFAULT_CLAUDE_RUNNER_MODEL = 'claude-opus-4-8';
 const DEFAULT_CLAUDE_RUNNER_BIN = 'claude';
 const RUNNER_PROFILES = Object.freeze({
   'atris-fast': Object.freeze({
@@ -97,6 +95,19 @@ function buildRunnerAvailabilityCommand() {
   return `command -v ${shellWord(resolveClaudeRunnerBin())}`;
 }
 
+function runnerAvailabilityFailureMessage(error) {
+  const message = error && error.message ? String(error.message).trim() : '';
+  if (message.startsWith('Unknown ATRIS_RUNNER_PROFILE')) {
+    return `${message}. Set ATRIS_RUNNER_PROFILE to one of: ${Object.keys(RUNNER_PROFILES).join(', ')}.`;
+  }
+
+  let runnerBin = 'configured runner';
+  try {
+    runnerBin = resolveClaudeRunnerBin();
+  } catch {}
+  return `${runnerBin} CLI not found. Set ATRIS_RUNNER_BIN (or legacy ATRIS_CLAUDE_BIN), or install the configured runner first.`;
+}
+
 function renderRunnerCommandTemplate(template, { promptFile, allowedTools, model }) {
   const allowedToolsFlag = allowedTools ? `--allowedTools ${shellWord(allowedTools)}` : '';
   const promptFileWord = shellWord(promptFile);
@@ -152,5 +163,6 @@ module.exports = {
   resolveClaudeRunnerBin,
   resolveClaudeRunnerCommandTemplate,
   buildRunnerAvailabilityCommand,
+  runnerAvailabilityFailureMessage,
   buildRunnerCommand,
 };

package/lib/runs-prune.js

@@ -0,0 +1,242 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function stampIso() {
+  return new Date().toISOString();
+}
+
+function toPosixPath(value) {
+  return String(value || '').split(path.sep).join('/');
+}
+
+function fileSize(filePath) {
+  try {
+    return fs.statSync(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+function listFiles(dir) {
+  const out = [];
+  function visit(current) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === '_archive') continue;
+        visit(fullPath);
+        continue;
+      }
+      if (entry.isFile()) out.push(fullPath);
+    }
+  }
+  visit(dir);
+  return out;
+}
+
+function runPathReferences(root) {
+  const stateDir = path.join(root, '.atris', 'state');
+  const refs = new Set();
+  const pattern = /atris\/runs\/[A-Za-z0-9._~:/@%+=,-]+(?:\/[A-Za-z0-9._~:@%+=,-]+)*/g;
+  const scan = (filePath) => {
+    let text = '';
+    try {
+      text = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return;
+    }
+    for (const match of text.matchAll(pattern)) {
+      refs.add(match[0].replace(/[)"'`.,;]+$/g, ''));
+    }
+  };
+  if (fs.existsSync(stateDir)) {
+    for (const filePath of listFiles(stateDir)) scan(filePath);
+  }
+  return refs;
+}
+
+function referencedDirs(refs) {
+  const dirs = new Set();
+  for (const ref of refs) {
+    const dir = path.posix.dirname(ref);
+    if (dir && dir !== '.' && dir !== 'atris/runs') dirs.add(dir);
+  }
+  return dirs;
+}
+
+function runEntry(root, filePath, refs, refDirs, nowMs) {
+  const rel = toPosixPath(path.relative(root, filePath));
+  let stat = null;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+  const dir = path.posix.dirname(rel);
+  const referenced = refs.has(rel) || refDirs.has(dir);
+  return {
+    path: rel,
+    absolute_path: filePath,
+    bytes: stat.size,
+    mtime_ms: stat.mtimeMs,
+    age_days: Math.max(0, Math.floor((nowMs - stat.mtimeMs) / 86400000)),
+    referenced,
+    kind: path.extname(filePath).toLowerCase().replace(/^\./, '') || 'file',
+  };
+}
+
+function compactJsonReceipt(filePath) {
+  let parsed = null;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+  return {
+    schema: parsed.schema || null,
+    mission_id: parsed.mission_id || parsed.mission?.id || null,
+    objective: parsed.objective || parsed.mission?.objective || null,
+    owner: parsed.owner || parsed.mission?.owner || null,
+    at: parsed.at || parsed.generated_at || parsed.created_at || null,
+    verifier: parsed.verifier || parsed.result?.verifier_result?.command || null,
+    passed: parsed.result?.passed === true || parsed.result?.verifier_result?.passed === true || null,
+    kind: parsed.result?.kind || parsed.action || null,
+    summary: parsed.result?.tick?.summary || parsed.result?.summary || parsed.landing?.happened || null,
+  };
+}
+
+function removeEmptyDirs(dir, stopDir) {
+  let current = dir;
+  while (current && current.startsWith(stopDir) && current !== stopDir) {
+    try {
+      const entries = fs.readdirSync(current);
+      if (entries.length) break;
+      fs.rmdirSync(current);
+    } catch {
+      break;
+    }
+    current = path.dirname(current);
+  }
+}
+
+function pruneRuns(root = process.cwd(), options = {}) {
+  const runsDir = options.runsDir || path.join(root, 'atris', 'runs');
+  const apply = options.apply === true;
+  const archive = options.archive !== false;
+  const keepNewest = Number.isFinite(options.keepNewest) ? Math.max(0, Math.floor(options.keepNewest)) : 200;
+  const keepDays = Number.isFinite(options.keepDays) ? Math.max(0, Math.floor(options.keepDays)) : 14;
+  const nowMs = options.nowMs || Date.now();
+  const cutoffMs = nowMs - keepDays * 86400000;
+  const refs = runPathReferences(root);
+  const refDirs = referencedDirs(refs);
+  const files = fs.existsSync(runsDir)
+    ? listFiles(runsDir).map((filePath) => runEntry(root, filePath, refs, refDirs, nowMs)).filter(Boolean)
+    : [];
+  const newest = new Set(
+    files
+      .slice()
+      .sort((a, b) => b.mtime_ms - a.mtime_ms || a.path.localeCompare(b.path))
+      .slice(0, keepNewest)
+      .map((entry) => entry.path),
+  );
+  const totalBytes = files.reduce((sum, entry) => sum + entry.bytes, 0);
+  const decisions = files.map((entry) => {
+    const reasons = [];
+    if (entry.referenced) reasons.push('referenced');
+    if (newest.has(entry.path)) reasons.push('newest');
+    if (entry.mtime_ms >= cutoffMs) reasons.push('recent');
+    const prune = reasons.length === 0;
+    return { ...entry, prune, keep_reasons: reasons };
+  });
+  const candidates = decisions.filter((entry) => entry.prune);
+  const archiveEntries = archive
+    ? candidates.map((entry) => ({
+      path: entry.path,
+      bytes: entry.bytes,
+      age_days: entry.age_days,
+      compact: entry.kind === 'json' ? compactJsonReceipt(entry.absolute_path) : null,
+    }))
+    : [];
+  let manifestPath = null;
+  const deleted = [];
+  const errors = [];
+  if (apply && candidates.length) {
+    const archiveDir = path.join(runsDir, '_archive');
+    if (archive) {
+      fs.mkdirSync(archiveDir, { recursive: true });
+      manifestPath = path.join(archiveDir, `prune-${stampIso().replace(/[:.]/g, '-')}.json`);
+      fs.writeFileSync(manifestPath, JSON.stringify({
+        schema: 'atris.runs_prune_manifest.v1',
+        generated_at: stampIso(),
+        policy: { keep_newest: keepNewest, keep_days: keepDays },
+        pruned_count: candidates.length,
+        pruned_bytes: candidates.reduce((sum, entry) => sum + entry.bytes, 0),
+        entries: archiveEntries,
+      }, null, 2) + '\n', 'utf8');
+    }
+    for (const entry of candidates) {
+      try {
+        fs.unlinkSync(entry.absolute_path);
+        deleted.push(entry.path);
+        removeEmptyDirs(path.dirname(entry.absolute_path), runsDir);
+      } catch (error) {
+        errors.push({ path: entry.path, error: error.message || String(error) });
+      }
+    }
+  }
+  return {
+    schema: 'atris.runs_prune_preview.v1',
+    action: apply ? 'runs_pruned' : 'runs_prune_preview',
+    runs_dir: toPosixPath(path.relative(root, runsDir)) || 'atris/runs',
+    applied: apply,
+    policy: { keep_newest: keepNewest, keep_days: keepDays, archive },
+    total_files: files.length,
+    total_bytes: totalBytes,
+    referenced_files: decisions.filter((entry) => entry.keep_reasons.includes('referenced')).length,
+    recent_files: decisions.filter((entry) => entry.keep_reasons.includes('recent')).length,
+    newest_files: decisions.filter((entry) => entry.keep_reasons.includes('newest')).length,
+    prune_count: candidates.length,
+    prune_bytes: candidates.reduce((sum, entry) => sum + entry.bytes, 0),
+    deleted_count: deleted.length,
+    manifest_path: manifestPath ? toPosixPath(path.relative(root, manifestPath)) : null,
+    candidates: candidates.map((entry) => ({
+      path: entry.path,
+      bytes: entry.bytes,
+      age_days: entry.age_days,
+      kind: entry.kind,
+    })),
+    deleted,
+    errors,
+  };
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes || 0);
+  if (value < 1024) return `${value} B`;
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`;
+  return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function runsPruneLines(result) {
+  return [
+    'Landing:',
+    `  Changed: ${result.applied ? `Pruned ${result.deleted_count} old run file(s).` : `Found ${result.prune_count} old run file(s) eligible for pruning.`}`,
+    `  How I checked: Scanned ${result.total_files} files in ${result.runs_dir}; kept referenced, newest, and recent proof.`,
+    `  Proof: ${result.applied ? (result.manifest_path ? `Manifest saved at ${result.manifest_path}.` : 'No manifest was needed.') : `Would reclaim ${formatBytes(result.prune_bytes)}.`}`,
+    `  Next: ${result.applied ? 'Run this command on a heartbeat when the run folder grows again.' : 'Run again with --apply to delete the eligible old files.'}`,
+  ];
+}
+
+module.exports = {
+  pruneRuns,
+  runsPruneLines,
+  formatBytes,
+};