@1aboveio/skills 1.0.10 → 1.0.12

package/skills/engineering/resolve-issues/scripts/cleanup-runs.mjs

@@ -1,364 +1,232 @@
 #!/usr/bin/env node
-// Reclaim disk from finished resolve-issues runs without losing work or evidence.
+// Owned unit workspaces: prepare, clean up, recover, and inventory.
 //
-//   cleanup-runs.mjs [--repo <dir>] [--older-than-days <n>] [--log-days <n>] [--apply]
-//   cleanup-runs.mjs --merged <unit-workspace> [--apply]
+//   cleanup-runs.mjs prepare  --run <run dir> --unit <id> --revision <n> [--apply] [--json] [--kind worktree|clone]
+//   cleanup-runs.mjs cleanup  --run <run dir> --unit <id> --revision <n> [--apply] [--json]
+//   cleanup-runs.mjs recover  --repo <repo root> --json
+//   cleanup-runs.mjs inventory --repo <repo root> [--root <dir>] [--max-entries <n>] [--max-depth <n>] --json
 //
-// Sweep mode looks at every run under <repo>/.resolve-issues/rush/, aged by its
-// task-plan.json (the file the orchestrator saves on every transition):
+// Legacy entry points, kept because the coordinator's references still call them:
 //
-//   idle under --older-than-days (default 3)   untouched
-//   idle under --log-days (default 30)         downloads go; records and logs stay
-//   idle longer                                records stay; logs go too
+//   cleanup-runs.mjs --repo <repo root> [--apply] [--json]
+//   cleanup-runs.mjs --merged <unit-workspace-or-resource> [--apply] [--json]
 //
-// Downloads are everything that can be fetched or rebuilt: tool caches, SDKs,
-// browsers, emulator disks, installs, builds, and a clean clone's tracked source
-// and .git. Logs are text evidence (.log, .txt, .json, .jsonl, .md, .out, .err,
-// logcat) up to EVIDENCE_MAX_BYTES, wherever they sit, except inside a tool
-// cache; inside a non-Git copy of a repository (a folder with a lockfile) only
-// .log and logcat files, and text under test-results/, logs/, and similar. Records are the run's own small .json, .jsonl and .md files near the
-// top of the run, outside any clone.
+// --repo is a safe owned completed-unit sweep, never an age-based disk sweep. It only
+// considers units the plan records as succeeded with delivery merged, and then applies the
+// same safety checks as `cleanup`. --merged resolves the saved run and unit that own the
+// path; an unowned path is refused. Neither mode strips ignored files, deletes logs, or
+// removes anything by mtime.
 //
-// A Git workspace never loses work. A clean one with nothing unpushed loses its
-// tracked files, .git and downloads and keeps its logs. One with uncommitted
-// changes, unpushed commits, or a stash keeps everything git tracks or would
-// show as untracked; only its git-ignored paths are swept.
-//
-// --merged handles one unit workspace whose PR has merged: its commits are on
-// the target, so it counts as clean unless it has uncommitted changes or a
-// stash. Its logs stay.
-//
-// Without --apply nothing is touched; the actions are printed. The last line is
-// always a one-line summary. Exit 0 on success, 2 for a bad command.
+// The helper never writes task-plan.json. `prepare` and `cleanup` return the next lifecycle
+// as JSON; the coordinator persists it through update_plan. A successful removal writes a
+// postcondition receipt under <run>/results/<unit>-cleanup.json.
 
 import { execFileSync } from 'node:child_process'
-import { existsSync, lstatSync, readdirSync, rmdirSync, rmSync, statSync, statfsSync } from 'node:fs'
-import { dirname, join, relative, resolve, sep } from 'node:path'
+import { existsSync } from 'node:fs'
 
 import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  INVENTORY_MAX_DEPTH, INVENTORY_MAX_ENTRIES, LifecycleError, cleanup, cleanupMerged, inventory, prepare, recover, sweep,
