mandrel 2.65.0 → 2.67.0

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -80,6 +80,10 @@ function writeJson(p, obj, fsImpl = fs) {
   fsImpl.writeFileSync(p, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
 }
 
+function agentRootOf(ctx) {
+  return ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents');
+}
+
 /**
  * Node floor SSOT (`node:sqlite` stabilised at 22.22.1); import it, never
  * duplicate. Matches `package.json` `engines.node` (`>=22.22.1 <25`).
@@ -126,9 +130,36 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
   return detectPm(projectRoot, (p) => fsImpl.existsSync(p)) ?? 'npm';
 }
 
+/** @returns {'added'|'already-present'} */
+function ensureScript(scripts, key, command) {
+  if (scripts[key]) return 'already-present';
+  scripts[key] = command;
+  return 'added';
+}
+
+/** Append each projection independently so a partial prepare gains the other. */
+function ensurePrepareScript(scripts) {
+  const prepare = scripts.prepare;
+  if (!prepare) {
+    scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
+    return 'added';
+  }
+  let next = prepare;
+  if (!next.includes('sync-claude-commands.js')) {
+    next = `${next} && ${SYNC_COMMAND}`;
+  }
+  if (!next.includes('sync-claude-agents.js')) {
+    next = `${next} && ${SYNC_AGENTS_COMMAND}`;
+  }
+  if (next === prepare) return 'already-present';
+  scripts.prepare = next;
+  return 'appended';
+}
+
 /**
  * Ensure `package.json` carries the sync/prepare/bootstrap scripts. Never
  * touches `dependencies` — framework deps arrive transitively via `mandrel`.
+ * An operator-defined `bootstrap` script always wins.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -136,62 +167,32 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
 export function ensurePackageJson(ctx) {
   const { fsImpl = fs } = ctx;
   const pkgPath = path.join(ctx.projectRoot, 'package.json');
-  const projectName = path.basename(path.resolve(ctx.projectRoot));
-  const outcomes = {
-    created: false,
-    scriptsSyncCommands: 'already-present',
-    scriptsSyncAgents: 'already-present',
-    scriptsPrepare: 'already-present',
-    scriptsBootstrap: 'already-present',
+  const existing = readJsonIfExists(pkgPath, fsImpl);
+  const pkg = existing || {
+    name: path.basename(path.resolve(ctx.projectRoot)),
+    version: '0.0.0',
+    private: true,
+    type: 'module',
   };
-  let pkg = readJsonIfExists(pkgPath, fsImpl);
-  if (!pkg) {
-    pkg = {
-      name: projectName,
-      version: '0.0.0',
-      private: true,
-      type: 'module',
-    };
-    outcomes.created = true;
-  }
   pkg.scripts = pkg.scripts ?? {};
-  if (!pkg.scripts['sync:commands']) {
-    pkg.scripts['sync:commands'] = SYNC_COMMAND;
-    outcomes.scriptsSyncCommands = 'added';
-  }
-  if (!pkg.scripts['sync:agents']) {
-    pkg.scripts['sync:agents'] = SYNC_AGENTS_COMMAND;
-    outcomes.scriptsSyncAgents = 'added';
-  }
-  const prepare = pkg.scripts.prepare;
-  if (!prepare) {
-    pkg.scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
-    outcomes.scriptsPrepare = 'added';
-  } else {
-    // Append each projection independently so a partial prepare gains the other.
-    let next = prepare;
-    if (!next.includes('sync-claude-commands.js')) {
-      next = `${next} && ${SYNC_COMMAND}`;
-    }
-    if (!next.includes('sync-claude-agents.js')) {
-      next = `${next} && ${SYNC_AGENTS_COMMAND}`;
-    }
-    if (next !== prepare) {
-      pkg.scripts.prepare = next;
-      outcomes.scriptsPrepare = 'appended';
-    }
-  }
-  // An operator-defined `bootstrap` script always wins.
-  if (!pkg.scripts.bootstrap) {
-    pkg.scripts.bootstrap = BOOTSTRAP_COMMAND;
-    outcomes.scriptsBootstrap = 'added';
-  }
-  const mutated =
-    outcomes.created ||
-    outcomes.scriptsSyncCommands === 'added' ||
-    outcomes.scriptsSyncAgents === 'added' ||
-    outcomes.scriptsPrepare !== 'already-present' ||
-    outcomes.scriptsBootstrap === 'added';
+  const outcomes = {
+    created: !existing,
+    scriptsSyncCommands: ensureScript(
+      pkg.scripts,
+      'sync:commands',
+      SYNC_COMMAND,
+    ),
+    scriptsSyncAgents: ensureScript(
+      pkg.scripts,
+      'sync:agents',
+      SYNC_AGENTS_COMMAND,
+    ),
+    scriptsPrepare: ensurePrepareScript(pkg.scripts),
+    scriptsBootstrap: ensureScript(pkg.scripts, 'bootstrap', BOOTSTRAP_COMMAND),
+  };
+  const mutated = Object.values(outcomes).some(
+    (v) => v === true || v === 'added' || v === 'appended',
+  );
   if (mutated) writeJson(pkgPath, pkg, fsImpl);
   return { ...outcomes, path: pkgPath, mutated };
 }
@@ -246,10 +247,7 @@ export function ensureAgentrc(ctx) {
   if (fsImpl.existsSync(target)) {
     return { action: 'already-present', path: target };
   }
-  const starter = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'starter-agentrc.json',
-  );
+  const starter = path.join(agentRootOf(ctx), 'starter-agentrc.json');
   if (!fsImpl.existsSync(starter)) {
     return { action: 'missing-starter', path: target };
   }
@@ -269,16 +267,28 @@ export function ensureAgentrc(ctx) {
   return { action: 'seeded', path: target, source: 'starter' };
 }
 
+async function loadAgentrcValidator(schemaModule) {
+  // pathToFileURL handles Windows drive letters and percent-encoding.
+  const mod = await import(pathToFileURL(schemaModule).href);
+  return mod.getAgentrcValidator();
+}
+
+function agentrcVerdict(validate, data) {
+  if (!data) return { ok: false, errors: ['.agentrc.json missing'] };
+  const ok = validate(data);
+  return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
+}
+
 /**
  * Validate `.agentrc.json` against the AJV schema; the caller decides whether to abort.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
  */
-export async function validateAgentrc(ctx) {
+async function validateAgentrc(ctx) {
   const { fsImpl = fs } = ctx;
   const schemaModule = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
+    agentRootOf(ctx),
     'scripts',
     'lib',
     'config-settings-schema.js',
@@ -286,16 +296,12 @@ export async function validateAgentrc(ctx) {
   if (!fsImpl.existsSync(schemaModule)) {
     return { ok: false, errors: ['config-settings-schema.js not found'] };
   }
-  // pathToFileURL handles Windows drive letters and percent-encoding.
-  const mod = await import(pathToFileURL(schemaModule).href);
-  const validate = mod.getAgentrcValidator();
+  const validate = await loadAgentrcValidator(schemaModule);
   const data = readJsonIfExists(
     path.join(ctx.projectRoot, '.agentrc.json'),
     fsImpl,
   );
-  if (!data) return { ok: false, errors: ['.agentrc.json missing'] };
-  const ok = validate(data);
-  return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
+  return agentrcVerdict(validate, data);
 }
 
 /**
@@ -347,12 +353,9 @@ function ensureIssueFormsPhase(ctx) {
  * @param {object} ctx
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
-export function runSyncCommands(ctx) {
+function runSyncCommands(ctx) {
   const { spawnImpl = defaultSpawnSync } = ctx;
-  const scriptsDir = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'scripts',
-  );
+  const scriptsDir = path.join(agentRootOf(ctx), 'scripts');
   const projections = [
     { label: 'sync-claude-commands.js', script: 'sync-claude-commands.js' },
     { label: 'sync-claude-agents.js', script: 'sync-claude-agents.js' },
@@ -390,10 +393,7 @@ export function runSyncCommands(ctx) {
  */
 export function checkParity(ctx) {
   const { fsImpl = fs } = ctx;
-  const workflowsDir = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'workflows',
-  );
+  const workflowsDir = path.join(agentRootOf(ctx), 'workflows');
   const commandsDir = path.join(ctx.projectRoot, '.claude', 'commands');
   const list = (dir) =>
     fsImpl.existsSync(dir)
@@ -437,13 +437,13 @@ export function ensureSystemPromptWiring(ctx) {
  * @param {typeof fs} [ctx.fsImpl]
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
-export function checkWindowsGitPerf(ctx) {
+function checkWindowsGitPerf(ctx) {
   const { fsImpl = fs, spawnImpl = defaultSpawnSync } = ctx;
-  if (os.platform() !== 'win32') {
+  if ((ctx.platform ?? os.platform()) !== 'win32') {
     return { platform: process.platform, skipped: true };
   }
   const script = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
+    agentRootOf(ctx),
     'scripts',
     'check-windows-git-perf.js',
   );

package/.agents/scripts/lib/clean-temp.js

@@ -0,0 +1,440 @@
+/**
+ * `/clean-temp` engine: sorts every top-level entry under the project's
+ * tempRoot into one bucket and, on `--execute`, deletes the confirmed
+ * buckets through the temp-retention engine — there is no second walker.
+ *
+ * Buckets: `framework` (a class entry the auto-purge would take),
+ * `closed-issue` (an unrecognized entry naming exactly one closed issue),
+ * `aged` (an unrecognized id-less entry past `staleDays`), and `kept`.
+ */
+
+import { realpathSync } from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { mainCheckoutRoot, tempRootFrom } from './config/temp-paths.js';
+import { removeSparingKept, safeReaddir } from './temp-removal.js';
+import {
+  collectTempEntries,
+  formatBytes,
+  isReservedTopLevel,
+  resolveTempRetention,
+  sweepTempRetention,
+} from './temp-retention.js';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Deletable buckets, in execution order. `aged` is never deleted under `--yes`. */
+const DELETABLE_BUCKETS = Object.freeze(['framework', 'closed-issue', 'aged']);
+const UNATTENDED_BUCKETS = Object.freeze(['framework', 'closed-issue']);
+
+/**
+ * A standalone run of 1–7 digits, no leading zero, not glued to a letter or
+ * digit — so a hash fragment, a timestamp or a version suffix is not an id.
+ */
+const ID_TOKEN = /(?<![A-Za-z0-9])[1-9]\d{0,6}(?![A-Za-z0-9])/g;
+
+const silent = Object.freeze({ info: () => {} });
+
+/**
+ * Distinct issue-id candidates in a basename (extension stripped). More than
+ * one means the entry cannot be attributed to any of them.
+ *
+ * @param {string} name
+ * @returns {number[]}
+ */
+function idCandidates(name) {
+  const stem = name.replace(/\.[^.]*$/, '');
+  return [...new Set(stem.match(ID_TOKEN) ?? [])].map(Number);
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {{ execute: boolean, yes: boolean, json: boolean, cwd: string|undefined }}
+ */
+function parseCleanTempArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      execute: { type: 'boolean', default: false },
+      yes: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      cwd: { type: 'string' },
+    },
+    strict: true,
+  });
+  return values;
+}
+
+/** `realpath` when the path exists, else a plain resolve. */
+function canonical(target) {
+  try {
+    return realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+/**
+ * The tempRoot a relative `project.paths.tempRoot` names, anchored at the
+ * project root, and whether it lies strictly inside that root.
+ *
+ * @param {string} projectRoot
+ * @param {object} config
+ * @returns {{ tempRoot: string, inside: boolean }}
+ */
+function resolveScopedTempRoot(projectRoot, config) {
+  const raw = tempRootFrom(config);
+  const tempRoot = canonical(
+    path.isAbsolute(raw) ? raw : path.join(projectRoot, raw),
+  );
+  const rel = path.relative(canonical(projectRoot), tempRoot);
+  const inside = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  return { tempRoot, inside };
+}
+
+/**
+ * Issue states, read once per id. A failed read is `error`, which every
+ * caller treats as "not closed" — reads fail safe.
+ *
+ * @param {object|null} provider
+ * @param {Iterable<number>} ids
+ * @returns {Promise<Map<number, 'closed'|'open'|'error'>>}
+ */
+async function readIssueStates(provider, ids) {
+  const states = new Map();
+  for (const id of ids) {
+    try {
+      const ticket = await provider.getTicket(id);
+      const state = String(ticket?.state ?? '').toLowerCase();
+      states.set(id, state === 'closed' ? 'closed' : 'open');
+    } catch {
+      states.set(id, 'error');
+    }
+  }
+  return states;
+}
+
+/** Top-level name of `target` beneath `tempRoot`. */
+function topLevelName(tempRoot, target) {
+  return path.relative(tempRoot, target).split(path.sep)[0];
+}
+
+/** Every id the scan could need a state for. */
+function idsToRead(scan) {
+  const ids = new Set();
+  for (const entry of scan.entries) {
+    if (entry.storyId !== null) ids.add(entry.storyId);
+  }
+  for (const u of scan.unrecognized) {
+    const candidates = idCandidates(path.basename(u.path));
+    if (candidates.length === 1) ids.add(candidates[0]);
+  }
+  return ids;
+}
+
+/** Closed ids among `states`. */
+function closedIds(states) {
+  return [...states].filter(([, s]) => s === 'closed').map(([id]) => id);
+}
+
+/**
+ * Bucket one unrecognized entry.
+ *
+ * @param {{ path: string, bytes: number, mtimeMs: number }} u
+ * @param {Map<number, string>} states
+ * @param {{ now: number, staleMs: number }} ctx
+ * @returns {{ bucket: string, reason: string }}
+ */
+function classifyUnrecognized(u, states, ctx) {
+  const ids = idCandidates(path.basename(u.path));
+  if (ids.length === 1) {
+    const state = states.get(ids[0]);
+    if (state === 'closed') {
+      return { bucket: 'closed-issue', reason: `issue #${ids[0]} closed` };
+    }
+    const why = state === 'open' ? 'open' : 'read failed';
+    return { bucket: 'kept', reason: `issue #${ids[0]} ${why}` };
+  }
+  const label = ids.length === 0 ? 'no id' : `${ids.length} ids`;
+  if (ctx.now - u.mtimeMs >= ctx.staleMs) {
+    return { bucket: 'aged', reason: `${label}, past staleDays` };
+  }
+  return { bucket: 'kept', reason: `${label}, too recent` };
+}
+
+/**
+ * One row per top-level entry under tempRoot.
+ *
+ * @param {object} args
+ * @returns {Promise<object[]>}
+ */
+async function buildRows({ tempRoot, scan, preview, states, ctx, fsp }) {
+  const spent = new Map();
+  for (const p of preview.purged) {
+    const name = topLevelName(tempRoot, p.path);
+    const acc = spent.get(name) ?? { count: 0, bytes: 0 };
+    spent.set(name, { count: acc.count + 1, bytes: acc.bytes + p.bytes });
+  }
+  const unrecognized = new Map(
+    scan.unrecognized.map((u) => [path.basename(u.path), u]),
+  );
+  const rows = [];
+  for (const dirent of await safeReaddir(fsp, tempRoot)) {
+    const { name } = dirent;
+    const row = { entry: name, path: path.join(tempRoot, name), bytes: 0 };
+    const u = unrecognized.get(name);
+    if (isReservedTopLevel(name)) {
+      rows.push({ ...row, bucket: 'kept', reason: 'reserved' });
+    } else if (u) {
+      const ageDays = Math.floor((ctx.now - u.mtimeMs) / MS_PER_DAY);
+      rows.push({
+        ...row,
+        bytes: u.bytes,
+        ageDays,
+        ...classifyUnrecognized(u, states, ctx),
+      });
+    } else if (spent.has(name)) {
+      const { count, bytes } = spent.get(name);
+      rows.push({
+        ...row,
+        bytes,
+        bucket: 'framework',
+        reason: `${count} spent artifact(s)`,
+      });
+    } else {
+      rows.push({ ...row, bucket: 'kept', reason: 'framework: nothing spent' });
+    }
+  }
+  return rows.sort((a, b) => a.entry.localeCompare(b.entry));
+}
+
+/**
+ * @param {object[]} rows
+ * @returns {Record<string, { count: number, bytes: number }>}
+ */
+function bucketTotals(rows) {
+  const totals = {};
+  for (const bucket of [...DELETABLE_BUCKETS, 'kept']) {
+    const inBucket = rows.filter((r) => r.bucket === bucket);
+    totals[bucket] = {
+      count: inBucket.length,
+      bytes: inBucket.reduce((sum, r) => sum + r.bytes, 0),
+    };
+  }
+  return totals;
+}
+
+/**
+ * @param {object[]} rows
+ * @returns {string}
+ */
+function renderTable(rows) {
+  const lines = [
+    'bucket        entry                                    size      age   reason',
+  ];
+  for (const r of rows) {
+    const age = r.ageDays === undefined ? '-' : `${r.ageDays}d`;
+    lines.push(
+      `${r.bucket.padEnd(13)} ${r.entry.padEnd(40)} ${formatBytes(r.bytes).padStart(8)} ${age.padStart(5)}   ${r.reason}`,
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The operator-confirmed deletion of unrecognized entries: each path is
+ * re-verified as still unrecognized by a fresh scan before it goes.
+ *
+ * @param {{ tempRoot: string, paths: string[], fsp: typeof fsPromises }} args
+ * @returns {Promise<{ bytes: number, errors: string[] }>}
+ */
+async function purgeUnrecognizedEntries({ tempRoot, paths, fsp }) {
+  const { unrecognized } = await collectTempEntries({ tempRoot, fsp });
+  const allowed = new Set(unrecognized.map((u) => u.path));
+  const out = { bytes: 0, errors: [] };
+  for (const target of paths) {
+    if (!allowed.has(target)) {
+      out.errors.push(`${target}: no longer an unrecognized entry — kept`);
+      continue;
+    }
+    try {
+      out.bytes += (await removeSparingKept(fsp, target)).bytes;
+    } catch (err) {
+      out.errors.push(`${target}: ${String(err?.message ?? err)}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Delete one bucket through the engine.
+ *
+ * @returns {Promise<{ bytes: number, errors: string[] }>}
+ */
+async function executeBucket(bucket, rows, env) {
+  if (bucket === 'framework') {
+    const result = await sweepTempRetention({
+      config: env.config,
+      tempRoot: env.tempRoot,
+      mergedStoryIds: env.closed,
+      now: env.now,
+      fsp: env.fsp,
+      logger: silent,
+      label: 'clean-temp',
+    });
+    return { bytes: result.bytesReclaimed, errors: result.errors };
+  }
+  return purgeUnrecognizedEntries({
+    tempRoot: env.tempRoot,
+    paths: rows.filter((r) => r.bucket === bucket).map((r) => r.path),
+    fsp: env.fsp,
+  });
+}
+
+/**
+ * Decide whether a bucket may be deleted this run.
+ *
+ * @returns {Promise<{ run: boolean, note?: string }>}
+ */
+async function approveBucket(bucket, total, opts, confirm) {
+  if (total.count === 0) return { run: false };
+  if (opts.yes) {
+    return UNATTENDED_BUCKETS.includes(bucket)
+      ? { run: true }
+      : { run: false, note: 'never deleted unattended — rerun without --yes' };
+  }
+  const ok = await confirm(
+    `[clean-temp] Delete ${total.count} ${bucket} entr${total.count === 1 ? 'y' : 'ies'} (${formatBytes(total.bytes)})?`,
+  );
+  return ok ? { run: true } : { run: false, note: 'declined' };
+}
+
+/**
+ * @returns {Promise<{ executed: object, bytesReclaimed: number, errors: string[] }>}
+ */
+async function executeBuckets(rows, totals, opts, env) {
+  const executed = {};
+  let bytesReclaimed = 0;
+  const errors = [];
+  for (const bucket of DELETABLE_BUCKETS) {
+    const decision = await approveBucket(
+      bucket,
+      totals[bucket],
+      opts,
+      env.confirm,
+    );
+    if (!decision.run) {
+      executed[bucket] = { deleted: false, note: decision.note ?? 'empty' };
+      continue;
+    }
+    const result = await executeBucket(bucket, rows, env);
+    executed[bucket] = { deleted: true, bytes: result.bytes };
+    bytesReclaimed += result.bytes;
+    errors.push(...result.errors);
+  }
+  return { executed, bytesReclaimed, errors };
+}
+
+/**
+ * Run `/clean-temp`. Never calls `process.exit`; the CLI shell applies the
+ * returned exit code.
+ *
+ * @param {object} args
+ * @param {string[]} args.argv
+ * @param {string} args.cwd Invocation dir; `--cwd` overrides it.
+ * @param {(projectRoot: string) => object} args.loadConfig Resolved config bag.
+ * @param {(cwd: string) => string} [args.resolveRoot] The project root the
+ *   run is scoped to — the main checkout root, else `cwd` itself.
+ * @param {(config: object) => object} args.getProvider Lazy; called only when
+ *   an id needs a read.
+ * @param {(question: string) => Promise<boolean>} args.confirm
+ * @param {(text: string) => void} args.write stdout sink.
+ * @param {(text: string) => void} args.writeErr stderr sink.
+ * @param {number} [args.now]
+ * @param {typeof fsPromises} [args.fsp]
+ * @returns {Promise<{ exitCode: number, envelope: object }>}
+ */
+export async function runCleanTemp({
+  argv,
+  cwd,
+  loadConfig,
+  resolveRoot = (dir) => mainCheckoutRoot(dir) ?? dir,
+  getProvider,
+  confirm,
+  write,
+  writeErr,
+  now = Date.now(),
+  fsp = fsPromises,
+}) {
+  const opts = parseCleanTempArgs(argv);
+  const projectRoot = resolveRoot(path.resolve(opts.cwd ?? cwd));
+  const config = loadConfig(projectRoot);
+  const { tempRoot, inside } = resolveScopedTempRoot(projectRoot, config);
+  if (!inside) {
+    writeErr(
+      `[clean-temp] refusing: tempRoot ${tempRoot} is not inside the project root ${projectRoot}.\n`,
+    );
+    return {
+      exitCode: 1,
+      envelope: { kind: 'clean-temp', refused: true, tempRoot, projectRoot },
+    };
+  }
+
+  const policy = resolveTempRetention(config);
+  const ctx = { now, staleMs: policy.staleDays * MS_PER_DAY };
+  const scan = await collectTempEntries({ config, tempRoot, fsp });
+  const ids = idsToRead(scan);
+  const states =
+    ids.size > 0 ? await readIssueStates(getProvider(config), ids) : new Map();
+  const closed = closedIds(states);
+  const preview = await sweepTempRetention({
+    config,
+    tempRoot,
+    mergedStoryIds: closed,
+    now,
+    fsp,
+    dryRun: true,
+    logger: silent,
+  });
+  const rows = await buildRows({ tempRoot, scan, preview, states, ctx, fsp });
+  const totals = bucketTotals(rows);
+  const envelope = {
+    kind: 'clean-temp',
+    tempRoot,
+    dryRun: !opts.execute,
+    staleDays: policy.staleDays,
+    buckets: totals,
+    entries: rows.map(({ path: _p, ...r }) => r),
+    executed: null,
+    bytesReclaimed: 0,
+    errors: [],
+  };
+
+  if (!opts.json) write(renderTable(rows));
+  if (opts.execute) {
+    const env = { config, tempRoot, closed, now, fsp, confirm };
+    Object.assign(envelope, await executeBuckets(rows, totals, opts, env));
+  }
+  if (opts.json) write(`${JSON.stringify(envelope)}\n`);
+  else write(renderSummary(envelope));
+  return { exitCode: envelope.errors.length > 0 ? 1 : 0, envelope };
+}
+
+/**
+ * @param {object} envelope
+ * @returns {string}
+ */
+function renderSummary(envelope) {
+  const parts = Object.entries(envelope.buckets).map(
+    ([bucket, t]) => `${bucket}=${t.count} (${formatBytes(t.bytes)})`,
+  );
+  const head = envelope.dryRun
+    ? '[clean-temp] dry run — nothing deleted; pass --execute to delete.'
+    : `[clean-temp] reclaimed ${formatBytes(envelope.bytesReclaimed)}.`;
+  const errors = envelope.errors
+    .map((e) => `[clean-temp] error: ${e}\n`)
+    .join('');
+  return `${head} ${parts.join(' · ')}\n${errors}`;
+}