@1aboveio/skills 1.0.18 → 1.0.19

package/skills/engineering/resolve-issues/scripts/retention.mjs

@@ -0,0 +1,2314 @@
+#!/usr/bin/env node
+// Bounded, explicit-ownership retention for resolve-issues run resources.
+//
+//   retention.mjs plan     --repo <repo root> [--generated-days 7] [--artifact-days 30] [--json]
+//   retention.mjs apply    --repo <repo root> [--generated-days 7] [--artifact-days 30] [--json]
+//   retention.mjs register --repo <repo root> --run <run dir> --unit <id> --path <abs path>
+//                          --kind generated|artifact --last-used-at <ISO> --recipe <text>
+//                          [--format generic|pnpm-install|uv-venv|next-build|pnpm-store]
+//                          [--input <abs canonical rebuild input> ...] [--release-owner] [--json]
+//   retention.mjs register-owned --repo <repo root> --run <run dir> --unit <id>
+//                          --last-used-at <ISO> [--apply] [--json]
+//   retention.mjs status   --repo <repo root> [--run <run dir> --unit <id>] [--json]
+//   retention.mjs recover  --repo <repo root> [--apply] [--json]
+//
+// `register-owned` is the bounded batch form: it reads only the resources the unit's plan
+// declares, needs each one to carry explicit retention metadata (kind, format, recipe,
+// inputs), never discovers or adopts an unrecorded path, and never releases an owner. It
+// previews by default and registers through the same register API with --apply.
+//
+// `status` is read-only and reports, per registered resource, whether it is ready to reuse
+// or why a rebuild is required. `recover` is read-only by default and clears a retention
+// lock only when its owner record proves that process dead on this host.
+//
+// This is not a whole-run purge and not a second task-plan lifecycle. The canonical
+// manifest <repo>/.resolve-issues/retention.json is the only source of deletion
+// candidates: a resource must have been registered explicitly, by path, against the
+// unit that owns it. Existing run metadata is never a candidate, and no code here
+// infers disposability from a name, an extension, or an age.
+//
+// A registered resource is removable only when every check holds: the owner unit is
+// succeeded+merged (or the manifest carries an explicit ownerReleased approval), the
+// path is inside that unit's workspace or a declared resource, no other unit or run claims
+// the same tree as its workspace or resource, the tree contains only untracked/ignored
+// content in its containing Git workspace, no metadata-named files, no credential- or
+// secret-bearing path (environment file, registry or cloud credential, SSH identity,
+// private key, keystore), no nested Git, no external symlinks, no special files, no
+// required evidence, pin or checkpoint overlaps anywhere in the repository's plans, the
+// recorded lastUsedAt and the newest write are old enough, and no process (or an
+// unreadable process probe) uses the path. Two exceptions are narrow and typed: a
+// resource registered with a proven format (pnpm-install, uv-venv, next-build,
+// pnpm-store) may embed a vendored `source`/`sources`/`results`/`raw` name and may hold
+// external symbolic links, because those are references that a removal unlinks without
+// following. A credential, nested Git, special file, blocking run metadata name, or a
+// changed rebuild input still retains the tree, and a generic resource keeps every
+// strict check. A plan declaration that cannot be read is
+// uncertainty about a path that must survive, so only a complete evidence scan can
+// authorize a deletion. Content is hashed by streaming
+// it through a fixed buffer under a finite total and per-file bound, so a real multi-GiB
+// cache is snapshotted without allocating it, and a file that grows while it is read is
+// refused instead of silently truncated.
+//
+// --apply takes <repo>/.resolve-issues/.retention-lock (never reclaimed by age; the lock
+// schema and its liveness proof live in retention-lock.mjs), snapshots identity and
+// content, rechecks it immediately before and after an atomic same-parent quarantine
+// rename, writes receipts under <repo>/.resolve-issues/retention-receipts/, and only then
+// deletes the quarantined tree. A retained row is not an I/O failure; a failure to finish
+// an apply is. Before taking the lock, apply and register clear one only when its owner is
+// provably dead on this host, so an interrupted apply cannot block the next one forever.
+// Every other lock, receipt, and quarantined tree is left exactly as it was.
+//
+// Exit 0: plan/status/recover ran; apply had no I/O failure (retained rows are allowed);
+//         register saved; register-owned reported.
+// Exit 1: apply started but could not finish a removal (read the failed receipt).
+// Exit 2: usage, unreadable/contradictory manifest, held lock, or register refusal.
+
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import {
+  closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync,
+  readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync,
+  rmSync, unlinkSync, writeFileSync,
+} from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { containsPath, liveProcessesUsing, normPath } from '../../harness-runtime/workspace-lifecycle.mjs'
+import {
+  MAX_REBUILD_INPUTS, TYPED_FORMATS, classifyEmbeddedNames, classifyRebuildState,
+  inspectResourceFormat,
+} from './resource-formats.mjs'
+import {
+  RetentionLockError, acquireRetentionLock, inspectRetentionLock, recoverRetentionLock,
+} from './retention-lock.mjs'
+import { retentionPlanFiles } from './retention-plans.mjs'
+
+const MANIFEST_FILE = 'retention.json'
+const MANIFEST_VERSION = 1
+const RECEIPT_VERSION = 1
+const LOCK_NAME = '.retention-lock'
+const RECEIPT_DIR = 'retention-receipts'
+const QUARANTINE_PREFIX = '.retention-quarantine-'
+const KINDS = new Set(['generated', 'artifact'])
+// `generic` is the strict default: it carries no typed proof, so every metadata-name and
+// external-link check stays in force. The rest are proven formats from resource-formats.mjs.
+const FORMATS = new Set(['generic', ...TYPED_FORMATS])
+const MAX_BATCH_RESOURCES = 200
+const MAX_STATUS_RECEIPTS = 50
+// The slots a unit or the plan root may declare a path that must survive removal in.
+const EVIDENCE_KEYS = ['evidence', 'requiredEvidence', 'pins', 'checkpoints']
+const DAY_MS = 24 * 60 * 60 * 1000
+// Finite snapshot bounds. The total is a ceiling for one tree snapshot, not a size policy:
+// a real package or build cache comfortably fits, and a bound is still enforced.
+const MAX_TOTAL_HASH_BYTES = 16 * 1024 * 1024 * 1024
+const MAX_FILE_HASH_BYTES = 2 * 1024 * 1024 * 1024
+const HASH_CHUNK_BYTES = 2 * 1024 * 1024
+
+// Metadata that belongs to a run record, never to a disposable resource. These are
+// exact base names: a package.json or other harmless JSON is not on the list.
+const METADATA_NAMES = new Set([
+  'task-plan.json', 'issue-tree.json', 'taskplan.json', 'dropbox.json', 'findings.json',
+  'next-actions-seen.json', 'source', 'sources', 'decisions', 'findings', 'results',
+  'reviewverdicts', 'review-verdicts', 'briefs', 'profiling', 'checkpoints', 'raw', '.git',
+])
+
+// Credential and secret-bearing configuration, matched by base name only. The list is
+// deliberately finite: a guard that withheld every .json, .yml or source file would
+// classify ordinary cache configuration, lockfiles and vendored sources as secrets, and a
+// guard that is wrong most of the time is a guard that gets switched off. A single match
+// retains the whole candidate rather than trying to lift the one entry out, because
+// deciding whether a vendor's test fixture private key is synthetic means reading and
+// interpreting secret content — and this module never does that. It inspects names only.
+const CREDENTIAL_FILE_NAMES = new Set([
+  '.npmrc', '.netrc', '.yarnrc', '.yarnrc.yml', '.pypirc', '.git-credentials', '.htpasswd',
+  '.pgpass', '.my.cnf', 'credentials', 'credentials.db', 'keystore', 'truststore',
+  'application_default_credentials.json', 'service-account.json',
+])
+const CREDENTIAL_FILE_PREFIXES = ['.env', 'id_rsa', 'id_dsa', 'id_ecdsa', 'id_ed25519']
+const CREDENTIAL_FILE_SUFFIXES = ['.pem', '.key', '.p8', '.p12', '.pfx', '.keystore', '.jks', '.ppk']
+const CREDENTIAL_DIR_NAMES = new Set(['.ssh', '.aws', '.azure', '.gnupg', '.kube', '.docker', 'gcloud'])
+// Bounded reporting: the tree is retained either way, so only a readable sample is kept.
+const MAX_REPORTED_CREDENTIALS = 50
+
+function credentialName(name, isDirectory) {
+  const lower = String(name).toLowerCase()
+  if (isDirectory) {
+    if (CREDENTIAL_DIR_NAMES.has(lower)) return name
+    return lower.startsWith('.env') ? name : null
+  }
+  if (CREDENTIAL_FILE_NAMES.has(lower)) return name
+  if (CREDENTIAL_FILE_PREFIXES.some((prefix) => lower.startsWith(prefix))) return name
+  return CREDENTIAL_FILE_SUFFIXES.some((suffix) => lower.endsWith(suffix)) ? name : null
+}
+
+const USAGE = `usage: retention.mjs plan     --repo <repo root> [--generated-days 7] [--artifact-days 30] [--json]
+       retention.mjs apply    --repo <repo root> [--generated-days 7] [--artifact-days 30] [--json]
+       retention.mjs register --repo <repo root> --run <run dir> --unit <id> --path <abs path>
+                              --kind generated|artifact --last-used-at <ISO> --recipe <text>
+                              [--format generic|pnpm-install|uv-venv|next-build|pnpm-store]
+                              [--input <abs path> ...] [--release-owner] [--json]
+       retention.mjs register-owned --repo <repo root> --run <run dir> --unit <id>
+                              --last-used-at <ISO> [--apply] [--json]
+       retention.mjs status   --repo <repo root> [--run <run dir> --unit <id>] [--json]
+       retention.mjs recover  --repo <repo root> [--apply] [--json]
+
+plan, status, and recover never write (recover writes only with --apply, and only to a
+lock whose owner is provably dead on this host). apply writes the lock, receipts,
+quarantine, and the manifest. register and register-owned are explicit owner mapping;
+they never write a task-plan.`
+
+export class RetentionError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+class UsageError extends RetentionError {
+  constructor(message) { super('usage', message) }
+}
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+const real = (p) => realpathSync.native ? realpathSync.native(p) : realpathSync(p)
+const lstatOrNull = (p) => { try { return lstatSync(p) } catch (error) { if (error?.code === 'ENOENT') return null; throw error } }
+const safeInt = (v) => Number.isSafeInteger(v)
+const normalized = (v) => (nonEmpty(v) ? normPath(v) : v)
+
+function nowValue(value) {
+  if (value === undefined) return Date.now()
+  if (value instanceof Date) return value.getTime()
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  const parsed = Date.parse(String(value))
+  if (!Number.isFinite(parsed)) throw new UsageError('the clock value is not a valid time')
+  return parsed
+}
+
+function timestamp(value) {
+  if (!nonEmpty(value)) return null
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/.test(value)) return null
+  const parsed = Date.parse(value)
+  if (!Number.isFinite(parsed)) return null
+  return parsed
+}
+
+function isoTimestamp(ms) {
+  return new Date(ms).toISOString()
+}
+
+function safeId(value) {
+  return String(value).replace(/[^A-Za-z0-9._-]/g, '_')
+}
+
+// ---- paths ----
+
+function canonicalRepo(repo) {
+  if (!nonEmpty(repo) || !isAbsolute(repo)) throw new UsageError('--repo must be an absolute repository path')
+  let canonical
+  try { canonical = real(repo) } catch (error) { throw new RetentionError('repo', `cannot resolve ${repo}: ${error?.code ?? error?.message}`) }
+  if (!existsSync(join(canonical, '.git'))) throw new RetentionError('repo', `${canonical} is not a Git repository root`)
+  return canonical
+}
+
+function canonicalRoot(repo, { mustExist = false } = {}) {
+  const canonical = canonicalRepo(repo)
+  const root = join(canonical, '.resolve-issues')
+  const st = lstatOrNull(root)
+  if (!st) {
+    if (mustExist) throw new RetentionError('root', `canonical root ${root} does not exist`)
+    return { repo: canonical, root }
+  }
+  if (st.isSymbolicLink()) throw new RetentionError('symlink', `${root} is a symbolic link; the canonical root must be a real directory`)
+  if (!st.isDirectory()) throw new RetentionError('root', `${root} is not a directory`)
+  return { repo: canonical, root }
+}
+
+// A path segment from a resolved base down to a target may not be a symlink. Missing
+// trailing segments are fine (the tree is created later), but an unreadable segment is
+// uncertainty and is refused.
+function symlinkOnPath(base, target) {
+  const rel = relative(base, target)
+  if (rel === '' ) return false
+  if (rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel)) return true
+  let cur = base
+  for (const part of rel.split(sep)) {
+    cur = join(cur, part)
+    let st
+    try { st = lstatSync(cur) } catch (error) {
+      if (error?.code === 'ENOENT') return false
+      return true
+    }
+    if (st.isSymbolicLink()) return true
+  }
+  return false
+}
+
+function strictInside(parent, child) {
+  const p = normPath(parent)
+  const c = normPath(child)
+  return Boolean(p && c && p !== c && containsPath(p, c))
+}
+
+function canonicalExistingDir(path, label) {
+  const abs = resolve(path)
+  const st = lstatOrNull(abs)
+  if (!st) throw new RetentionError('missing', `${label} ${abs} does not exist`)
+  if (st.isSymbolicLink()) throw new RetentionError('symlink', `${label} ${abs} is a symbolic link`)
+  if (!st.isDirectory()) throw new RetentionError('not-directory', `${label} ${abs} is not a directory`)
+  return real(abs)
+}
+
+// ---- bounded tree inspection ----
+
+function allocation(st) {
+  if (Number.isFinite(st.blocks) && st.blocks > 0) return st.blocks * 512
+  return Number.isFinite(st.size) ? st.size : 0
+}
+
+// Streams one file through a fixed buffer, so nothing scales with the file size. The size
+// seen by lstat is the exact expected length: a short read, one readable byte past that
+// length (a growth probe), or a differing final stat (identity, size, mtime, ctime) is a
+// change, and a changed file is never removed.
+function hashFile(path, st, { remaining, maxFileBytes }) {
+  if (st.size > maxFileBytes) {
+    return { error: `${path} is ${st.size} bytes, beyond the ${maxFileBytes}-byte per-file snapshot bound` }
+  }
+  if (st.size > remaining) return { hash: null, read: 0, truncated: true }
+  let fd
+  try {
+    fd = openSync(path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0))
+  } catch (error) {
+    return { error: `cannot open ${path}: ${error?.code ?? error?.message}` }
+  }
+  try {
+    const opened = fstatSync(fd)
+    if (!opened.isFile() || opened.dev !== st.dev || opened.ino !== st.ino || opened.size !== st.size) {
+      return { error: `${path} changed while it was being snapshotted` }
+    }
+    const digest = createHash('sha256')
+    const buffer = Buffer.allocUnsafe(Math.min(HASH_CHUNK_BYTES, Math.max(1, st.size)))
+    let read = 0
+    while (read < st.size) {
+      const want = Math.min(buffer.length, st.size - read)
+      let got
+      try { got = readSync(fd, buffer, 0, want, read) } catch (error) {
+        return { error: `cannot read ${path}: ${error?.code ?? error?.message}` }
+      }
+      if (got === 0) return { error: `${path} shrank while it was being snapshotted` }
+      digest.update(buffer.subarray(0, got))
+      read += got
+    }
+    let growth
+    try { growth = readSync(fd, buffer, 0, 1, st.size) } catch (error) {
+      return { error: `cannot probe ${path}: ${error?.code ?? error?.message}` }
+    }
+    if (growth !== 0) return { error: `${path} grew while it was being snapshotted` }
+    const final = fstatSync(fd)
+    if (!final.isFile() || final.dev !== st.dev || final.ino !== st.ino || final.size !== st.size
+      || final.mtimeMs !== st.mtimeMs || final.ctimeMs !== st.ctimeMs) {
+      return { error: `${path} changed while it was being snapshotted` }
+    }
+    return { hash: digest.digest('hex'), read, truncated: false }
+  } catch (error) {
+    return { error: `cannot snapshot ${path}: ${error?.code ?? error?.message}` }
+  } finally {
+    try { closeSync(fd) } catch { /* already closed */ }
+  }
+}
+
+// Reads with lstat only (never stat/follow), sorts names for a deterministic digest,
+// and stops on any bound. Any truncation or unreadable entry is a refusal, not a guess.
+export function inspectTree(rootInput, options = {}) {
+  const maxEntries = options.maxEntries ?? 100000
+  const maxDepth = options.maxDepth ?? 64
+  const maxHashBytes = options.maxHashBytes ?? MAX_TOTAL_HASH_BYTES
+  const maxFileHashBytes = options.maxFileHashBytes ?? MAX_FILE_HASH_BYTES
+  const hashContent = options.hashContent !== false
+  const result = {
+    ok: false, reason: null, truncated: false, entries: 0, files: 0, dirs: 0, symlinks: 0,
+    allocatedBytes: 0, newestMtimeMs: null, rootMtimeMs: null, rootIdentity: null,
+    digest: null, metadataNames: [], credentialPaths: [], nestedGit: [], externalSymlinks: [],
+    special: [], containingWorkspace: null,
+  }
+  const input = resolve(rootInput)
+  let rootStat
+  try { rootStat = lstatSync(input) } catch (error) {
+    result.reason = `cannot read ${input}: ${error?.code ?? error?.message}`
+    return result
+  }
+  if (rootStat.isSymbolicLink()) { result.reason = `${input} is a symbolic link`; return result }
+  let root
+  try { root = real(input) } catch (error) {
+    result.reason = `cannot resolve ${input}: ${error?.code ?? error?.message}`
+    return result
+  }
+  if (!rootStat.isDirectory()) { result.reason = `${root} is not a directory`; return result }
+  result.rootMtimeMs = rootStat.mtimeMs
+  result.rootIdentity = { dev: rootStat.dev, ino: rootStat.ino }
+  const digest = createHash('sha256')
+  digest.update(`root\0${rootStat.dev}\0${rootStat.ino}\0${rootStat.mode}\0${rootStat.mtimeMs}\n`)
+  let hashedBytes = 0
+  let newest = null
+
+  const stack = [{ abs: root, rel: '', depth: 0 }]
+  while (stack.length) {
+    const item = stack.pop()
+    let entries
+    try {
+      entries = readdirSync(item.abs, { withFileTypes: true })
+        .slice()
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    } catch (error) {
+      result.reason = `cannot read ${item.abs}: ${error?.code ?? error?.message}`
+      return result
+    }
+    for (const entry of entries) {
+      if (result.entries++ >= maxEntries) { result.truncated = true; result.reason = `tree exceeds the ${maxEntries}-entry bound`; return result }
+      const abs = join(item.abs, entry.name)
+      const rel = item.rel ? `${item.rel}/${entry.name}` : entry.name
+      let st
+      try { st = lstatSync(abs) } catch (error) {
+        result.reason = `cannot inspect ${abs}: ${error?.code ?? error?.message}`
+        return result
+      }
+      result.allocatedBytes += allocation(st)
+      digest.update(`${rel}\0${st.dev}\0${st.ino}\0${st.mode}\0${st.size}\0${st.mtimeMs}\n`)
+      if (result.credentialPaths.length < MAX_REPORTED_CREDENTIALS && credentialName(entry.name, st.isDirectory())) {
+        result.credentialPaths.push(rel)
+      }
+      if (METADATA_NAMES.has(entry.name)) result.metadataNames.push(rel)
+      if (st.isSymbolicLink()) {
+        result.symlinks += 1
+        if (st.mtimeMs > (newest ?? 0)) newest = st.mtimeMs
+        let link = null
+        try { link = readlinkSync(abs) } catch (error) {
+          result.reason = `cannot read symbolic link ${abs}: ${error?.code ?? error?.message}`
+          return result
+        }
+        digest.update(`link\0${rel}\0${link}\n`)
+        const candidate = isAbsolute(link) ? resolve(link) : resolve(dirname(abs), link)
+        let outside = !(containsPath(root, candidate) || normPath(candidate) === root)
+        if (!outside) {
+          try {
+            const target = real(abs)
+            outside = !(containsPath(root, target) || normPath(target) === root)
+          } catch { /* a dangling link is unlinked, never followed */ }
+        }
+        if (outside) result.externalSymlinks.push({ path: abs, target: link })
+        continue
+      }
+      if (st.isDirectory()) {
+        result.dirs += 1
+        if (item.depth + 1 > maxDepth) { result.truncated = true; result.reason = `tree exceeds the ${maxDepth}-level depth bound`; return result }
+        if (entry.name === '.git') result.nestedGit.push(rel)
+        const bare = existsSync(join(abs, 'HEAD')) && existsSync(join(abs, 'objects')) && existsSync(join(abs, 'refs'))
+        if (bare) result.nestedGit.push(rel)
+        stack.push({ abs, rel, depth: item.depth + 1 })
+        continue
+      }
+      if (entry.name === '.git') result.nestedGit.push(rel)
+      if (!st.isFile()) { result.special.push(rel); continue }
+      result.files += 1
+      if (st.mtimeMs > (newest ?? 0)) newest = st.mtimeMs
+      if (hashContent) {
+        const hashed = hashFile(abs, st, { remaining: maxHashBytes - hashedBytes, maxFileBytes: maxFileHashBytes })
+        if (hashed.error) { result.reason = hashed.error; return result }
+        if (hashed.truncated) {
+          result.truncated = true
+          result.reason = `content snapshot exceeds the ${maxHashBytes}-byte bound`
+          return result
+        }
+        hashedBytes += hashed.read
+        digest.update(`content\0${rel}\0${hashed.hash}\n`)
+      }
+    }
+  }
+  result.digest = digest.digest('hex')
+  result.newestMtimeMs = newest ?? rootStat.mtimeMs
+  result.ok = true
+  return result
+}
+
+function snapshotOf(inspection) {
+  return {
+    digest: inspection.digest,
+    entries: inspection.entries,
+    files: inspection.files,
+    allocatedBytes: inspection.allocatedBytes,
+    newestMtimeMs: inspection.newestMtimeMs,
+    root: inspection.rootIdentity,
+  }
+}
+
+function sameSnapshot(a, b) {
+  if (!isObject(a) || !isObject(b)) return false
+  return a.digest === b.digest && a.entries === b.entries && a.files === b.files
+    && a.allocatedBytes === b.allocatedBytes && a.newestMtimeMs === b.newestMtimeMs
+    && a.root?.dev === b.root?.dev && a.root?.ino === b.root?.ino
+}
+
+// ---- Git proof ----
+
+function git(dir, args) {
+  try {
+    const out = execFileSync('git', ['-C', dir, ...args], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 30000, maxBuffer: 8 * 1024 * 1024,
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' },
+    })
+    return { ok: true, out: String(out) }
+  } catch (error) {
+    return { ok: false, err: String(error?.stderr ?? error?.message ?? '') }
+  }
+}
+
+// The resource must live inside a real Git workspace and contain no tracked path.
+// If no containing workspace can be found, trackedness cannot be proved, so the
+// resource is refused rather than assumed disposable.
+function trackedProof(target) {
+  const top = git(target, ['rev-parse', '--show-toplevel'])
+  if (!top.ok || !nonEmpty(top.out.trim())) {
+    return { ok: false, reason: `${target} is not inside a readable Git workspace, so untracked content cannot be proved` }
+  }
+  let toplevel
+  try { toplevel = real(top.out.trim()) } catch (error) {
+    return { ok: false, reason: `cannot resolve the containing Git workspace of ${target}: ${error?.code ?? error?.message}` }
+  }
+  let targetReal
+  try { targetReal = real(target) } catch (error) {
+    return { ok: false, reason: `cannot resolve ${target}: ${error?.code ?? error?.message}` }
+  }
+  if (!containsPath(toplevel, targetReal)) return { ok: false, reason: `${target} is outside its containing Git workspace ${toplevel}` }
+  const rel = relative(toplevel, targetReal)
+  const tracked = git(toplevel, ['ls-files', '-z', '--', rel])
+  if (!tracked.ok) return { ok: false, reason: `cannot list tracked paths under ${target}` }
+  const count = tracked.out.split('\0').filter(Boolean).length
+  if (count) return { ok: false, reason: `${count} tracked path(s) live inside ${target}; tracked source is never disposable` }
+  return { ok: true, toplevel, relative: rel }
+}
+
+// ---- manifest ----
+
+function manifestPath(root) {
+  return join(root, MANIFEST_FILE)
+}
+
+export function readManifest(root) {
+  const path = manifestPath(root)
+  const st = lstatOrNull(path)
+  if (!st) return { version: MANIFEST_VERSION, entries: [] }
+  if (st.isSymbolicLink()) throw new RetentionError('symlink', `${path} is a symbolic link`)
+  if (!st.isFile()) throw new RetentionError('manifest', `${path} is not a regular file`)
+  if (st.size > 8 * 1024 * 1024) throw new RetentionError('manifest', `${path} exceeds the 8 MiB manifest bound`)
+  let parsed
+  try { parsed = JSON.parse(readFileSync(path, 'utf8')) } catch (error) {
+    throw new RetentionError('manifest', `${path} is not readable JSON: ${error.message}`)
+  }
+  if (!isObject(parsed) || parsed.version !== MANIFEST_VERSION || !Array.isArray(parsed.entries)) {
+    throw new RetentionError('manifest', `${path} must be {"version": 1, "entries": [...]}`)
+  }
+  return parsed
+}
+
+function writeManifest(root, manifest) {
+  const path = manifestPath(root)
+  const st = lstatOrNull(path)
+  if (st?.isSymbolicLink()) throw new RetentionError('symlink', `${path} is a symbolic link`)
+  const temporary = join(root, `.${MANIFEST_FILE}.${process.pid}.${Date.now()}.tmp`)
+  try {
+    writeFileSync(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx', mode: 0o600 })
+    renameSync(temporary, path)
+  } catch (error) {
+    try { unlinkSync(temporary) } catch { /* absent */ }
+    throw new RetentionError('io', `cannot write ${path}: ${error?.code ?? error?.message}`)
+  }
+  return path
+}
+
+// ---- locking ----
+
+// The lock contract (strong owner record, liveness proof, atomic same-parent quarantine)
+// lives in retention-lock.mjs. What retention adds is one policy: before taking the lock it
+// may clear a lock whose recorded owner is provably dead on this host, because an
+// interrupted apply leaves that lock behind and the lock is never reclaimed by age. Live,
+// foreign, legacy, unreadable and ambiguous locks are kept, as is every receipt and
+// quarantined tree the interrupted apply wrote: releasing a dead lock never claims that
+// the apply finished.
+function recoverDeadLock(root) {
+  let inspection
+  try {
+    inspection = inspectRetentionLock(root)
+  } catch (error) {
+    if (error instanceof RetentionLockError) throw new RetentionError(error.code === 'usage' ? 'usage' : 'lock', error.message)
+    throw error
+  }
+  if (!inspection.present || !inspection.recoverable) return null
+  let recovery
+  try {
+    recovery = recoverRetentionLock(root, { apply: true })
+  } catch (error) {
+    if (error instanceof RetentionLockError) throw new RetentionError('lock', error.message)
+    throw error
+  }
+  return {
+    status: recovery.status,
+    action: recovery.action,
+    reason: recovery.reason,
+    cleared: recovery.cleared,
+    owner: inspection.owner,
+    pendingQuarantines: recovery.quarantines,
+  }
+}
+
+function acquireLock(root) {
+  const dir = join(root, LOCK_NAME)
+  if (symlinkOnPath(root, dir)) throw new RetentionError('symlink', `${dir} passes through a symbolic link`)
+  const recovery = recoverDeadLock(root)
+  let lock
+  try {
+    lock = acquireRetentionLock(root)
+  } catch (error) {
+    if (error instanceof RetentionLockError) {
+      const code = error.code === 'locked' ? 'locked' : error.code === 'usage' ? 'usage' : 'io'
+      throw new RetentionError(code, error.message)
+    }
+    throw error
+  }
+  return {
+    path: lock.path,
+    owner: lock.owner,
+    recovery,
+    release() {
+      try { return lock.release() } catch { return { released: false, reason: 'release-failed' } }
+    },
+  }
+}
+
+// ---- plans, owners, evidence ----
+
+function readPlanFile(path) {
+  const st = lstatOrNull(path)
+  if (!st || st.isSymbolicLink() || !st.isFile() || st.size > 4 * 1024 * 1024) return null
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return isObject(parsed) ? parsed : null
+  } catch { return null }
+}
+
+function unitOfPlan(plan, unitId) {
+  const rows = [...(Array.isArray(plan?.units) ? plan.units : []), ...(Array.isArray(plan?.issues) ? plan.issues : [])]
+  return rows.find((row) => isObject(row) && String(row.id) === String(unitId)) ?? null
+}
+
+function deliveryMerged(unit) {
+  const delivery = unit?.delivery
+  if (delivery === 'merged') return true
+  if (isObject(delivery)) return delivery.outcome === 'merged' || delivery.state === 'merged' || delivery.status === 'merged'
+  return false
+}
+
+function unitCompleted(unit) {
+  return unit?.status === 'succeeded' && deliveryMerged(unit)
+}
+
+function declaredResources(unit, run) {
+  const raw = unit?.lifecycle?.resources
+  if (!Array.isArray(raw)) return []
+  return raw.filter((r) => isObject(r) && nonEmpty(r.path))
+    .map((r) => (isAbsolute(r.path) ? resolve(r.path) : resolve(run, r.path)))
+}
+
+// Resolve as far as the filesystem allows. A required-evidence path that has not been
+// written yet still names a tree: its deepest existing ancestor is canonicalized and the
+// missing tail is appended lexically, so a link spelling cannot hide an overlap with the
+// target it really points into. Non-absence failures are uncertainty (null).
+function canonicalResolve(p) {
+  let current = normPath(resolve(p))
+  const missing = []
+  for (;;) {
+    try {
+      const base = normPath(real(current))
+      return missing.length ? normPath(join(base, ...missing.slice().reverse())) : base
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') return null
+    }
+    const parent = dirname(current)
+    if (parent === current) return normPath(resolve(p))
+    missing.push(basename(current))
+    current = parent
+  }
+}
+
+// A path may be spelled lexically or reached through a link. Both forms are compared, so
+// no claim can be dodged by an alternate spelling. A path that cannot be resolved for a
+// reason other than absence is uncertainty, and uncertainty never authorizes a deletion.
+function pathForms(p) {
+  const lexical = normPath(resolve(p))
+  if (!lexical) return null
+  const forms = [lexical]
+  const canonical = canonicalResolve(lexical)
+  if (canonical === null) return null
+  if (canonical && canonical !== lexical) forms.push(canonical)
+  return forms
+}
+
+function formsOverlap(left, right) {
+  return left.some((a) => right.some((b) => containsPath(a, b) || containsPath(b, a)))
+}
+
+// Another unit or run claiming the same tree as its own workspace or resource makes this
+// target ambiguous ownership, not a candidate. Only real claims count: a run directory or a
+// shared resource container is not a claim unless a plan declares it as one.
+function claimConflict(target, claims, owner) {
+  if (!isObject(claims) || !claims.complete) {
+    return { status: 'retained', reason: 'the bounded workspace/resource claim scan did not finish, so overlapping ownership cannot be ruled out' }
+  }
+  const forms = pathForms(target)
+  if (!forms) return { status: 'retained', reason: `the ownership forms of ${target} cannot be resolved` }
+  for (const claim of claims.list) {
+    if (claim.run === owner.run && claim.unit === String(owner.unit)) continue
+    if (formsOverlap(forms, claim.forms)) {
+      return {
+        status: 'refused',
+        reason: `${claim.label} declares ${claim.kind} ${claim.path}, which overlaps ${target}; a tree another unit or run claims is never removed`,
+      }
+    }
+  }
+  return null
+}
+
+// Every path a plan declares as required evidence (or a required checkpoint or pin), plus
+// every workspace and declared resource that names an owner. One bounded walk of the
+// canonical root produces both, and each proof keeps its own completeness: an unreadable
+// evidence declaration says nothing about who owns a tree, and claiming otherwise would
+// report the wrong uncertainty. Either one incomplete never authorizes a deletion.
+function planIndex(root, bounds = {}) {
+  const locations = retentionPlanFiles(root, { maxPlans: bounds.maxPlans ?? 200, maxEntries: bounds.maxEvidenceEntries ?? 20000 })
+  const maxClaims = bounds.maxClaims ?? 20000
+  const evidence = []
+  const claims = []
+  let evidenceComplete = locations.complete
+  let claimsComplete = locations.complete
+  const collectEvidence = (raw, run) => {
+    if (raw === undefined) return
+    if (!Array.isArray(raw)) { evidenceComplete = false; return }
+    for (const entry of raw) {
+      if (typeof entry === 'string') {
+        if (!nonEmpty(entry)) { evidenceComplete = false; continue }
+        evidence.push({ path: resolve(run, entry), run })
+        continue
+      }
+      // An entry that names no readable path, or whose `required` is not a boolean, is a
+      // declaration nobody can resolve. Dropping it silently is how a required path became
+      // an authorized deletion, so a malformed entry makes the whole scan incomplete.
+      // Only an entry that says `required: false` is knowingly optional, and it protects
+      // nothing: the caller chose that.
+      if (!isObject(entry) || !nonEmpty(entry.path)
+        || (entry.required !== undefined && typeof entry.required !== 'boolean')) {
+        evidenceComplete = false
+        continue
+      }
+      if (entry.required === false) continue
+      evidence.push({ path: resolve(run, entry.path), run })
+    }
+  }
+  // A unit and the plan itself declare evidence, pins and checkpoints in the same four
+  // slots, plus lifecycle.cleanup.evidence. Every slot is read the same way, so a path is
+  // protected wherever the run recorded it, including at the root of the plan.
+  const collectDeclarations = (scope, run) => {
+    if (!isObject(scope)) return
+    for (const key of EVIDENCE_KEYS) {
+      collectEvidence(scope[key], run)
+      collectEvidence(scope.lifecycle?.[key], run)
+    }
+    collectEvidence(scope.lifecycle?.cleanup?.evidence, run)
+  }
+  const collectClaim = (run, unitId, raw, kind) => {
+    if (raw === undefined) return
+    if (!nonEmpty(raw)) { claimsComplete = false; return }
+    const lexical = isAbsolute(raw) ? resolve(raw) : resolve(run, raw)
+    const forms = pathForms(lexical)
+    if (!forms || claims.length >= maxClaims) { claimsComplete = false; return }
+    claims.push({ run, unit: String(unitId), kind, path: lexical, forms, label: `unit ${unitId} of ${run}` })
+  }
+  const readPlan = (dir) => {
+    const abs = join(dir, 'task-plan.json')
+    if (!existsSync(abs)) return
+    const plan = readPlanFile(abs)
+    if (!plan) { evidenceComplete = false; claimsComplete = false; return }
+    if (plan.units !== undefined && !Array.isArray(plan.units)) { evidenceComplete = false; claimsComplete = false; return }
+    if (plan.issues !== undefined && !Array.isArray(plan.issues)) { evidenceComplete = false; claimsComplete = false; return }
+    collectDeclarations(plan, dir)
+    for (const unit of [...(Array.isArray(plan.units) ? plan.units : []), ...(Array.isArray(plan.issues) ? plan.issues : [])]) {
+      if (!isObject(unit)) { evidenceComplete = false; claimsComplete = false; continue }
+      collectDeclarations(unit, dir)
+      if (!nonEmpty(unit.id) && !Number.isSafeInteger(unit.id)) { claimsComplete = false; continue }
+      // A null workspace explicitly means no allocation in legacy pending units.
+      // A non-null malformed path remains uncertainty and blocks the scan.
+      if (unit.workspace !== null) collectClaim(dir, unit.id, unit.workspace, 'workspace')
+      const resources = unit.lifecycle?.resources === undefined ? unit.resources : unit.lifecycle.resources
+      if (resources !== undefined && !Array.isArray(resources)) { claimsComplete = false; continue }
+      for (const resource of Array.isArray(resources) ? resources : []) {
+        if (!isObject(resource)) { claimsComplete = false; continue }
+        collectClaim(dir, unit.id, resource.path, 'resource')
+      }
+    }
+  }
+  for (const path of locations.paths) readPlan(dirname(path))
+  return { evidence: { paths: evidence, complete: evidenceComplete }, claims: { list: claims, complete: claimsComplete } }
+}
+
+function requiredEvidenceOverlap(target, index) {
+  if (!index.complete) return `the bounded evidence scan did not finish, so required-evidence overlap cannot be ruled out`
+  const targetForms = pathForms(target)
+  if (!targetForms) return `the canonical forms of ${target} cannot be resolved, so required-evidence overlap cannot be ruled out`
+  for (const evidence of index.paths) {
+    const evidenceForms = pathForms(evidence.path)
+    if (!evidenceForms) return `required evidence ${evidence.path} (declared by ${evidence.run}) cannot be resolved, so overlap with ${target} cannot be ruled out`
+    if (formsOverlap(targetForms, evidenceForms)) {
+      return `required evidence ${evidence.path} (declared by ${evidence.run}) overlaps ${target}`
+    }
+  }
+  return null
+}
+
+function runDirs(root, bounds = {}) {
+  const limit = bounds.maxRuns ?? 100
+  const runs = []
+  const add = (path) => {
+    if (runs.length >= limit) return
+    const st = lstatOrNull(path)
+    if (!st || st.isSymbolicLink() || !st.isDirectory()) return
+    runs.push(path)
+  }
+  if (!existsSync(root)) return runs
+  const rush = join(root, 'rush')
+  if (existsSync(rush) && !lstatSync(rush).isSymbolicLink()) {
+    for (const entry of readdirSync(rush, { withFileTypes: true })) {
+      if (entry.isDirectory() && !entry.isSymbolicLink()) add(join(rush, entry.name))
+    }
+  }
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue
+    if (!entry.name.endsWith('-workspaces')) continue
+    const legacy = join(root, entry.name)
+    let children = []
+    try {
+      children = readdirSync(legacy, { withFileTypes: true })
+        .filter((child) => child.isDirectory() && !child.isSymbolicLink())
+        .map((child) => join(legacy, child.name))
+    } catch { /* an unreadable legacy container is inventory-only */ }
+    if (children.length) for (const child of children) add(child)
+    else add(legacy)
+  }
+  return runs
+}
+
+function inventory(root, bounds) {
+  const runs = []
+  let complete = true
+  if (!existsSync(root)) return { runs, complete, totalBytes: 0 }
+  for (const run of runDirs(root, bounds)) {
+    const scan = inspectTree(run, {
+      maxEntries: bounds.maxInventoryEntries ?? 20000,
+      maxDepth: bounds.maxDepth ?? 64,
+      hashContent: false,
+    })
+    if (!scan.ok) complete = false
+    runs.push({
+      run, bytes: scan.allocatedBytes, entries: scan.entries,
+      truncated: scan.truncated, readable: scan.ok, reason: scan.reason,
+    })
+  }
+  runs.sort((a, b) => b.bytes - a.bytes)
+  const resources = []
+  const maxResources = bounds.maxInventoryResources ?? 100
+  const addResource = (path, ownerRun) => {
+    if (resources.length >= maxResources) return
+    const st = lstatOrNull(path)
+    if (!st || st.isSymbolicLink() || !st.isDirectory()) return
+    const scan = inspectTree(path, {
+      maxEntries: bounds.maxInventoryEntries ?? 20000,
+      maxDepth: bounds.maxDepth ?? 64,
+      hashContent: false,
+    })
+    if (!scan.ok) complete = false
+    resources.push({ path, run: ownerRun, bytes: scan.allocatedBytes, entries: scan.entries, truncated: scan.truncated })
+  }
+  const addTwoLevels = (base, depth, ownerRun) => {
+    let entries
+    try { entries = readdirSync(base, { withFileTypes: true }) } catch { return }
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (resources.length >= maxResources) return
+      if (!entry.isDirectory() || entry.isSymbolicLink()) continue
+      const abs = join(base, entry.name)
+      if (depth > 1) addTwoLevels(abs, depth - 1, ownerRun)
+      else addResource(abs, ownerRun)
+    }
+  }
+  for (const run of runs) {
+    if (resources.length >= maxResources) break
+    addTwoLevels(join(run.run, 'resources'), 2, run.run)
+    let reviewUnits = []
+    try { reviewUnits = readdirSync(join(run.run, 'reviews'), { withFileTypes: true }) } catch { /* none */ }
+    for (const unit of reviewUnits) {
+      if (!unit.isDirectory() || unit.isSymbolicLink()) continue
+      addResource(join(run.run, 'reviews', unit.name, 'clone'), run.run)
+    }
+  }
+  resources.sort((a, b) => b.bytes - a.bytes)
+  return {
+    runs, resources, complete,
+    totalBytes: runs.reduce((sum, r) => sum + r.bytes, 0),
+    totalResourceBytes: resources.reduce((sum, r) => sum + r.bytes, 0),
+  }
+}
+
+// ---- entry validation and ownership ----
+
+// A recorded rebuild input proof is a small, bounded record: the canonical file's name and
+// absolute path, the content hash that was proven, and the filesystem identity it was
+// bound to. Anything else is a claim no apply pass can recheck, so it is refused by shape
+// rather than trusted.
+function inputProofProblem(proof, index) {
+  const where = `inputProofs[${index}]`
+  if (!isObject(proof)) return `${where} is not an object`
+  if (!nonEmpty(proof.name)) return `${where}.name is missing`
+  if (!nonEmpty(proof.path) || !isAbsolute(proof.path)) return `${where}.path must be absolute`
+  if (!nonEmpty(proof.hash) || !/^[0-9a-f]{64}$/.test(proof.hash)) return `${where}.hash must be a sha256 hex digest`
+  const identity = proof.identity
+  if (!isObject(identity) || !safeInt(identity.dev) || !safeInt(identity.ino) || !safeInt(identity.size)) {
+    return `${where}.identity must carry integer dev, ino and size`
+  }
+  return null
+}
+
+function parseEntry(entry, { forStatus = false } = {}) {
+  const problems = []
+  if (!isObject(entry)) return { problems: ['entry is not an object'] }
+  if (!nonEmpty(entry.id)) problems.push('id is missing')
+  if (!nonEmpty(entry.path) || !isAbsolute(entry.path)) problems.push('path must be absolute')
+  if (!KINDS.has(entry.kind)) problems.push(`kind ${String(entry.kind)} is not generated|artifact`)
+  if (!isObject(entry.owner) || !nonEmpty(entry.owner.run) || !isAbsolute(entry.owner.run) || !nonEmpty(entry.owner.unit)) problems.push('owner must be {run: absolute path, unit: id}')
+  if (timestamp(entry.lastUsedAt) === null) problems.push('lastUsedAt must be an ISO timestamp')
+  if (typeof entry.disposable !== 'boolean' || (!forStatus && entry.disposable !== true)) problems.push('disposable must be true; the manifest cannot be edited into disposability')
+  if (typeof entry.pinned !== 'boolean' || (!forStatus && entry.pinned !== false)) problems.push('pinned must be false; pinned resources are never candidates')
+  if (entry.kind === 'generated' && !nonEmpty(entry.recipe)) problems.push('generated resources need a nonempty reconstruction recipe')
+  if (entry.kind === 'artifact' && typeof entry.recipe !== 'string') problems.push('artifact recipe must be a string (it may be empty)')
+  if (!isObject(entry.identity) || !safeInt(entry.identity.dev) || !safeInt(entry.identity.ino)) problems.push('identity must carry integer dev and ino')
+  if (!isObject(entry.authorization) || entry.authorization.source !== 'explicit-registration' || timestamp(entry.authorization.at) === null) problems.push('authorization must be an explicit-registration record with an ISO at')
+  if (entry.ownerReleased !== undefined && typeof entry.ownerReleased !== 'boolean') problems.push('ownerReleased must be a boolean when present')
+  if (entry.cleanupState !== undefined && !['removed', 'failed'].includes(entry.cleanupState)) problems.push(`cleanupState ${String(entry.cleanupState)} is not removed|failed`)
+  // A format is a claim about proof, so an unreadable or unsupported name is refused
+  // rather than treated as `generic`: the two carry different checks.
+  if (entry.format !== undefined && (!nonEmpty(entry.format) || !FORMATS.has(entry.format))) {
+    problems.push(`format ${String(entry.format)} is not ${[...FORMATS].join('|')}`)
+  }
+  const format = entry.format ?? 'generic'
+  if (entry.inputProofs !== undefined) {
+    if (!Array.isArray(entry.inputProofs)) problems.push('inputProofs must be an array')
+    else if (entry.inputProofs.length === 0) problems.push('inputProofs must record at least one proven rebuild input')
+    else if (entry.inputProofs.length > MAX_REBUILD_INPUTS) problems.push(`inputProofs carries more than ${MAX_REBUILD_INPUTS} proofs`)
+    else {
+      for (const [index, proof] of entry.inputProofs.entries()) {
+        const problem = inputProofProblem(proof, index)
+        if (problem) { problems.push(problem); break }
+      }
+    }
+  }
+  // The stored format and the stored proof must agree. A typed format without retained
+  // inputs cannot be rebuilt, and a generic resource carrying them is a proof nobody made.
+  if (format !== 'generic' && !Array.isArray(entry.inputProofs)) problems.push(`${format} needs recorded rebuild input proofs`)
+  if (format === 'generic' && entry.inputProofs !== undefined) problems.push('a generic resource carries no typed rebuild input proofs')
+  return { problems, format }
+}
+
+function ownershipProblem({ root, run, unit, unitId, target, plan }) {
+  let runReal, targetReal, rootReal
+  try { rootReal = real(root) } catch { return `cannot resolve ${root}` }
+  try { runReal = real(run) } catch { return `run ${run} does not exist or cannot be resolved` }
+  try { targetReal = real(target) } catch { return `target ${target} does not exist or cannot be resolved` }
+  if (!strictInside(rootReal, runReal)) return `run ${run} is not inside the canonical root ${root}`
+  if (!strictInside(rootReal, targetReal)) return `target ${target} is not inside the canonical root ${root}`
+  if (symlinkOnPath(rootReal, resolve(run))) return `run ${run} passes through a symbolic link`
+  if (symlinkOnPath(rootReal, resolve(target))) return `target ${target} passes through a symbolic link`
+  if (targetReal === rootReal || targetReal === runReal) return `target ${target} is the root or the run itself`
+  const repoRoot = plan?.repoRoot
+  if (nonEmpty(repoRoot)) {
+    let recorded
+    try { recorded = real(repoRoot) } catch { return `the plan's repoRoot ${repoRoot} cannot be resolved` }
+    if (recorded !== real(dirname(rootReal))) return `the plan's repoRoot ${repoRoot} is not this repository`
+  }
+  const expectedWorkspace = join(runReal, 'units', String(unitId))
+  let expectedReal
+  try { expectedReal = real(expectedWorkspace) } catch { return `the unit workspace ${expectedWorkspace} does not exist or cannot be resolved` }
+  if (!nonEmpty(unit.workspace)) return `unit ${unitId} records no workspace`
+  let recordedWorkspace
+  try { recordedWorkspace = real(unit.workspace) } catch { return `unit ${unitId} workspace ${unit.workspace} cannot be resolved` }
+  if (recordedWorkspace !== expectedReal) return `unit ${unitId} workspace ${unit.workspace} is not ${expectedWorkspace}; the plan and the disk disagree`
+  if (targetReal === recordedWorkspace) return `target ${target} is the unit workspace itself`
+  const resourcesRoot = join(runReal, 'resources', String(unitId))
+  const reviewRoot = join(runReal, 'reviews', String(unitId))
+  if (targetReal === resourcesRoot || targetReal === reviewRoot) return `target ${target} is a resource/review container, not a leaf resource`
+  const declared = declaredResources(unit, runReal).map((p) => {
+    try { return real(p) } catch { return resolve(p) }
+  })
+  if (METADATA_NAMES.has(basename(targetReal))) return `target ${target} is named like run metadata, which is never disposable`
+  if (containsPath(recordedWorkspace, targetReal) && targetReal !== recordedWorkspace) return null
+  const owners = declared.filter((p) => containsPath(p, targetReal))
+  if (owners.length) {
+    // A declared resource may be a leaf or a parent of the registered path. Refuse a
+    // declared path that itself escapes the run's resource roots.
+    if (owners.some((p) => containsPath(resourcesRoot, p) || containsPath(reviewRoot, p) || containsPath(recordedWorkspace, p))) return null
+    return `declared resource(s) ${owners.join(', ')} for unit ${unitId} are outside the run's resource roots`
+  }
+  return `target ${target} is neither inside unit ${unitId}'s workspace nor a declared resource in its task-plan`
+}
+
+// A typed format that was proven from the same tree inspection is the only authority that
+// can relax two generic guards. It never relaxes the rest: credentials, nested Git,
+// special files and blocking run metadata are engine policy, not format policy, and a
+// resource whose rebuild inputs changed keeps every guard.
+function formatVerdict(entry, target, inspection) {
+  const format = nonEmpty(entry.format) ? entry.format : 'generic'
+  if (format === 'generic') {
+    return {
+      format, typed: false, ok: true, state: 'generic', reason: null,
+      blockingMetadata: [], allowReferenceSymlinks: false,
+    }
+  }
+  // The recorded format and its rebuild inputs are re-proved here: the markers must still
+  // describe that format, and every recorded input must still be the proven file. A changed
+  // input means the artifact is no longer reproducible, so it is retained for rebuild.
+  const state = classifyRebuildState({ format, path: target, inputProofs: entry.inputProofs, inspection })
+  const names = classifyEmbeddedNames({ format, names: inspection.metadataNames })
+  return {
+    format,
+    typed: true,
+    ok: state.ok === true,
+    state: state.state,
+    reason: state.reason,
+    blockingMetadata: names.blocking,
+    allowReferenceSymlinks: state.ok === true,
+    markers: state.markers,
+    inputCheck: state.inputCheck,
+  }
+}
+
+function preservationProblem(inspection, typed = null) {
+  const proven = typed?.ok === true && typed?.format !== undefined && typed.format !== 'generic'
+  const referenceLinks = proven && typed.allowReferenceSymlinks
+  if (!referenceLinks && inspection.externalSymlinks.length) {
+    return `symbolic link(s) point outside the target: ${inspection.externalSymlinks.slice(0, 3).map((s) => `${s.path} -> ${s.target}`).join(', ')}`
+  }
+  if (inspection.special.length) return `special file(s) cannot be snapshotted or removed safely: ${inspection.special.slice(0, 3).join(', ')}`
+  if (inspection.nestedGit.length) return `nested Git repository inside the target: ${inspection.nestedGit.slice(0, 3).join(', ')}`
+  if (inspection.credentialPaths.length) {
+    return `credential- or secret-bearing path(s) inside the target are never disposable, so the whole candidate is retained: ${inspection.credentialPaths.slice(0, 3).join(', ')}`
+  }
+  // A proven format may embed the vendored names installed dependencies really contain;
+  // every other metadata name still blocks, because a generated tree never owns a plan, a
+  // finding record, a checkpoint or a Git repository.
+  const blocking = proven ? typed.blockingMetadata : inspection.metadataNames
+  if (blocking.length) return `metadata-named path(s) inside the target are never disposable: ${blocking.slice(0, 3).join(', ')}`
+  return null
+}
+
+function treeSafety(target, inspection, typed = null) {
+  if (!inspection.ok) return inspection.reason
+  if (inspection.truncated) return inspection.reason ?? 'tree inspection hit a bound'
+  const problem = preservationProblem(inspection, typed)
+  if (problem) return problem
+  const proof = trackedProof(target)
+  if (!proof.ok) return proof.reason
+  inspection.containingWorkspace = proof.toplevel
+  return null
+}
+
+function duplicateIds(entries) {
+  const counts = new Map()
+  for (const entry of entries) {
+    if (!nonEmpty(entry?.id)) continue
+    counts.set(entry.id, (counts.get(entry.id) ?? 0) + 1)
+  }
+  return new Set([...counts].filter(([, count]) => count > 1).map(([id]) => id))
+}
+
+function overlappingPairs(entries) {
+  const realPaths = entries.map((entry) => {
+    try { return { id: entry?.id, path: normPath(real(entry.path)) } } catch { return { id: entry?.id, path: normPath(resolve(String(entry?.path ?? ''))) } }
+  })
+  const overlaps = new Map()
+  for (let i = 0; i < realPaths.length; i++) {
+    for (let j = i + 1; j < realPaths.length; j++) {
+      const a = realPaths[i]
+      const b = realPaths[j]
+      if (!a.path || !b.path) continue
+      if (containsPath(a.path, b.path) || containsPath(b.path, a.path)) {
+        if (!overlaps.has(i)) overlaps.set(i, [])
+        if (!overlaps.has(j)) overlaps.set(j, [])
+        overlaps.get(i).push(b.id ?? b.path)
+        overlaps.get(j).push(a.id ?? a.path)
+      }
+    }
+  }
+  return overlaps
+}
+
+function receiptPathFor(root, id, atMs) {
+  return join(root, RECEIPT_DIR, `${safeId(id)}-${isoTimestamp(atMs).replace(/[:.]/g, '-')}.json`)
+}
+
+function receiptCandidates(root, id) {
+  const dir = join(root, RECEIPT_DIR)
+  let names
+  try { names = readdirSync(dir) } catch { return [] }
+  return names.filter((name) => name.startsWith(`${safeId(id)}-`) && name.endsWith('.json'))
+    .sort().reverse().map((name) => join(dir, name))
+}
+
+function verifiedCompleteReceipt(root, entry) {
+  for (const path of receiptCandidates(root, entry.id)) {
+    const st = lstatOrNull(path)
+    if (!st || st.isSymbolicLink() || !st.isFile() || st.size > 4 * 1024 * 1024) continue
+    let saved
+    try { saved = JSON.parse(readFileSync(path, 'utf8')) } catch { continue }
+    if (saved?.version !== RECEIPT_VERSION || saved.kind !== 'retention-receipt') continue
+    if (saved.id !== entry.id || normPath(saved.path) !== normPath(entry.path)) continue
+    if (normPath(saved.root) !== normPath(root)) continue
+    if (saved.resourceKind !== entry.kind || normalized(saved.owner?.run) !== normalized(entry.owner?.run) || saved.unit !== String(entry.owner?.unit)) continue
+    if (saved.status !== 'complete' || saved.removed !== true) continue
+    if (saved.identity?.dev !== entry.identity?.dev || saved.identity?.ino !== entry.identity?.ino) continue
+    const now = lstatOrNull(entry.path)
+    if (now) continue
+    return { ok: true, path }
+  }
+  return { ok: false, reason: 'no complete receipt binds this entry and its absence' }
+}
+
+function writeReceipt(root, payload, targetPath = null) {
+  const dir = join(root, RECEIPT_DIR)
+  if (symlinkOnPath(root, dir)) throw new RetentionError('symlink', `${dir} passes through a symbolic link`)
+  const path = targetPath ?? receiptPathFor(root, payload.id, payload.atMs)
+  const unique = targetPath ? path : (() => {
+    let candidate = path
+    for (let i = 1; existsSync(candidate) && i < 100; i++) candidate = path.replace(/\.json$/, `-${i}.json`)
+    return candidate
+  })()
+  try {
+    mkdirSync(dir, { recursive: true })
+    const temporary = join(dir, `.${safeId(payload.id)}.${process.pid}.${Date.now()}.tmp`)
+    writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { flag: 'wx', mode: 0o600 })
+    renameSync(temporary, unique)
+  } catch (error) {
+    throw new RetentionError('io', `cannot write receipt ${unique}: ${error?.code ?? error?.message}`)
+  }
+  return unique
+}
+
+// ---- evaluation ----
+
+// A plan revision binds one apply step to the plan that evaluation read, so a concurrent
+// admission cannot be smuggled past the snapshot.
+function planFingerprint(path, plan) {
+  const st = lstatOrNull(path)
+  const identity = st ? `${st.dev}:${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}` : 'absent'
+  return `${identity}:${createHash('sha256').update(JSON.stringify(plan)).digest('hex')}`
+}
+
+function loadOwner(ctx, entry) {
+  const runReal = real(entry.owner.run)
+  if (!strictInside(ctx.rootReal, runReal)) {
+    return { ok: false, status: 'refused', reason: `owner run ${entry.owner.run} is not inside ${ctx.root}` }
+  }
+  const planPath = join(runReal, 'task-plan.json')
+  const plan = readPlanFile(planPath)
+  if (!plan) {
+    return { ok: false, status: 'retained', reason: `owner task-plan ${planPath} is missing or unreadable; ownership cannot be proved` }
+  }
+  const unit = unitOfPlan(plan, entry.owner.unit)
+  if (!unit) {
+    return { ok: false, status: 'retained', reason: `unit ${entry.owner.unit} is not in ${planPath}; ownership cannot be proved` }
+  }
+  return { ok: true, runReal, planPath, plan, unit, revision: planFingerprint(planPath, plan) }
+}
+
+// One authority gate, used by evaluation and re-run from a fresh plan read immediately
+// before the quarantine rename. A reused gate is the only way the two can agree.
+function ownerGate({ ctx, entry, target, loaded, claims, evidence }) {
+  const ownership = ownershipProblem({ root: ctx.root, run: loaded.runReal, unit: loaded.unit, unitId: entry.owner.unit, target, plan: loaded.plan })
+  if (ownership) return { status: 'refused', reason: ownership }
+  if (loaded.unit.worker != null && loaded.unit.worker !== '') {
+    return { status: 'retained', reason: `unit ${entry.owner.unit} records active worker ${loaded.unit.worker}; an old resource is still in use` }
+  }
+  const completed = unitCompleted(loaded.unit)
+  if (!completed && entry.ownerReleased !== true) {
+    return { status: 'retained', reason: `unit ${entry.owner.unit} is not succeeded+merged and the manifest has no explicit ownerReleased approval; age never infers a release` }
+  }
+  const conflict = claimConflict(target, claims, { run: loaded.runReal, unit: entry.owner.unit })
+  if (conflict) return conflict
+  const overlap = requiredEvidenceOverlap(target, evidence)
+  if (overlap) return { status: 'retained', reason: overlap }
+  return null
+}
+
+function evaluateEntry(context) {
+  const { entry, index, manifest, ctx, mode } = context
+  const checks = []
+  const add = (name, ok, detail) => { checks.push({ name, ok, detail }); return ok }
+  const row = {
+    id: entry?.id ?? null,
+    path: entry?.path ?? null,
+    kind: entry?.kind ?? null,
+    owner: entry?.owner ?? null,
+    lastUsedAt: entry?.lastUsedAt ?? null,
+    bytes: 0,
+    newestMtime: null,
+    status: 'refused',
+    reason: null,
+    checks,
+  }
+  const parsed = parseEntry(entry)
+  if (!parsed.problems.length) add('shape', true, 'manifest entry is complete')
+  else {
+    row.reason = parsed.problems.join('; ')
+    row.status = 'refused'
+    return row
+  }
+  row.format = parsed.format
+  if (entry.cleanupState === 'removed') {
+    const receipt = verifiedCompleteReceipt(ctx.root, entry)
+    const present = lstatOrNull(entry.path)
+    if (present) {
+      row.status = 'refused'
+      row.reason = `manifest says removed, but ${entry.path} exists; the manifest and the disk disagree`
+      return row
+    }
+    if (!receipt.ok) {
+      row.status = 'retained'
+      row.reason = `manifest says removed and the path is absent, but ${receipt.reason}; rerun cannot claim success`
+      return row
+    }
+    row.status = 'already-removed'
+    row.reason = 'path absent and a complete receipt binds the removal'
+    row.receipt = receipt.path
+    return row
+  }
+  if (!lstatOrNull(entry.path)) {
+    const receipt = verifiedCompleteReceipt(ctx.root, entry)
+    if (receipt.ok) {
+      row.status = 'already-removed'
+      row.reason = 'path absent and a complete receipt binds the removal; the manifest marker is missing'
+      row.receipt = receipt.path
+      return row
+    }
+  }
+  if (ctx.duplicateIds.has(entry.id)) {
+    row.status = 'refused'
+    row.reason = `id ${entry.id} appears more than once in the manifest; duplicate ownership is never resolved by guessing`
+    return row
+  }
+  const overlap = ctx.overlaps.get(index)
+  if (overlap?.length) {
+    row.status = 'refused'
+    row.reason = `overlaps another registered resource (${overlap.join(', ')}); overlapping registrations never count or delete twice`
+    return row
+  }
+  add('overlap', true, 'no registered path contains or is contained by another')
+
+  const target = resolve(entry.path)
+  let loaded
+  try { loaded = loadOwner(ctx, entry) } catch (error) {
+    row.status = 'retained'
+    row.reason = `owner run cannot be resolved: ${error?.message ?? error}`
+    return row
+  }
+  if (!loaded.ok) { row.status = loaded.status; row.reason = loaded.reason; return row }
+  const gate = ownerGate({ ctx, entry, target, loaded, claims: ctx.claims, evidence: ctx.evidence })
+  if (gate) { row.status = gate.status; row.reason = gate.reason; return row }
+  add('ownership', true, `${entry.owner.unit} owns ${target}`)
+  add('owner', true, unitCompleted(loaded.unit) ? 'succeeded and delivered' : 'owner released explicitly in the manifest')
+  add('claims', true, 'no other unit or run claims the target as its workspace or resource')
+  add('evidence', true, 'no declared required evidence overlaps the target')
+  row.ownerRevision = loaded.revision
+
+  const inspection = inspectTree(target, { ...ctx.bounds, hashContent: mode === 'apply' })
+  row.bytes = inspection.allocatedBytes
+  row.newestMtime = inspection.newestMtimeMs === null ? null : isoTimestamp(inspection.newestMtimeMs)
+  // A typed resource is re-proved before any policy question is asked about deletion: a
+  // format whose markers or rebuild inputs no longer match is not a deletion candidate, it
+  // is work to rebuild.
+  const typed = formatVerdict(entry, target, inspection)
+  if (typed.typed && !typed.ok) {
+    row.status = 'retained'
+    row.rebuildRequired = true
+    row.formatState = typed.state
+    row.reason = `${typed.format} resource at ${target} is not proven reusable: ${typed.reason}`
+    return row
+  }
+  if (typed.typed) add('format', true, `${typed.format} markers and rebuild inputs still match the registration`)
+  const unsafe = treeSafety(target, inspection, typed)
+  if (unsafe) { row.status = 'retained'; row.reason = unsafe; return row }
+  add('tree', true, `${inspection.files} file(s), ${inspection.allocatedBytes} allocated byte(s), only untracked content`)
+
+  const lastUsedMs = timestamp(entry.lastUsedAt)
+  if (lastUsedMs === null) { row.status = 'refused'; row.reason = 'lastUsedAt is not a valid ISO timestamp'; return row }
+  if (lastUsedMs > ctx.nowMs) { row.status = 'refused'; row.reason = `lastUsedAt ${entry.lastUsedAt} is in the future`; return row }
+  if (inspection.newestMtimeMs === null) { row.status = 'retained'; row.reason = 'the newest write cannot be read'; return row }
+  if (inspection.newestMtimeMs > ctx.nowMs + 1000) { row.status = 'refused'; row.reason = `the newest write inside ${target} is in the future`; return row }
+  const days = entry.kind === 'generated' ? ctx.generatedDays : ctx.artifactDays
+  const threshold = days * DAY_MS
+  const age = ctx.nowMs - lastUsedMs
+  const writeAge = ctx.nowMs - inspection.newestMtimeMs
+  row.ageDays = age / DAY_MS
+  if (age < threshold) {
+    row.status = 'retained'
+    row.reason = `lastUsedAt is ${(age / DAY_MS).toFixed(3)} day(s) old; ${entry.kind} retention is ${days} day(s)`
+    return row
+  }
+  if (writeAge < threshold) {
+    row.status = 'retained'
+    row.reason = `a file inside ${target} was written ${(writeAge / DAY_MS).toFixed(3)} day(s) ago; the newest write can only delay deletion`
+    return row
+  }
+  add('age', true, `lastUsedAt ${(age / DAY_MS).toFixed(3)} day(s), newest write ${(writeAge / DAY_MS).toFixed(3)} day(s), threshold ${days}`)
+
+  const recorded = lstatOrNull(target)
+  if (!recorded) { row.status = 'retained'; row.reason = `${target} disappeared during evaluation`; return row }
+  if (recorded.dev !== entry.identity.dev || recorded.ino !== entry.identity.ino) {
+    row.status = 'refused'
+    row.reason = `${target} dev/ino ${recorded.dev}/${recorded.ino} is not the registered ${entry.identity.dev}/${entry.identity.ino}; a replacement tree is never removed`
+    return row
+  }
+  add('identity', true, `${entry.identity.dev}/${entry.identity.ino}`)
+
+  const uncertain = []
+  const live = ctx.probe([target], { onUncertain: (detail) => uncertain.push(detail) })
+  if (live === 'unreadable') {
+    row.status = 'retained'
+    row.reason = `process use of ${target} cannot be determined; uncertainty never authorizes deletion`
+    return row
+  }
+  if (live === 'unavailable') {
+    row.status = 'retained'
+    row.reason = `no process-use probe is available, so ${target} cannot be shown idle`
+    return row
+  }
+  if (!Array.isArray(live)) {
+    row.status = 'retained'
+    row.reason = `process use of ${target} returned ${String(live)}; only a proven empty scan authorizes deletion`
+    return row
+  }
+  if (live.length) {
+    row.status = 'retained'
+    row.reason = `${live.length} process(es) are using ${target} (${live.slice(0, 3).join(', ')})`
+    return row
+  }
+  add('process', true, 'no process was found using the target')
+
+  row.status = 'ready'
+  row.reason = `ready: ${entry.kind} past its ${days}-day threshold; every safety check passed`
+  row.snapshot = snapshotOf(inspection)
+  row.inspection = inspection
+  return row
+}
+
+function baseContext({ repo, generatedDays, artifactDays, now, probe, bounds }, manifest) {
+  const { root } = canonicalRoot(repo)
+  const rootReal = existsSync(root) ? real(root) : root
+  const index = planIndex(rootReal, bounds)
+  return {
+    repo: canonicalRepo(repo),
+    root,
+    rootReal,
+    generatedDays,
+    artifactDays,
+    nowMs: now,
+    probe,
+    bounds,
+    manifest,
+    evidence: index.evidence,
+    claims: index.claims,
+    overlaps: overlappingPairs(manifest.entries),
+    duplicateIds: duplicateIds(manifest.entries),
+  }
+}
+
+function assertDays(value, flag) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new UsageError(`${flag} must be a nonnegative integer`)
+  return value
+}
+
+function normalizeBounds(bounds = {}) {
+  return {
+    maxEntries: bounds.maxEntries ?? 100000,
+    maxDepth: bounds.maxDepth ?? 64,
+    maxHashBytes: bounds.maxHashBytes ?? MAX_TOTAL_HASH_BYTES,
+    maxFileHashBytes: bounds.maxFileHashBytes ?? MAX_FILE_HASH_BYTES,
+    maxClaims: bounds.maxClaims ?? 20000,
+    maxPlanDepth: bounds.maxPlanDepth ?? 6,
+    maxPlans: bounds.maxPlans ?? 200,
+    maxEvidenceEntries: bounds.maxEvidenceEntries ?? 20000,
+    maxRuns: bounds.maxRuns ?? 100,
+    maxInventoryEntries: bounds.maxInventoryEntries ?? 20000,
+  }
+}
+
+function summarize(rows) {
+  return {
+    total: rows.length,
+    ready: rows.filter((r) => r.status === 'ready').length,
+    retained: rows.filter((r) => r.status === 'retained').length,
+    refused: rows.filter((r) => r.status === 'refused').length,
+    alreadyRemoved: rows.filter((r) => r.status === 'already-removed').length,
+    candidatesBytes: rows.filter((r) => r.status === 'ready').reduce((sum, r) => sum + (r.bytes ?? 0), 0),
+  }
+}
+
+function publicRow(row) {
+  const { inspection, snapshot, ownerRevision, ...rest } = row
+  return rest
+}
+
+// ---- plan ----
+
+export function planRetention({
+  repo, generatedDays = 7, artifactDays = 30, now, probe = liveProcessesUsing, bounds = {},
+} = {}) {
+  assertDays(generatedDays, '--generated-days')
+  assertDays(artifactDays, '--artifact-days')
+  const nowMs = nowValue(now)
+  const { root } = canonicalRoot(repo)
+  const manifest = existsSync(root) ? readManifest(root) : { version: MANIFEST_VERSION, entries: [] }
+  const ctx = baseContext({ repo, generatedDays, artifactDays, now: nowMs, probe, bounds: normalizeBounds(bounds) }, manifest)
+  const rows = manifest.entries.map((entry, index) => {
+    try { return evaluateEntry({ entry, index, manifest, ctx, mode: 'plan' }) } catch (error) {
+      return { id: entry?.id ?? null, path: entry?.path ?? null, status: 'refused', reason: `entry evaluation failed: ${error?.message ?? error}`, checks: [] }
+    }
+  })
+  rows.sort((a, b) => (b.bytes ?? 0) - (a.bytes ?? 0))
+  const view = rows.map(publicRow)
+  return {
+    version: 1, command: 'plan', ok: true, applied: false,
+    repo: ctx.repo, root: ctx.root,
+    generatedDays, artifactDays, now: isoTimestamp(nowMs),
+    entries: view,
+    targets: view.filter((r) => r.status === 'ready'),
+    summary: summarize(rows),
+    inventory: inventory(ctx.rootReal, ctx.bounds),
+    evidenceScanComplete: ctx.evidence.complete,
+    errors: [],
+  }
+}
+
+// ---- apply ----
+
+function quarantineDestination(target, id, atMs) {
+  return join(dirname(target), `${QUARANTINE_PREFIX}${safeId(id)}-${isoTimestamp(atMs).replace(/[:.]/g, '-')}`)
+}
+
+function applyOne(context, row) {
+  const { entry, ctx } = context
+  const target = resolve(entry.path)
+  const atMs = ctx.nowMs
+  const receiptBase = {
+    version: RECEIPT_VERSION, kind: 'retention-receipt', id: entry.id, path: normPath(target),
+    root: normPath(ctx.root), repo: normPath(ctx.repo), run: normPath(entry.owner.run),
+    unit: entry.owner.unit, owner: entry.owner, resourceKind: entry.kind, recipe: entry.recipe ?? '',
+    format: entry.format ?? 'generic', inputProofs: entry.inputProofs ?? null,
+    identity: entry.identity, atMs, at: isoTimestamp(atMs),
+    status: 'applying', removed: false, quarantine: null,
+  }
+  // A fresh inode check immediately before anything else.
+  const before = lstatOrNull(target)
+  if (!before) return { action: 'retained', reason: `${target} disappeared before apply` }
+  if (before.dev !== entry.identity.dev || before.ino !== entry.identity.ino) {
+    return { action: 'retained', reason: `${target} dev/ino changed before apply; a replacement tree is never removed` }
+  }
+  const first = inspectTree(target, { ...ctx.bounds, hashContent: true })
+  const firstTyped = formatVerdict(entry, target, first)
+  if (firstTyped.typed && !firstTyped.ok) {
+    return { action: 'retained', reason: `${firstTyped.format} resource is not proven reusable immediately before apply: ${firstTyped.reason}`, rebuildRequired: true }
+  }
+  const unsafe = treeSafety(target, first, firstTyped)
+  if (unsafe) return { action: 'retained', reason: unsafe }
+  if (!sameSnapshot(row.snapshot, snapshotOf(first))) {
+    return { action: 'retained', reason: `${target} changed between plan evaluation and apply` }
+  }
+
+  // Test seam only: a real filesystem writer outside this function is the production
+  // equivalent. It runs before the final snapshot recheck, never after it.
+  ctx.hooks.beforeQuarantine?.({ entry: publicRow(row), target })
+
+  const second = inspectTree(target, { ...ctx.bounds, hashContent: true })
+  const secondTyped = formatVerdict(entry, target, second)
+  if (secondTyped.typed && !secondTyped.ok) {
+    return { action: 'retained', reason: `${secondTyped.format} resource is not proven reusable immediately before quarantine: ${secondTyped.reason}`, rebuildRequired: true }
+  }
+  const secondUnsafe = treeSafety(target, second, secondTyped)
+  if (secondUnsafe) return { action: 'retained', reason: secondUnsafe }
+  if (!sameSnapshot(snapshotOf(first), snapshotOf(second))) {
+    return { action: 'retained', reason: `${target} changed immediately before quarantine; nothing was moved` }
+  }
+  // Owner authority is re-read here, not trusted from evaluation: a worker can be admitted,
+  // a delivery withdrawn, or another unit or run can declare this tree between the first
+  // snapshot and the rename. The plan revision binds this step to the plan evaluation read.
+  let fresh
+  try { fresh = loadOwner(ctx, entry) } catch (error) {
+    return { action: 'retained', reason: `owner run cannot be resolved immediately before quarantine: ${error?.message ?? error}` }
+  }
+  if (!fresh.ok) return { action: fresh.status, reason: fresh.reason }
+  const index = planIndex(ctx.rootReal, ctx.bounds)
+  const gate = ownerGate({ ctx, entry, target, loaded: fresh, claims: index.claims, evidence: index.evidence })
+  if (gate) return { action: gate.status, reason: gate.reason }
+  if (row.ownerRevision === undefined || fresh.revision !== row.ownerRevision) {
+    return { action: 'retained', reason: `owner task-plan ${fresh.planPath} changed during apply; ${target} was retained, restart with a fresh plan` }
+  }
+  const stillThere = lstatOrNull(target)
+  if (!stillThere || stillThere.dev !== entry.identity.dev || stillThere.ino !== entry.identity.ino) {
+    return { action: 'retained', reason: `${target} identity changed immediately before quarantine` }
+  }
+  const freshManifest = readManifest(ctx.root)
+  const freshEntry = freshManifest.entries.find((item) => item?.id === entry.id)
+  if (!freshEntry || JSON.stringify(freshEntry) !== JSON.stringify(entry)) {
+    return { action: 'retained', reason: `the manifest entry for ${entry.id} changed during apply; restart with a fresh plan` }
+  }
+  const live = ctx.probe([target], { onUncertain: () => {} })
+  if (live === 'unreadable' || live === 'unavailable' || !Array.isArray(live)) {
+    return { action: 'retained', reason: `process use of ${target} became uncertain immediately before apply` }
+  }
+  if (live.length) return { action: 'retained', reason: `${live.length} process(es) are using ${target} immediately before apply` }
+
+  let receipt
+  try {
+    receipt = writeReceipt(ctx.root, receiptBase)
+  } catch (error) {
+    return { action: 'failed', reason: error.message, ioFailure: true }
+  }
+  const quarantine = quarantineDestination(target, entry.id, atMs)
+  if (existsSync(quarantine)) {
+    const failed = { ...receiptBase, receipt, status: 'failed', reason: `quarantine destination ${quarantine} already exists` }
+    try { writeReceipt(ctx.root, failed, receipt) } catch { /* already an I/O failure */ }
+    return { action: 'failed', reason: failed.reason, receipt, ioFailure: true }
+  }
+  try {
+    renameSync(target, quarantine)
+  } catch (error) {
+    const failed = { ...receiptBase, receipt, status: 'failed', reason: `quarantine rename failed: ${error?.code ?? error?.message}` }
+    try { writeReceipt(ctx.root, failed, receipt) } catch { /* receipt failure is reported below */ }
+    return { action: 'failed', reason: failed.reason, receipt, ioFailure: true }
+  }
+  const moved = inspectTree(quarantine, { ...ctx.bounds, hashContent: true })
+  if (!moved.ok || !sameSnapshot(snapshotOf(second), snapshotOf(moved)) || moved.rootIdentity?.dev !== entry.identity.dev || moved.rootIdentity?.ino !== entry.identity.ino) {
+    let restored = true
+    try { renameSync(quarantine, target) } catch { restored = false }
+    const failed = {
+      ...receiptBase, receipt, status: 'failed', quarantine,
+      reason: restored
+        ? 'content changed at the quarantine destination; the tree was restored and retained'
+        : 'content changed at the quarantine destination and restoring the original name failed; inspect the quarantine path',
+    }
+    try { writeReceipt(ctx.root, failed, receipt) } catch { /* reported as IO failure */ }
+    return { action: restored ? 'retained' : 'failed', reason: failed.reason, receipt, quarantine, ioFailure: !restored }
+  }
+  try {
+    ctx.hooks.beforeDelete?.({ entry: publicRow(row), quarantine })
+    // fs.rm removes a symbolic link itself and never walks through it, so an external
+    // reference inside a proven format is unlinked while its destination is untouched.
+    rmSync(quarantine, { recursive: true, force: true })
+  } catch (error) {
+    const failed = {
+      ...receiptBase, receipt, status: 'failed', quarantine,
+      reason: `removal of the quarantined tree failed: ${error?.code ?? error?.message}; the original path is gone`,
+    }
+    try { writeReceipt(ctx.root, failed, receipt) } catch { /* reported as IO failure */ }
+    return { action: 'failed', reason: failed.reason, receipt, quarantine, ioFailure: true }
+  }
+  if (existsSync(target) || existsSync(quarantine)) {
+    const failed = { ...receiptBase, receipt, status: 'failed', quarantine, reason: 'a removal postcondition is not established; the original path or quarantine still exists' }
+    try { writeReceipt(ctx.root, failed, receipt) } catch { /* reported as IO failure */ }
+    return { action: 'failed', reason: failed.reason, receipt, quarantine, ioFailure: true }
+  }
+  const complete = {
+    ...receiptBase, receipt, status: 'complete', quarantine,
+    removedAt: isoTimestamp(atMs), removed: true,
+    snapshot: {
+      digest: second.digest, entries: second.entries, files: second.files,
+      allocatedBytes: second.allocatedBytes, newestMtimeMs: second.newestMtimeMs,
+    },
+  }
+  try {
+    writeReceipt(ctx.root, complete, receipt)
+  } catch (error) {
+    return { action: 'failed', reason: `the tree was removed but the complete receipt cannot be written: ${error.message}`, receipt, quarantine, ioFailure: true }
+  }
+  const updated = readManifest(ctx.root)
+  const next = updated.entries.map((item) => item?.id === entry.id
+    ? { ...item, cleanupState: 'removed', removedAt: isoTimestamp(atMs), receipt: normPath(receipt) }
+    : item)
+  try {
+    writeManifest(ctx.root, { ...updated, version: MANIFEST_VERSION, entries: next })
+  } catch (error) {
+    return { action: 'removed', reason: `removed and receipted, but the manifest marker could not be written: ${error.message}`, receipt, quarantine, ioFailure: true }
+  }
+  return { action: 'removed', reason: `quarantined, verified, and removed; receipt ${receipt}`, receipt, quarantine }
+}
+
+export function applyRetention({
+  repo, generatedDays = 7, artifactDays = 30, now, probe = liveProcessesUsing, bounds = {}, hooks = {},
+} = {}) {
+  assertDays(generatedDays, '--generated-days')
+  assertDays(artifactDays, '--artifact-days')
+  const nowMs = nowValue(now)
+  const { root } = canonicalRoot(repo)
+  if (!existsSync(root)) return { ...planRetention({ repo, generatedDays, artifactDays, now: nowMs, probe, bounds }), command: 'apply', applied: false, actions: [], ioFailures: [] }
+  const lock = acquireLock(root)
+  try {
+    const manifest = readManifest(root)
+    const ctx = baseContext({ repo, generatedDays, artifactDays, now: nowMs, probe, bounds: normalizeBounds(bounds) }, manifest)
+    ctx.hooks = hooks
+    const rows = manifest.entries.map((entry, index) => {
+      try { return { entry, row: evaluateEntry({ entry, index, manifest, ctx, mode: 'apply' }) } } catch (error) {
+        return { entry, row: { id: entry?.id ?? null, path: entry?.path ?? null, status: 'refused', reason: `entry evaluation failed: ${error?.message ?? error}`, checks: [] } }
+      }
+    })
+    rows.sort((a, b) => (b.row.bytes ?? 0) - (a.row.bytes ?? 0))
+    const ioFailures = []
+    const results = []
+    for (const { entry, row } of rows) {
+      if (row.status === 'already-removed') {
+        const latest = readManifest(root)
+        const saved = latest.entries.find((item) => item?.id === entry.id)
+        if (saved && saved.cleanupState !== 'removed') {
+          try {
+            writeManifest(root, {
+              ...latest,
+              entries: latest.entries.map((item) => (item?.id === entry.id
+                ? { ...item, cleanupState: 'removed', removedAt: item.removedAt ?? isoTimestamp(nowMs), receipt: row.receipt }
+                : item)),
+            })
+          } catch (error) {
+            ioFailures.push({ id: entry.id, path: entry.path, reason: error.message })
+          }
+        }
+        results.push({ ...publicRow(row), action: 'already-removed' })
+        continue
+      }
+      if (row.status !== 'ready') {
+        results.push({ ...publicRow(row), action: row.status })
+        continue
+      }
+      let outcome
+      try { outcome = applyOne({ entry, ctx, row }, row) } catch (error) {
+        outcome = { action: 'failed', reason: `apply failed safely: ${error?.message ?? error}`, ioFailure: true }
+      }
+      if (outcome.action === 'failed' && outcome.receipt) {
+        try {
+          const latest = readManifest(root)
+          writeManifest(root, {
+            ...latest,
+            entries: latest.entries.map((item) => (item?.id === entry.id
+              ? { ...item, cleanupState: 'failed', receipt: outcome.receipt, failedAt: isoTimestamp(nowMs) }
+              : item)),
+          })
+        } catch (error) { ioFailures.push({ id: entry.id, path: entry.path, reason: error.message }) }
+      }
+      if (outcome.ioFailure) ioFailures.push({ id: entry.id, path: entry.path, reason: outcome.reason })
+      results.push({ ...publicRow(row), ...outcome })
+    }
+    return {
+      version: 1, command: 'apply', ok: ioFailures.length === 0, applied: true,
+      repo: ctx.repo, root: ctx.root,
+      generatedDays, artifactDays, now: isoTimestamp(nowMs),
+      evidenceScanComplete: ctx.evidence.complete,
+      lockRecovery: lock.recovery,
+      entries: results,
+      summary: summarize(results.map((r) => ({ ...r, status: r.action === 'removed' ? 'removed' : r.status }))),
+      ioFailures,
+      errors: ioFailures.map((f) => f.reason),
+    }
+  } finally {
+    lock.release()
+  }
+}
+
+// ---- register ----
+
+function assertTimestamp(value, flag) {
+  if (timestamp(value) === null) throw new UsageError(`${flag} must be an ISO-8601 UTC timestamp such as 2026-10-01T00:00:00.000Z`)
+  return new Date(timestamp(value)).toISOString()
+}
+
+// The format and its explicit rebuild inputs are caller choices, so a wrong combination is
+// a usage error and never a guess. A generic resource records no input proof at all.
+function formatInputs(format, inputs) {
+  if (!nonEmpty(format)) throw new UsageError('--format must be a format name')
+  if (!FORMATS.has(format)) throw new UsageError(`--format must be ${[...FORMATS].join('|')}`)
+  const list = (Array.isArray(inputs) ? inputs : [inputs]).filter((value) => value !== undefined)
+  for (const value of list) {
+    if (!nonEmpty(value) || !isAbsolute(value)) throw new UsageError('--input must be an absolute canonical rebuild input path')
+  }
+  if (format === 'generic') {
+    if (list.length) throw new UsageError('--input is only meaningful with a typed --format; a generic resource records no rebuild input proof')
+    return []
+  }
+  if (!list.length) throw new UsageError(`--format ${format} needs its canonical rebuild inputs (--input <absolute path>)`)
+  return list
+}
+
+export function registerResource({
+  repo, run, unit, path, kind, lastUsedAt, recipe, releaseOwner = false, format = 'generic', inputs = [], dryRun = false, now,
+  bounds = {},
+} = {}) {
+  const nowMs = nowValue(now)
+  const { root } = canonicalRoot(repo, { mustExist: true })
+  if (!nonEmpty(unit)) throw new UsageError('--unit must be a unit id')
+  if (!KINDS.has(kind)) throw new UsageError('--kind must be generated or artifact')
+  if (!nonEmpty(path) || !isAbsolute(path)) throw new UsageError('--path must be an absolute path')
+  const rebuildInputs = formatInputs(format, inputs)
+  if (lastUsedAt === undefined) throw new UsageError('--last-used-at is required; activity dates are caller-supplied, never inferred')
+  const usedAt = assertTimestamp(lastUsedAt, '--last-used-at')
+  if (timestamp(usedAt) > nowMs) throw new RetentionError('timestamp', `--last-used-at ${usedAt} is in the future`)
+  if (kind === 'generated' && !nonEmpty(recipe)) throw new UsageError('a generated resource needs a nonempty --recipe for reconstruction')
+  if (kind === 'artifact' && recipe !== undefined && typeof recipe !== 'string') throw new UsageError('--recipe must be text')
+  if (!nonEmpty(run) || !isAbsolute(run)) throw new UsageError('--run must be an absolute run directory')
+  const runReal = canonicalExistingDir(run, 'run directory')
+  const rootReal = real(root)
+  if (!strictInside(rootReal, runReal)) throw new RetentionError('ownership', `run ${runReal} is not inside the canonical root ${root}`)
+  if (symlinkOnPath(rootReal, resolve(run))) throw new RetentionError('symlink', `run ${run} passes through a symbolic link`)
+  const planPath = join(runReal, 'task-plan.json')
+  const plan = readPlanFile(planPath)
+  if (!plan) throw new RetentionError('plan', `owner task-plan ${planPath} is missing or unreadable`)
+  const member = unitOfPlan(plan, unit)
+  if (!member) throw new RetentionError('ownership', `unit ${unit} is not recorded in ${planPath}`)
+  const lexicalTarget = resolve(path)
+  const lexicalRelative = relative(rootReal, lexicalTarget)
+  if (!lexicalRelative.startsWith(`..${sep}`) && lexicalRelative !== '..' && !isAbsolute(lexicalRelative)
+    && symlinkOnPath(rootReal, lexicalTarget)) {
+    throw new RetentionError('symlink', `${lexicalTarget} passes through a symbolic link below the canonical root`)
+  }
+  const target = canonicalExistingDir(path, 'resource path')
+  if (!strictInside(real(root), target)) throw new RetentionError('ownership', `${target} is not inside the canonical root ${root}`)
+  if (symlinkOnPath(real(root), target)) throw new RetentionError('symlink', `${target} passes through a symbolic link`)
+  const ownership = ownershipProblem({ root, run: runReal, unit: member, unitId: unit, target, plan })
+  if (ownership) throw new RetentionError('ownership', ownership)
+  const completed = unitCompleted(member)
+  if (member.worker != null && member.worker !== '') {
+    throw new RetentionError('owner-active', `unit ${unit} records active worker ${member.worker}; release it before registering its resources`)
+  }
+  // Inventory is recorded before worker admission. Only eligibility grants a
+  // release; registering unfinished work must not authorize its deletion.
+  const inspection = inspectTree(target, { ...normalizeBounds(bounds), hashContent: true })
+  // The typed proof is taken from this same inspection, so registering a format costs one
+  // tree walk, not two. Nothing is relaxed until the format is positively proven.
+  const typed = format === 'generic' ? null : inspectResourceFormat({ format, path: target, inputs: rebuildInputs, inspection })
+  if (typed && !typed.ok) throw new RetentionError('format', `${format} is not proven for ${target}: ${typed.reason}`)
+  const unsafe = treeSafety(target, inspection, typed)
+  if (unsafe) throw new RetentionError('refused', unsafe)
+  const index = planIndex(real(root), normalizeBounds(bounds))
+  const evidence = requiredEvidenceOverlap(target, index.evidence)
+  if (evidence) throw new RetentionError('evidence', evidence)
+  const claim = claimConflict(target, index.claims, { run: runReal, unit })
+  if (claim) throw new RetentionError('overlap', claim.reason)
+  const id = `${kind}-${createHash('sha256').update(target).digest('hex').slice(0, 12)}`
+  const identity = { dev: lstatSync(target).dev, ino: lstatSync(target).ino }
+  const entryFor = (existing) => ({
+    id,
+    path: target,
+    kind,
+    format,
+    ...(typed ? { inputProofs: typed.inputProofs } : {}),
+    owner: { run: runReal, unit: String(unit) },
+    lastUsedAt: usedAt,
+    disposable: true,
+    pinned: existing?.pinned === true,
+    recipe: kind === 'generated' ? String(recipe).trim() : String(recipe ?? ''),
+    identity,
+    authorization: { source: 'explicit-registration', at: isoTimestamp(nowMs) },
+    ...(releaseOwner === true ? { ownerReleased: true } : {}),
+  })
+  const registered = (entry, saved, existing) => ({
+    version: 1, command: 'register', ok: true, applied: !dryRun, dryRun,
+    repo: canonicalRepo(repo), root, manifest: saved,
+    entry,
+    resource: {
+      id, path: target, kind, format, identity, owner: entry.owner,
+      ...(typed ? { inputProofs: typed.inputProofs } : {}),
+    },
+    authorization: entry.authorization,
+    ownerCompleted: completed,
+    ownerReleased: entry.ownerReleased === true,
+    ...(existing ? { refreshed: true } : {}),
+    ...(typed ? { markers: typed.markers } : {}),
+  })
+  if (dryRun) {
+    // Preview: every safety and reuse check above ran, but nothing was acquired or written.
+    const manifest = readManifest(root)
+    const existing = manifest.entries.find((item) => item?.id === id)
+    if (!existing) {
+      const overlap = overlappingPairs([...manifest.entries, { id, path: target }]).get(manifest.entries.length)
+      if (overlap?.length) throw new RetentionError('overlap', `${target} overlaps registered resource(s) ${overlap.join(', ')}; overlapping registrations are refused`)
+    }
+    return registered(entryFor(existing), manifestPath(root), existing)
+  }
+  const lock = acquireLock(root)
+  try {
+    // Ownership can change while the lock is acquired: another unit or run may have
+    // declared the same tree, so the claim scan is repeated from the plans on disk.
+    const freshClaim = claimConflict(target, planIndex(real(root), normalizeBounds(bounds)).claims, { run: runReal, unit })
+    if (freshClaim) throw new RetentionError('overlap', freshClaim.reason)
+    const manifest = readManifest(root)
+    const existing = manifest.entries.find((entry) => entry?.id === id)
+    if (!existing) {
+      const overlap = overlappingPairs([...manifest.entries, { id, path: target }]).get(manifest.entries.length)
+      if (overlap?.length) throw new RetentionError('overlap', `${target} overlaps registered resource(s) ${overlap.join(', ')}; overlapping registrations are refused`)
+    }
+    const entry = entryFor(existing)
+    const next = existing
+      ? manifest.entries.map((item) => (item?.id === id ? entry : item))
+      : [...manifest.entries, entry]
+    const saved = writeManifest(root, { ...manifest, version: MANIFEST_VERSION, entries: next })
+    return { ...registered(entry, saved, existing), lockRecovery: lock.recovery }
+  } finally {
+    lock.release()
+  }
+}
+
+// ---- status ----
+
+// Read-only reuse verdict for one registered resource. It re-proves the recorded format
+// from a fresh (cheap, content-free) tree inspection and re-validates the recorded rebuild
+// inputs; it never writes, never executes the recipe, and never acquires the lock. A
+// partial root left by a manual cleanup stays partial: presence of the parent directory is
+// not evidence that the resource is usable.
+function statusOf(entry, bounds) {
+  const row = {
+    id: entry?.id ?? null,
+    path: entry?.path ?? null,
+    kind: entry?.kind ?? null,
+    format: nonEmpty(entry?.format) ? entry.format : 'generic',
+    recipe: typeof entry?.recipe === 'string' ? entry.recipe : null,
+    owner: entry?.owner ?? null,
+    lastUsedAt: entry?.lastUsedAt ?? null,
+    inputs: Array.isArray(entry?.inputProofs)
+      ? entry.inputProofs.map((proof) => ({ name: proof?.name ?? null, path: proof?.path ?? null }))
+      : [],
+    state: 'invalid',
+    ready: false,
+    rebuildRequired: true,
+    reason: null,
+  }
+  const parsed = parseEntry(entry, { forStatus: true })
+  if (parsed.problems.length) { row.reason = parsed.problems.join('; '); return row }
+  row.format = parsed.format
+  if (entry.cleanupState === 'removed') {
+    row.state = 'removed'
+    row.reason = 'the manifest records this resource as removed; only its recipe can recreate it'
+    return row
+  }
+  const target = resolve(entry.path)
+  const st = lstatOrNull(target)
+  if (!st) {
+    row.state = 'missing'
+    row.reason = `${target} does not exist; rebuild it with the retained recipe`
+    return row
+  }
+  if (st.isSymbolicLink() || !st.isDirectory()) {
+    row.state = 'partial'
+    row.reason = `${target} is not a real directory, so the recorded resource is no longer there`
+    return row
+  }
+  // Readiness is not deletion eligibility. Pins, credentials and reference links
+  // protect cleanup but do not make a structurally valid installation broken.
+  const typed = parsed.format === 'generic'
+    ? { typed: false, ok: true }
+    : { typed: true, ...classifyRebuildState({ format: parsed.format, path: target, inputProofs: entry.inputProofs }) }
+  if (typed.typed && !typed.ok) {
+    // A partial install or a changed lockfile is deferred work, never a silent success.
+    row.state = typed.state === 'missing' ? 'missing' : typed.state === 'inputs-changed' ? 'inputs-changed' : 'partial'
+    row.reason = typed.reason
+    return row
+  }
+  row.state = 'ready'
+  row.ready = true
+  row.rebuildRequired = false
+  row.reason = typed.typed
+    ? `${parsed.format} markers and rebuild inputs still match the registration`
+    : 'present; a generic resource carries no typed format proof'
+  return row
+}
+
+function statusFilter({ run, unit } = {}) {
+  if (run === undefined && unit === undefined) return { matches: () => true, describe: null }
+  if (run === undefined || unit === undefined) throw new UsageError('status takes --run and --unit together')
+  if (!nonEmpty(run) || !isAbsolute(run)) throw new UsageError('--run must be an absolute run directory')
+  const runReal = canonicalExistingDir(run, 'run directory')
+  return {
+    matches: (entry) => isObject(entry?.owner) && entry.owner.run === runReal && String(entry.owner.unit) === String(unit),
+    describe: { run: runReal, unit: String(unit) },
+  }
+}
+
+export function resourceStatus({ repo, run, unit, bounds = {} } = {}) {
+  const { root, repo: canonical } = canonicalRoot(repo)
+  const filter = statusFilter({ run, unit })
+  const manifest = existsSync(root) ? readManifest(root) : { version: MANIFEST_VERSION, entries: [] }
+  const entries = manifest.entries
+    .filter((entry) => filter.matches(entry))
+    .map((entry) => {
+      try {
+        return statusOf(entry, bounds)
+      } catch (error) {
+        return {
+          id: entry?.id ?? null, path: entry?.path ?? null, state: 'unreadable', ready: false,
+          rebuildRequired: true, reason: `status could not be read: ${error?.message ?? error}`,
+        }
+      }
+    })
+    .sort((a, b) => String(a.path).localeCompare(String(b.path)))
+  const counts = {}
+  for (const entry of entries) counts[entry.state] = (counts[entry.state] ?? 0) + 1
+  return {
+    version: 1, command: 'status', ok: true, readOnly: true, applied: false,
+    repo: canonical, root, filter: filter.describe, entries, counts,
+    summary: {
+      total: entries.length,
+      ready: entries.filter((entry) => entry.ready).length,
+      rebuildRequired: entries.filter((entry) => entry.rebuildRequired).length,
+      byState: counts,
+    },
+    errors: [],
+  }
+}
+
+// ---- recover ----
+
+// Read-only receipt inventory. A receipt is the only record of what an interrupted apply
+// reached, so recovery reports it and changes nothing about it.
+function receiptReport(root) {
+  const dir = join(root, RECEIPT_DIR)
+  let names
+  try { names = readdirSync(dir) } catch {
+    return { dir, count: 0, entries: [], counts: { total: 0, applying: 0, complete: 0, failed: 0, other: 0 }, truncated: false }
+  }
+  const files = names.filter((name) => name.endsWith('.json')).sort()
+  const entries = []
+  for (const name of files.slice(0, MAX_STATUS_RECEIPTS)) {
+    const path = join(dir, name)
+    const st = lstatOrNull(path)
+    if (!st || st.isSymbolicLink() || !st.isFile() || st.size > 4 * 1024 * 1024) {
+      entries.push({ file: name, status: 'unreadable' })
+      continue
+    }
+    let saved
+    try { saved = JSON.parse(readFileSync(path, 'utf8')) } catch { entries.push({ file: name, status: 'unreadable' }); continue }
+    entries.push({
+      file: name,
+      id: saved?.id ?? null,
+      path: saved?.path ?? null,
+      status: saved?.status ?? 'unknown',
+      at: saved?.at ?? null,
+      quarantine: saved?.quarantine ?? null,
+      removed: saved?.removed === true,
+      reason: saved?.reason ?? null,
+    })
+  }
+  const counts = { total: files.length, applying: 0, complete: 0, failed: 0, other: 0 }
+  for (const entry of entries) {
+    if (entry.status === 'applying') counts.applying += 1
+    else if (entry.status === 'complete') counts.complete += 1
+    else if (entry.status === 'failed') counts.failed += 1
+    else counts.other += 1
+  }
+  return { dir, count: files.length, entries, counts, truncated: files.length > MAX_STATUS_RECEIPTS }
+}
+
+export function recoverRetention({ repo, apply = false } = {}) {
+  const { root } = canonicalRoot(repo)
+  const canonical = canonicalRepo(repo)
+  if (!existsSync(root)) {
+    return {
+      version: 1, command: 'recover', ok: true, applied: false, dryRun: !apply,
+      repo: canonical, root, lockPath: join(root, LOCK_NAME), status: 'absent', action: 'none',
+      reason: 'root-missing', detail: `${root} does not exist`, cleared: { lock: false, tombstones: [] },
+      remaining: { lock: false, tombstones: [] }, tombstones: [], quarantines: [],
+      receipts: { dir: join(root, RECEIPT_DIR), count: 0, entries: [], counts: { total: 0, applying: 0, complete: 0, failed: 0, other: 0 }, truncated: false },
+      resourcesUntouched: true, claimsSuccessor: false,
+      note: 'there is nothing to recover; no cleanup state was read or changed',
+    }
+  }
+  const recovery = recoverRetentionLock(root, { apply })
+  return {
+    ...recovery,
+    version: 1,
+    command: 'recover',
+    repo: canonical,
+    ok: recovery.failures.length === 0,
+    applied: recovery.cleared.lock || recovery.cleared.tombstones.length > 0,
+    receipts: receiptReport(recovery.root),
+    resourcesUntouched: true,
+    claimsSuccessor: false,
+  }
+}
+
+// ---- register-owned (bounded batch inventory) ----
+
+// The batch form reads only what the unit's plan declares. It needs an explicit retention
+// record per resource and never adopts an unrecorded path, so a path the plan does not
+// carry stays invisible here no matter how old or how large it is.
+function retentionSpec(resource) {
+  const raw = resource?.retention
+  if (!isObject(raw)) return { ok: false, reason: 'the declared resource carries no retention metadata ({kind, format, recipe, inputs})' }
+  if (!KINDS.has(raw.kind)) return { ok: false, reason: `retention.kind ${String(raw.kind)} is not generated|artifact` }
+  if (!nonEmpty(raw.format) || !FORMATS.has(raw.format)) {
+    return { ok: false, reason: `retention.format ${String(raw.format)} is not ${[...FORMATS].join('|')}` }
+  }
+  if (typeof raw.recipe !== 'string') return { ok: false, reason: 'retention.recipe must be text' }
+  if (raw.inputs !== undefined && !Array.isArray(raw.inputs)) return { ok: false, reason: 'retention.inputs must be an array of absolute paths' }
+  for (const input of Array.isArray(raw.inputs) ? raw.inputs : []) {
+    if (!nonEmpty(input) || !isAbsolute(input)) return { ok: false, reason: 'retention.inputs must be absolute canonical file paths' }
+  }
+  return {
+    ok: true,
+    kind: raw.kind,
+    format: raw.format,
+    recipe: raw.recipe,
+    inputs: Array.isArray(raw.inputs) ? raw.inputs : [],
+  }
+}
+
+export function registerOwned({ repo, run, unit, lastUsedAt, apply = false, now, bounds = {} } = {}) {
+  const nowMs = nowValue(now)
+  const { root } = canonicalRoot(repo, { mustExist: true })
+  if (!nonEmpty(unit)) throw new UsageError('--unit must be a unit id')
+  if (!nonEmpty(run) || !isAbsolute(run)) throw new UsageError('--run must be an absolute run directory')
+  if (lastUsedAt === undefined) throw new UsageError('--last-used-at is required; activity dates are caller-supplied, never inferred')
+  const usedAt = assertTimestamp(lastUsedAt, '--last-used-at')
+  if (timestamp(usedAt) > nowMs) throw new RetentionError('timestamp', `--last-used-at ${usedAt} is in the future`)
+  const runReal = canonicalExistingDir(run, 'run directory')
+  const rootReal = real(root)
+  if (!strictInside(rootReal, runReal)) throw new RetentionError('ownership', `run ${runReal} is not inside the canonical root ${root}`)
+  if (symlinkOnPath(rootReal, resolve(run))) throw new RetentionError('symlink', `run ${run} passes through a symbolic link`)
+  const planPath = join(runReal, 'task-plan.json')
+  const plan = readPlanFile(planPath)
+  if (!plan) throw new RetentionError('plan', `owner task-plan ${planPath} is missing or unreadable`)
+  const member = unitOfPlan(plan, unit)
+  if (!member) throw new RetentionError('ownership', `unit ${unit} is not recorded in ${planPath}`)
+  const declared = member.lifecycle?.resources
+  if (declared !== undefined && !Array.isArray(declared)) {
+    throw new RetentionError('plan', `unit ${unit} resources are not an array, so the declared inventory cannot be read`)
+  }
+  const declaredTotal = Array.isArray(declared) ? declared.length : 0
+  const list = (Array.isArray(declared) ? declared : []).slice(0, MAX_BATCH_RESOURCES)
+  const truncated = list.length < declaredTotal
+  const registrations = []
+  const deferred = []
+  const uncovered = []
+  const failed = []
+  for (const resource of list) {
+    const declaredPath = isObject(resource) && nonEmpty(resource.path) ? resource.path : null
+    const lexical = declaredPath === null ? null : (isAbsolute(declaredPath) ? resolve(declaredPath) : resolve(runReal, declaredPath))
+    if (!lexical) {
+      uncovered.push({ path: declaredPath, reason: 'the declared resource names no path, so it cannot be registered' })
+      continue
+    }
+    const spec = retentionSpec(resource)
+    if (!spec.ok) {
+      uncovered.push({ path: lexical, reason: spec.reason })
+      continue
+    }
+    try {
+      const result = registerResource({
+        repo, run: runReal, unit, path: lexical, kind: spec.kind, format: spec.format,
+        inputs: spec.inputs, recipe: spec.recipe, lastUsedAt: usedAt, now: nowMs, bounds,
+        dryRun: !apply,
+      })
+      registrations.push({
+        path: result.resource.path,
+        id: result.resource.id,
+        kind: spec.kind,
+        format: spec.format,
+        recipe: spec.recipe,
+        inputs: spec.inputs,
+        action: apply ? 'registered' : 'would-register',
+        state: apply ? 'registered' : 'verified',
+        refreshed: result.refreshed === true,
+        ownerReleased: result.ownerReleased === true,
+      })
+    } catch (error) {
+      const entry = {
+        path: lexical,
+        kind: spec.kind,
+        format: spec.format,
+        recipe: spec.recipe,
+        inputs: spec.inputs,
+        state: 'deferred',
+        deferredReason: error?.code ?? 'error',
+        reason: error?.message ?? String(error),
+      }
+      // An I/O failure is not a deferral: the command must not report full coverage.
+      if (entry.deferredReason === 'io') failed.push(entry)
+      else deferred.push(entry)
+    }
+  }
+  const counts = {
+    declared: list.length,
+    declaredTotal,
+    registrations: registrations.length,
+    deferred: deferred.length,
+    uncovered: uncovered.length,
+    failed: failed.length,
+    bounded: truncated,
+  }
+  const complete = deferred.length === 0 && uncovered.length === 0 && failed.length === 0 && !truncated
+  return {
+    version: 1, command: 'register-owned', ok: complete, applied: apply, dryRun: !apply,
+    repo: canonicalRepo(repo), root, run: runReal, unit: String(unit), lastUsedAt: usedAt,
+    ownerCompleted: unitCompleted(member),
+    // The batch form records inventory; it never releases an unfinished owner's resource.
+    ownerReleaseRequested: false,
+    registrations, deferred, uncovered, failed, counts,
+    coverage: {
+      complete,
+      reason: list.length === 0
+        ? `unit ${unit} declares no resources`
+        : truncated
+          ? `the declared inventory exceeds the ${MAX_BATCH_RESOURCES}-resource batch bound; ${declaredTotal - list.length} resource(s) were not examined`
+          : complete
+            ? `every declared resource with retention metadata was ${apply ? 'registered' : 'verified'}`
+            : `${counts.deferred} deferred, ${counts.uncovered} uncovered, ${counts.failed} failed of ${counts.declared} declared`,
+    },
+    errors: failed.map((entry) => entry.reason),
+  }
+}
+
+// ---- CLI ----
+
+function positiveOrZero(value, flag) {
+  const number = Number(value)
+  if (!Number.isSafeInteger(number) || number < 0) throw new UsageError(`${flag} must be a nonnegative integer`)
+  return number
+}
+
+const COMMANDS = new Set(['plan', 'apply', 'register', 'register-owned', 'status', 'recover'])
+const APPLY_COMMANDS = new Set(['apply', 'recover', 'register-owned'])
+
+// Which flags each command accepts. Anything else is a usage error, so a misplaced flag can
+// never quietly change what a command does.
+const COMMAND_FLAGS = {
+  plan: ['--repo', '--generated-days', '--artifact-days'],
+  apply: ['--repo', '--generated-days', '--artifact-days'],
+  register: ['--repo', '--run', '--unit', '--path', '--kind', '--last-used-at', '--recipe', '--format', '--input'],
+  'register-owned': ['--repo', '--run', '--unit', '--last-used-at'],
+  status: ['--repo', '--run', '--unit'],
+  recover: ['--repo'],
+}
+const BOOLEAN_FLAGS = {
+  register: ['--release-owner'],
+}
+const REGISTER_ARG_FLAGS = new Set(['--run', '--unit', '--path', '--kind', '--last-used-at', '--recipe', '--format', '--input'])
+
+export function parseArgs(argv) {
+  const opts = {
+    command: null, repo: null, generatedDays: 7, artifactDays: 30, json: false, apply: false,
+    run: null, unit: null, path: null, kind: null, lastUsedAt: null, recipe: undefined,
+    format: null, inputs: [], releaseOwner: false, help: false,
+  }
+  const seen = new Set()
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (!opts.command && COMMANDS.has(arg)) { opts.command = arg; continue }
+    if (arg === '--apply') { opts.apply = true; continue }
+    if (arg === '--json') { opts.json = true; continue }
+    if (arg === '--release-owner') { opts.releaseOwner = 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]
+    }
+    if (arg === '--repo') opts.repo = value()
+    else if (arg === '--generated-days') opts.generatedDays = positiveOrZero(value(), '--generated-days')
+    else if (arg === '--artifact-days') opts.artifactDays = positiveOrZero(value(), '--artifact-days')
+    else if (arg === '--run') opts.run = value()
+    else if (arg === '--unit') opts.unit = value()
+    else if (arg === '--path') opts.path = value()
+    else if (arg === '--kind') opts.kind = value()
+    else if (arg === '--last-used-at') opts.lastUsedAt = value()
+    else if (arg === '--recipe') opts.recipe = value()
+    else if (arg === '--format') opts.format = value()
+    else if (arg === '--input') opts.inputs.push(value())
+    else throw new UsageError(`unrecognized argument ${arg}`)
+    if (['--generated-days', '--artifact-days', '--run', '--unit', '--path', '--kind', '--last-used-at', '--recipe', '--format', '--input'].includes(arg)) seen.add(arg)
+  }
+  if (opts.help) return opts
+  if (!opts.command) opts.command = opts.apply ? 'apply' : 'plan'
+  if (opts.apply && !APPLY_COMMANDS.has(opts.command)) throw new UsageError(`${opts.command} does not take --apply`)
+  if (!opts.repo) throw new UsageError('--repo is required')
+  const allowed = new Set(COMMAND_FLAGS[opts.command])
+  const booleans = new Set(BOOLEAN_FLAGS[opts.command] ?? [])
+  for (const flag of seen) {
+    if (!allowed.has(flag)) {
+      throw new UsageError(REGISTER_ARG_FLAGS.has(flag)
+        ? `${opts.command} does not take register arguments (${flag})`
+        : `${opts.command} does not take ${flag}`)
+    }
+  }
+  if (opts.releaseOwner && !booleans.has('--release-owner')) throw new UsageError(`${opts.command} does not take --release-owner`)
+  if (opts.command === 'register') {
+    for (const [flag, key] of [['--run', 'run'], ['--unit', 'unit'], ['--path', 'path'], ['--kind', 'kind'], ['--last-used-at', 'lastUsedAt']]) {
+      if (!nonEmpty(opts[key])) throw new UsageError(`register needs ${flag}`)
+    }
+  }
+  if (opts.command === 'register-owned') {
+    if (!nonEmpty(opts.run)) throw new UsageError('register-owned needs --run')
+    if (!nonEmpty(opts.unit)) throw new UsageError('register-owned needs --unit')
+  }
+  if (opts.command === 'status' && nonEmpty(opts.run) !== nonEmpty(opts.unit)) {
+    throw new UsageError('status takes --run and --unit together')
+  }
+  if (opts.command === 'register-owned' && !nonEmpty(opts.lastUsedAt)) throw new UsageError('register-owned needs --last-used-at')
+  return opts
+}
+
+function renderPlan(result) {
+  const lines = [`retention plan (read-only): ${result.root}`,
+    `  generated ${result.generatedDays}d, artifact ${result.artifactDays}d`]
+  for (const row of result.entries) {
+    lines.push(`  ${row.status.toUpperCase().padEnd(16)} ${row.path ?? '(invalid entry)'}  ${row.reason ?? ''}`)
+  }
+  const s = result.summary
+  lines.push(`  ${s.total} entr${s.total === 1 ? 'y' : 'ies'}: ${s.ready} ready (${s.candidatesBytes} byte(s)), ${s.retained} retained, ${s.refused} refused, ${s.alreadyRemoved} already removed`)
+  if (result.inventory.runs.length) {
+    lines.push('  largest run directories (inventory only, never removal candidates):')
+    for (const run of result.inventory.runs.slice(0, 10)) lines.push(`    ${run.bytes}  ${run.run}${run.truncated ? ' (bounded)' : ''}`)
+  }
+  if (result.inventory.resources?.length) {
+    lines.push('  largest run resources (inventory only; only manifest entries are candidates):')
+    for (const resource of result.inventory.resources.slice(0, 10)) lines.push(`    ${resource.bytes}  ${resource.path}${resource.truncated ? ' (bounded)' : ''}`)
+  }
+  return lines.join('\n')
+}
+
+function renderApply(result) {
+  const lines = [`retention apply: ${result.root}`]
+  for (const row of result.entries) {
+    lines.push(`  ${row.action.toUpperCase().padEnd(16)} ${row.path ?? '(invalid entry)'}  ${row.reason ?? ''}`)
+  }
+  lines.push(`  ${result.entries.length} row(s), ${result.ioFailures.length} I/O failure(s)`)
+  return lines.join('\n')
+}
+
+function renderRegister(result) {
+  return [
+    `${result.dryRun ? 'would register' : 'registered'} ${result.resource.kind} ${result.resource.path}`,
+    `  id ${result.resource.id}  format ${result.resource.format}  identity ${result.resource.identity.dev}/${result.resource.identity.ino}  owner ${result.resource.owner.unit}`,
+    ...(result.resource.inputProofs ? result.resource.inputProofs.map((proof) => `  input ${proof.name} ${proof.path}`) : []),
+    `  authorization ${result.authorization.source} at ${result.authorization.at}${result.ownerReleased ? ' (owner released)' : ''}`,
+    `  manifest ${result.manifest}${result.dryRun ? ' (not written; preview)' : ''}`,
+  ].join('\n')
+}
+
+function renderStatus(result) {
+  const lines = [`retention status (read-only): ${result.root}`]
+  if (result.filter) lines.push(`  filter run ${result.filter.run} unit ${result.filter.unit}`)
+  for (const row of result.entries) {
+    lines.push(`  ${row.state.toUpperCase().padEnd(15)} ${row.path ?? '(invalid entry)'}  ${row.reason ?? ''}`)
+    if (row.recipe) lines.push(`    recipe: ${row.recipe}`)
+    if (row.inputs?.length) lines.push(`    inputs: ${row.inputs.map((input) => `${input.name} ${input.path}`).join(', ')}`)
+  }
+  lines.push(`  ${result.summary.total} registered: ${result.summary.ready} ready, ${result.summary.rebuildRequired} rebuild required`)
+  return lines.join('\n')
+}
+
+function renderRecover(result) {
+  const lines = [
+    `retention recover${result.dryRun ? ' (read-only)' : ''}: ${result.root}`,
+    `  status ${result.status}  action ${result.action}  reason ${result.reason ?? '(none)'}  ${result.detail ?? ''}`,
+    `  cleared lock ${result.cleared.lock ? 'yes' : 'no'}, tombstones ${result.cleared.tombstones.length}`,
+  ]
+  const receipts = result.receipts
+  lines.push(`  receipts: ${receipts.counts.total} total, ${receipts.counts.applying} applying, ${receipts.counts.failed} failed, ${receipts.counts.complete} complete (unchanged)`)
+  for (const receipt of receipts.entries.filter((entry) => entry.status !== 'complete').slice(0, 10)) {
+    lines.push(`    ${receipt.status} ${receipt.id ?? receipt.file} ${receipt.path ?? ''} ${receipt.quarantine ? `quarantine ${receipt.quarantine}` : ''}`)
+  }
+  lines.push('  no resource, receipt, or quarantined tree was removed; recovery never claims a successor apply')
+  return lines.join('\n')
+}
+
+function renderRegisterOwned(result) {
+  const lines = [
+    `retention register-owned${result.dryRun ? ' (preview)' : ''}: ${result.root}`,
+    `  run ${result.run} unit ${result.unit} last-used ${result.lastUsedAt}`,
+  ]
+  for (const row of result.registrations) lines.push(`  ${row.action.toUpperCase().padEnd(16)} ${row.path}  ${row.format} ${row.kind}`)
+  for (const row of result.deferred) lines.push(`  DEFERRED         ${row.path}  ${row.reason}`)
+  for (const row of result.failed) lines.push(`  FAILED           ${row.path}  ${row.reason}`)
+  for (const row of result.uncovered) lines.push(`  UNCOVERED        ${row.path ?? '(no path)'}  ${row.reason}`)
+  lines.push(`  ${result.counts.declared} declared: ${result.counts.registrations} ${result.dryRun ? 'verified' : 'registered'}, ${result.counts.deferred} deferred, ${result.counts.uncovered} uncovered, ${result.counts.failed} failed`)
+  lines.push(`  coverage ${result.coverage.complete ? 'complete' : 'partial'}: ${result.coverage.reason}`)
+  return lines.join('\n')
+}
+
+function failure(command, error) {
+  const code = error instanceof UsageError ? 'usage' : (error?.code ?? 'error')
+  return { version: 1, command, ok: false, applied: false, error: { code, message: error?.message ?? String(error) }, errors: [error?.message ?? String(error)] }
+}
+
+export function run(argv, runtime = {}) {
+  let opts
+  try { opts = parseArgs(argv) } catch (error) {
+    return { code: 2, error: error.message, json: failure(null, error), text: `retention: ${error.message}\n${USAGE}` }
+  }
+  if (opts.help) return { code: 0, text: `${USAGE}\n` }
+  const shared = {
+    repo: opts.repo,
+    generatedDays: opts.generatedDays,
+    artifactDays: opts.artifactDays,
+    ...(runtime.now !== undefined ? { now: runtime.now } : {}),
+    ...(runtime.probe ? { probe: runtime.probe } : {}),
+    ...(runtime.bounds ? { bounds: runtime.bounds } : {}),
+    ...(runtime.hooks ? { hooks: runtime.hooks } : {}),
+  }
+  try {
+    if (opts.command === 'register') {
+      const result = registerResource({
+        ...shared, run: opts.run, unit: opts.unit, path: opts.path, kind: opts.kind,
+        lastUsedAt: opts.lastUsedAt, recipe: opts.recipe, releaseOwner: opts.releaseOwner,
+        ...(opts.format !== null ? { format: opts.format } : {}),
+        inputs: opts.inputs,
+      })
+      return { code: 0, json: result, text: renderRegister(result) }
+    }
+    if (opts.command === 'register-owned') {
+      const result = registerOwned({
+        ...shared, run: opts.run, unit: opts.unit, lastUsedAt: opts.lastUsedAt, apply: opts.apply,
+      })
+      return { code: result.ok ? 0 : 1, json: result, text: renderRegisterOwned(result) }
+    }
+    if (opts.command === 'status') {
+      const result = resourceStatus({ ...shared, run: opts.run ?? undefined, unit: opts.unit ?? undefined })
+      return { code: 0, json: result, text: renderStatus(result) }
+    }
+    if (opts.command === 'recover') {
+      const result = recoverRetention({ repo: opts.repo, apply: opts.apply })
+      return { code: result.failures?.length ? 1 : 0, json: result, text: renderRecover(result) }
+    }
+    if (opts.command === 'apply') {
+      const result = applyRetention(shared)
+      return { code: result.ioFailures.length ? 1 : 0, json: result, text: renderApply(result) }
+    }
+    const result = planRetention(shared)
+    return { code: 0, json: result, text: renderPlan(result) }
+  } catch (error) {
+    const code = error instanceof RetentionError ? (error.code === 'io' ? 1 : 2) : 1
+    return { code, error: error.message, json: failure(opts.command, error), text: `retention: ${error.message}` }
+  }
+}
+
+export function main(argv) {
+  const result = run(argv)
+  if (argv.includes('--json')) process.stdout.write(`${JSON.stringify(result.json ?? failure(null, new Error(result.error ?? 'unknown error')), null, 2)}\n`)
+  else if (result.error) process.stderr.write(`${result.text}\n`)
+  else process.stdout.write(`${result.text}\n`)
+  return result.code
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = main(process.argv.slice(2))