+} from './workspace-lifecycle.mjs'
 
-export const DEFAULT_OLDER_THAN_DAYS = 3
-export const DEFAULT_LOG_DAYS = 30
-// Records live near the top of a run: task-plan.json, exploration/, sources/,
-// reviews/<round>/review.json.
-export const RECORD_MAX_DEPTH = 4
-export const RECORD_MAX_BYTES = 1024 * 1024
-export const EVIDENCE_MAX_BYTES = 20 * 1024 * 1024
-const RECORD_EXTENSIONS = ['.json', '.jsonl', '.md']
-const EVIDENCE_EXTENSIONS = ['.log', '.txt', '.json', '.jsonl', '.md', '.out', '.err']
-// Directories that only ever hold downloads or build output.
-export const CACHE_DIRS = new Set([
-  'node_modules', '.cache', 'cache', 'caches', 'xdg-cache', '.gradle', '.npm', '.pnpm-store', '.m2', '.android',
-  'android-sdk', 'sdk', 'system-images', 'build', 'dist', '.cxx', '.next', '.turbo', 'browsers',
-  'playwright-browsers', 'ms-playwright', '.venv', 'venv', '__pycache__', 'DerivedData', 'Pods',
-])
-// A non-Git folder with one of these at its root is a copy of a repository:
-// inside it, only logs and text under an evidence folder count as evidence.
-const LOCKFILES = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb', 'uv.lock', 'poetry.lock', 'Cargo.lock', 'go.sum', 'Gemfile.lock']
-const EVIDENCE_DIRS = new Set(['test-results', 'logs', 'log', 'reports', 'artifacts', 'playwright-report'])
-const DAY_MS = 24 * 60 * 60 * 1000
+export { LifecycleError } from './workspace-lifecycle.mjs'
 
-export class CleanupError extends Error {}
+const USAGE = `usage: cleanup-runs.mjs prepare --run <run dir> --unit <id> --revision <n> [--apply] [--json] [--kind worktree|clone]
+       cleanup-runs.mjs cleanup --run <run dir> --unit <id> --revision <n> [--apply] [--json]
+       cleanup-runs.mjs recover --repo <repo root> --json
+       cleanup-runs.mjs inventory --repo <repo root> [--root <dir>] [--max-entries <n>] [--max-depth <n>] --json
+       cleanup-runs.mjs --repo <repo root> [--apply] [--json]
+       cleanup-runs.mjs --merged <unit-workspace-or-resource> [--apply] [--json]
 
-function git(dir, args) {
-  return execFileSync('git', ['-C', dir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024 })
-}
+exit 0: the command ran and every removal it planned succeeded, or it was a read-only plan
+exit 1: a path was retained/refused for a safety reason, or --apply could not finish a removal
+exit 2: bad arguments, unreadable or contradictory plan, revision mismatch, lock held, or unowned path`
 
-// What unsaved work a Git workspace holds. `null` when Git cannot read it.
-export function workspaceState(dir) {
-  try {
-    const changed = git(dir, ['status', '--porcelain']).split('\n').filter(Boolean).length
-    const unpushed = Number(git(dir, ['rev-list', '--count', 'HEAD', '--branches', '--not', '--remotes']).trim())
-    const stashed = git(dir, ['stash', 'list']).split('\n').filter(Boolean).length
-    return { changed, unpushed, stashed }
-  } catch {
-    return null
-  }
-}
+const COMMANDS = new Set(['prepare', 'cleanup', 'recover', 'inventory'])
 
-const isGitWorkspace = (dir) => existsSync(join(dir, '.git'))
-const isCacheDir = (name) => CACHE_DIRS.has(name) || name.endsWith('.avd')
-const isEvidenceName = (name) => EVIDENCE_EXTENSIONS.some((ext) => name.endsWith(ext)) || /logcat/i.test(name)
-const isLogName = (name) => name.endsWith('.log') || /logcat/i.test(name)
-const isSourceCopy = (dir) => LOCKFILES.some((f) => existsSync(join(dir, f)))
+class UsageError extends Error {}
 
-// Entering a repository copy starts fresh: only evidence folders inside it count.
-function enterDir(ctx, name, path) {
-  if (isSourceCopy(path)) return { sourceCopy: true, inEvidenceDir: false }
-  return { sourceCopy: ctx.sourceCopy, inEvidenceDir: ctx.inEvidenceDir || EVIDENCE_DIRS.has(name) }
+function positiveInt(value, flag, { allowZero = false } = {}) {
+  const n = Number(value)
+  if (!Number.isSafeInteger(n) || n < (allowZero ? 0 : 1)) throw new UsageError(`${flag} must be ${allowZero ? 'a nonnegative' : 'a positive'} integer`)
+  return n
 }
 
-function describe(state) {
-  const parts = []
-  if (state.changed) parts.push(`${state.changed} uncommitted file(s)`)
-  if (state.unpushed) parts.push(`${state.unpushed} unpushed commit(s)`)
-  if (state.stashed) parts.push(`${state.stashed} stash(es)`)
-  return parts.join(', ')
-}
-
-// What happens to one file: kept as a record, kept as a log, or deleted.
-function fileFate(name, path, ctx) {
-  if (ctx.tracked?.has(path)) return 'delete'
-  const size = statSync(path).size
-  const isRecord = !ctx.inClone && !ctx.hidden && ctx.depth <= RECORD_MAX_DEPTH
-    && RECORD_EXTENSIONS.some((ext) => name.endsWith(ext)) && size <= RECORD_MAX_BYTES
-  if (isRecord) return 'record'
-  const evidence = ctx.sourceCopy && !ctx.inEvidenceDir ? isLogName(name) : isEvidenceName(name)
-  if (ctx.keepLogs && evidence && size <= EVIDENCE_MAX_BYTES) return 'log'
-  return 'delete'
-}
-
-// Actions for one directory. Returns { actions, kept, logs }; a directory with
-// nothing kept collapses into a single delete.
-function sweep(dir, ctx) {
-  const actions = []
-  let kept = false
-  let logs = 0
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const path = join(dir, entry.name)
-    if (entry.isDirectory()) {
-      if (isCacheDir(entry.name) || (ctx.inClone && entry.name === '.git')) {
-        actions.push({ kind: 'delete', path })
-        continue
-      }
-      if (!ctx.inClone && isGitWorkspace(path)) {
-        const action = workspaceAction(path, { keepLogs: ctx.keepLogs, depth: ctx.depth + 1 })
-        actions.push(action)
-        logs += action.logs ?? 0
-        if (action.kind !== 'delete') kept = true
-        continue
-      }
-      const sub = sweep(path, {
-        ...ctx,
-        depth: ctx.depth + 1,
-        hidden: ctx.hidden || entry.name.startsWith('.'),
-        ...enterDir(ctx, entry.name, path),
-      })
-      if (sub.kept) {
-        actions.push(...sub.actions)
-        kept = true
-        logs += sub.logs
-      } else {
-        actions.push({ kind: 'delete', path })
-      }
-    } else if (entry.isFile()) {
-      const fate = fileFate(entry.name, path, ctx)
-      if (fate === 'delete') actions.push({ kind: 'delete', path })
-      else {
-        kept = true
-        if (fate === 'log') logs++
-      }
-    } else {
-      actions.push({ kind: 'delete', path })
-    }
+export function parseArgs(argv) {
+  const opts = {
+    command: null, run: null, unit: null, revision: null, repo: null, merged: null,
+    apply: false, json: false, help: false, kind: null, root: null,
+    maxEntries: INVENTORY_MAX_ENTRIES, maxDepth: INVENTORY_MAX_DEPTH,
   }
-  return { actions, kept, logs }
-}
-
-const zList = (out) => out.split('\0').filter(Boolean)
-
-export function workspaceAction(dir, { merged = false, keepLogs = true, depth = 1 } = {}) {
-  const state = workspaceState(dir)
-  if (!state) return { kind: 'keep', path: dir, reason: 'Git cannot read this workspace', deletes: [], logs: 0 }
-  const unsaved = { ...state, unpushed: merged ? 0 : state.unpushed }
-  const ctx = { depth, hidden: false, inClone: true, keepLogs }
-  if (!unsaved.changed && !unsaved.unpushed && !unsaved.stashed) {
-    const tracked = new Set(zList(git(dir, ['ls-files', '-z'])).map((p) => join(dir, p)))
-    const sub = sweep(dir, { ...ctx, tracked })
-    const reason = merged ? 'merged and clean' : 'clean and pushed'
-    if (!sub.kept) return { kind: 'delete', path: dir, reason, deletes: [], logs: 0 }
-    return { kind: 'sweep', path: dir, reason: `${reason}; keeps ${sub.logs} log file(s)`, deletes: sub.actions, logs: sub.logs }
-  }
-  // Only git-ignored paths are fair game; tracked and untracked files are work.
-  const deletes = []
-  let logs = 0
-  for (const rel of zList(git(dir, ['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z']))) {
-    const path = join(dir, rel)
-    if (!existsSync(path)) continue
-    const name = rel.replace(/\/$/, '').split('/').pop()
-    if (lstatSync(path).isDirectory()) {
-      if (isCacheDir(name)) { deletes.push({ kind: 'delete', path }); continue }
-      const sub = sweep(path, { ...ctx, depth: depth + rel.split('/').length, ...enterDir({ ...ctx, sourceCopy: false, inEvidenceDir: false }, name, path) })
-      if (sub.kept) { deletes.push(...sub.actions); logs += sub.logs } else deletes.push({ kind: 'delete', path })
-    } else if (fileFate(name, path, ctx) === 'delete') {
-      deletes.push({ kind: 'delete', path })
-    } else {
-      logs++
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (COMMANDS.has(arg) && !opts.command) { opts.command = arg; continue }
+    if (arg === '--apply') { opts.apply = true; continue }
+    if (arg === '--json') { opts.json = true; continue }
+    if (arg === '--help' || arg === '-h') { opts.help = true; continue }
+    const value = () => {
+      if (argv[i + 1] === undefined || argv[i + 1].startsWith('--')) throw new UsageError(`${arg} needs a value`)
+      return argv[++i]
     }
-  }
-  return { kind: 'strip', path: dir, reason: `keeps ${describe(unsaved)} and ${logs} log file(s); removes ignored downloads`, deletes, logs }
-}
-
-function lastActive(runDir) {
-  const plan = join(runDir, 'task-plan.json')
-  return (existsSync(plan) ? statSync(plan) : statSync(runDir)).mtimeMs
+    if (arg === '--run') opts.run = value()
+    else if (arg === '--unit') opts.unit = value()
+    else if (arg === '--revision') opts.revision = positiveInt(value(), '--revision', { allowZero: true })
+    else if (arg === '--repo') opts.repo = value()
+    else if (arg === '--merged') opts.merged = value()
+    else if (arg === '--kind') opts.kind = value()
+    else if (arg === '--root') opts.root = value()
+    else if (arg === '--max-entries') opts.maxEntries = positiveInt(value(), '--max-entries')
+    else if (arg === '--max-depth') opts.maxDepth = positiveInt(value(), '--max-depth', { allowZero: true })
+    else if (arg === '--older-than-days' || arg === '--log-days') {
+      throw new UsageError(`${arg} was removed: age no longer authorizes a deletion. A workspace is cleaned only from task-plan ownership, completion, and the safety checks. Run inventory to see what is on disk`)
+    } else throw new UsageError(`unrecognized argument ${arg}`)
+  }
+  if (!opts.command && !opts.merged && !opts.repo) throw new UsageError('no command, --repo, or --merged given')
+  if (opts.command === 'prepare' || opts.command === 'cleanup') {
+    if (!opts.run) throw new UsageError(`${opts.command} needs --run`)
+    if (!opts.unit) throw new UsageError(`${opts.command} needs --unit`)
+    if (opts.revision === null) throw new UsageError(`${opts.command} needs --revision`)
+    if (opts.merged) throw new UsageError(`${opts.command} does not take --merged`)
+  }
+  if ((opts.command === 'recover' || opts.command === 'inventory') && !opts.repo) throw new UsageError(`${opts.command} needs --repo`)
+  if (opts.command === 'recover' && opts.apply) throw new UsageError('recover is read-only and does not take --apply')
+  if (opts.command === 'inventory' && opts.apply) throw new UsageError('inventory is read-only and does not take --apply')
+  if (opts.command === 'prepare' && opts.root) throw new UsageError('prepare does not take --root')
+  if (opts.command && opts.merged) throw new UsageError(`${opts.command} does not take --merged`)
+  return opts
 }
 
-export function planSweep({ repo, olderThanDays = DEFAULT_OLDER_THAN_DAYS, logDays = DEFAULT_LOG_DAYS, now = Date.now() }) {
-  const root = join(repo, '.resolve-issues', 'rush')
-  if (!existsSync(root)) return { root, runs: [] }
-  const runs = []
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue
-    const dir = join(root, entry.name)
-    const idleDays = (now - lastActive(dir)) / DAY_MS
-    if (idleDays < olderThanDays) {
-      runs.push({ run: entry.name, dir, idleDays, stage: 'active', actions: [], logs: 0 })
-      continue
-    }
-    const keepLogs = idleDays < logDays
-    const result = sweep(dir, { depth: 1, hidden: false, inClone: false, keepLogs })
-    runs.push({ run: entry.name, dir, idleDays, stage: keepLogs ? 'keep-logs' : 'records-only', actions: result.actions, logs: result.logs })
-  }
-  runs.sort((a, b) => a.run.localeCompare(b.run))
-  return { root, runs }
+function ghAvailableRunner() {
+  if (process.env.CLEANUP_RUNS_NO_GH === '1') return null
+  return (args) => execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30000, maxBuffer: 4 * 1024 * 1024 })
 }
 
-export function planMerged(workspace) {
-  const dir = resolve(workspace)
-  if (!dir.split(sep).includes('.resolve-issues')) {
-    throw new CleanupError(`--merged only removes workspaces under a .resolve-issues directory: ${dir}`)
-  }
-  if (!existsSync(dir) || !lstatSync(dir).isDirectory() || !isGitWorkspace(dir)) {
-    throw new CleanupError(`not a Git workspace: ${dir}`)
-  }
-  return workspaceAction(dir, { merged: true, keepLogs: true })
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`)
 }
 
-// Remove directories left empty under `dir` (bottom-up), and `dir` itself.
-function pruneEmpty(dir) {
-  if (!existsSync(dir) || !lstatSync(dir).isDirectory()) return
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isDirectory()) pruneEmpty(join(dir, entry.name))
+function failure(command, error) {
+  const code = error instanceof LifecycleError || error instanceof UsageError ? error.code ?? 'usage' : 'error'
+  return {
+    version: 1,
+    command,
+    ok: false,
+    applied: false,
+    action: 'refuse',
+    reason: error.message,
+    code,
+    error: { code, message: error.message, ...(error.details ? { details: error.details } : {}) },
+    errors: [error.message],
   }
-  if (readdirSync(dir).length === 0) rmdirSync(dir)
 }
 
-// Delete one path. Package stores (pnpm, Gradle) mark their files and folders
-// read-only, so on a permission failure grant the owner write access and retry.
-// Returns an error message, or null on success.
-function remove(path) {
-  try {
-    rmSync(path, { recursive: true, force: true })
-    return null
-  } catch {
-    try {
-      execFileSync('chmod', ['u+w', dirname(path)], { stdio: 'ignore' })
-      execFileSync('chmod', ['-R', 'u+w', path], { stdio: 'ignore' })
-      rmSync(path, { recursive: true, force: true })
-      return null
-    } catch (error) {
-      return `${path}: ${error.code ?? error.message}`
-    }
-  }
+function renderPrepare(result) {
+  const lines = []
+  const dry = result.applied ? '' : ' (dry run)'
+  lines.push(`prepare${dry}: ${result.action} ${result.workspace.kind} ${result.workspace.path}`)
+  lines.push(`  base ${result.workspace.baseSha}  revision ${result.revision}  unit ${result.unit}`)
+  if (result.resources.length) lines.push(`  resources: ${result.resources.map((r) => `${r.role}${r.path}`).join(', ')}`)
+  if (!result.applied) lines.push('  nothing was created; rerun with --apply')
+  return lines.join('\n')
 }
 
-// Apply one action; returns the paths it could not remove.
-export function applyAction(action) {
-  const failures = []
-  const del = (path) => {
-    const failure = remove(path)
-    if (failure) failures.push(failure)
-  }
-  if (action.kind === 'delete') del(action.path)
-  else if (action.kind === 'sweep' || action.kind === 'strip') {
-    for (const d of action.deletes) del(d.path)
-    if (action.kind === 'sweep' && failures.length === 0) pruneEmpty(action.path)
-  }
-  return failures
+function renderCleanup(result) {
+  const lines = []
+  const verb = result.applied ? '' : ' (dry run)'
+  const target = result.workspace?.path ?? result.paths?.[0] ?? ''
+  lines.push(`${result.command}${verb}: ${result.action} ${target}`)
+  if (result.reason) lines.push(`  ${result.reason}`)
+  for (const check of result.checks ?? []) lines.push(`  ${check.ok ? 'ok  ' : 'FAIL'} ${check.name}: ${check.detail}`)
+  if (result.receipt) lines.push(`  receipt ${result.receipt}`)
+  if (result.wouldRemove) lines.push('  nothing was removed; rerun with --apply')
+  return lines.join('\n')
 }
 
-const deletionCount = (actions) => actions.reduce((n, a) => n + (a.kind === 'delete' ? 1 : (a.deletes?.length ?? 0)), 0)
-
-function freeBytes(dir) {
-  try {
-    const s = statfsSync(dir)
-    return s.bavail * s.bsize
-  } catch {
-    return null
+function renderSweep(result) {
+  const lines = [`sweep${result.applied ? '' : ' (dry run)'}: ${result.repo}`]
+  for (const run of result.runs) {
+    lines.push(`  run ${run.run}${run.revision !== null ? ` (revision ${run.revision})` : ''}`)
+    for (const unit of run.units) {
+      lines.push(`    ${unit.unit}: ${unit.action}${unit.reason ? ` — ${unit.reason}` : ''}`)
+    }
   }
+  if (result.unknownEntries.length) lines.push(`  unknown entries (inventory only, never removed): ${result.unknownEntries.join(', ')}`)
+  const s = result.summary
+  lines.push(`  ${s.runs} run(s), ${s.completed} completed unit(s): ${s.removed} removed, ${s.retained} retained, ${s.refused} refused; ${s.unknown} unknown entr${s.unknown === 1 ? 'y' : 'ies'}`)
+  return lines.join('\n')
 }
 
-const gigabytes = (bytes) => `${(bytes / 1e9).toFixed(1)} GB`
-
-function parseArgs(argv) {
-  const usage = 'usage: cleanup-runs.mjs [--repo <dir>] [--older-than-days <n>] [--log-days <n>] [--apply] | --merged <unit-workspace> [--apply]'
-  const opts = { repo: process.cwd(), olderThanDays: DEFAULT_OLDER_THAN_DAYS, logDays: DEFAULT_LOG_DAYS, apply: false, merged: null }
-  const days = (value) => {
-    const n = Number(value)
-    if (!Number.isFinite(n) || n < 0) throw new CleanupError(usage)
-    return n
-  }
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]
-    if (arg === '--apply') opts.apply = true
-    else if (arg === '--repo' && argv[i + 1]) opts.repo = argv[++i]
-    else if (arg === '--merged' && argv[i + 1]) opts.merged = argv[++i]
-    else if (arg === '--older-than-days' && argv[i + 1]) opts.olderThanDays = days(argv[++i])
-    else if (arg === '--log-days' && argv[i + 1]) opts.logDays = days(argv[++i])
-    else throw new CleanupError(usage)
+function renderRecover(result) {
+  const lines = [`recover (read-only): ${result.repo}`]
+  for (const run of result.runs) {
+    for (const unit of run.units) lines.push(`  ${unit.unit}: ${unit.action}${unit.reason ? ` — ${unit.reason}` : ''}`)
   }
-  if (opts.logDays < opts.olderThanDays) throw new CleanupError('--log-days must be at least --older-than-days')
-  return opts
+  lines.push(`  ${result.due.length} due operation(s), ${result.worktrees.length} registered worktree(s), ${result.locks.length} lock(s)`)
+  return lines.join('\n')
 }
 
-function describeAction(a, base) {
-  const extra = a.deletes?.length ? `; ${a.deletes.length} path(s) to delete` : ''
-  return `${a.kind.padEnd(6)} ${relative(base, a.path) || '.'}${a.reason ? ` (${a.reason}${extra})` : ''}`
+function renderInventory(result) {
+  const lines = [`inventory (read-only): ${result.root}`]
+  lines.push(`  ${result.entries.length} entr${result.entries.length === 1 ? 'y' : 'ies'}${result.truncated ? ' (truncated)' : ''}; ${result.runs.length} run(s); ${result.registeredWorktrees.length} registered worktree(s)`)
+  if (result.reason) lines.push(`  ${result.reason}`)
+  return lines.join('\n')
 }
 
-function run(opts, out) {
-  const base = opts.merged ? resolve(opts.merged, '..') : opts.repo
-  const before = opts.apply ? freeBytes(base) : null
-  let actions
-  let summary
-  if (opts.merged) {
-    const action = planMerged(opts.merged)
-    out(describeAction(action, base))
-    actions = [action]
-    summary = `${action.kind} ${action.path}`
-  } else {
-    const plan = planSweep({ repo: resolve(opts.repo), olderThanDays: opts.olderThanDays, logDays: opts.logDays })
-    actions = []
-    let logs = 0
-    for (const r of plan.runs) {
-      const idle = `idle ${r.idleDays.toFixed(1)} days`
-      if (r.stage === 'active') {
-        out(`run ${r.run} (${idle}): skipped, used within ${opts.olderThanDays} days`)
-        continue
-      }
-      const note = r.stage === 'records-only' ? `records only, past ${opts.logDays} days` : `keeps records and ${r.logs} log file(s)`
-      out(`run ${r.run} (${idle}): ${note}${r.actions.length ? '' : '; nothing to remove'}`)
-      for (const a of r.actions) out(`  ${describeAction(a, r.dir)}`)
-      actions.push(...r.actions)
-      logs += r.logs
+export function main(argv) {
+  let opts
+  let command = argv.find((arg) => COMMANDS.has(arg)) ?? (argv.includes('--merged') ? 'merged' : 'sweep')
+  try {
+    opts = parseArgs(argv)
+    if (opts.help) { process.stdout.write(`${USAGE}\n`); return 0 }
+    command = opts.command ?? (opts.merged ? 'merged' : 'sweep')
+    const runGh = ghAvailableRunner()
+
+    if (command === 'prepare') {
+      const result = prepare({ run: opts.run, unit: opts.unit, revision: opts.revision, apply: opts.apply, kind: opts.kind })
+      if (opts.json) printJson(result)
+      else process.stdout.write(`${renderPrepare(result)}\n`)
+      return 0
     }
-    const swept = plan.runs.filter((r) => r.stage !== 'active').length
-    const count = (kind) => actions.filter((a) => a.kind === kind).length
-    summary = `${swept} idle run(s), ${plan.runs.length - swept} active; ${deletionCount(actions)} path(s) deleted, ${count('sweep')} clean clone(s) emptied, ${count('strip')} clone(s) with work stripped, ${count('keep')} unreadable kept; ${logs} log file(s) kept`
-  }
-  if (!opts.apply) {
-    out(`cleanup-runs: dry run, nothing removed; ${summary}. Rerun with --apply.`)
-    return
-  }
-  const failures = actions.flatMap((action) => applyAction(action))
-  for (const failure of failures) out(`  could not remove ${failure}`)
-  if (!opts.merged) {
-    try {
-      git(resolve(opts.repo), ['worktree', 'prune'])
-    } catch {}
+    if (command === 'cleanup') {
+      const result = cleanup({ run: opts.run, unit: opts.unit, revision: opts.revision, apply: opts.apply, requireApplying: true, runGh })
+      if (opts.json) printJson(result)
+      else process.stdout.write(`${renderCleanup(result)}\n`)
+      return result.ok ? 0 : (result.action === 'refuse' ? 2 : 1)
+    }
+    if (command === 'recover') {
+      const result = recover({ repo: opts.repo, runGh })
+      if (opts.json) printJson(result)
+      else process.stdout.write(`${renderRecover(result)}\n`)
+      return result.ok ? 0 : 2
+    }
+    if (command === 'inventory') {
+      const result = inventory({ repo: opts.repo, root: opts.root, maxEntries: opts.maxEntries, maxDepth: opts.maxDepth })
+      if (opts.json) printJson(result)
+      else process.stdout.write(`${renderInventory(result)}\n`)
+      return 0
+    }
+    if (command === 'merged') {
+      const result = cleanupMerged({ repo: opts.repo, path: opts.merged, apply: opts.apply, requireApplying: false, runGh: ghAvailableRunner() })
+      if (opts.json) printJson(result)
+      else process.stdout.write(`${renderCleanup(result)}\n`)
+      return result.ok ? 0 : 1
+    }
+    if (command === 'sweep') {
+      const result = sweep({ repo: opts.repo, apply: opts.apply, runGh })
+      if (opts.json) printJson(result)
+      else process.stdout.write(`${renderSweep(result)}\n`)
+      return result.ok ? 0 : 2
+    }
+    throw new UsageError(USAGE)
+  } catch (error) {
+    if (opts?.json) printJson(failure(command, error))
+    else process.stderr.write(`${error instanceof UsageError ? `${error.message}\n${USAGE}` : `${error.message}\n`}`)
+    if (error instanceof UsageError) return 2
+    if (error instanceof LifecycleError) return 2
+    return 2
   }
-  const after = freeBytes(base)
-  const freed = before !== null && after !== null ? `; freed ${gigabytes(Math.max(0, after - before))}` : ''
-  const failed = failures.length ? `; ${failures.length} path(s) could not be removed` : ''
-  out(`cleanup-runs: ${summary}${freed}${failed}`)
 }
 
 if (isMainModule(import.meta.url)) {
-  try {
-    run(parseArgs(process.argv.slice(2)), (line) => process.stdout.write(`${line}\n`))
-  } catch (error) {
-    process.stderr.write(`${error instanceof CleanupError ? error.message : error.stack}\n`)
-    process.exitCode = 2
-  }
+  process.exitCode = main(process.argv.slice(2))
 }