@1aboveio/skills 1.0.10 → 1.0.11

package/skills/engineering/harness-runtime/workspace-lifecycle.mjs

@@ -0,0 +1,2154 @@
+// Shared owned-workspace mechanics for workflow and standalone native callers.
+//
+// This module is deliberately a small support module for cleanup-runs.mjs. It does NOT
+// write task-plan.json: the coordinator owns every plan transition through update_plan.
+// Every exported operation returns observations and the next lifecycle value as JSON; the
+// coordinator decides whether to persist it.
+//
+// Ownership authority is the existing task plan. A unit owns exactly what the plan records
+// in `unit.workspace` plus `unit.lifecycle.resources`; anything else under a run is
+// inventory only and is never removed by a glob or by age.
+//
+// Lifecycle shape (version 1):
+//
+//   lifecycle: {
+//     version: 1,
+//     workspace: {
+//       path, kind: 'worktree' | 'clone', state: 'preparing' | 'ready',
+//       baseSha: <exact 40 or 64 hex>,
+//       identity: { realPath, dev, ino, gitCommonDir, headSha }
+//     },
+//     resources: [
+//       { path, kind: 'directory' | 'clone' | 'worktree',
+//         role: 'scratch' | 'tools' | 'review', disposable: true,
+//         state: 'preparing' | 'ready',
+//         identity: { realPath, dev, ino, gitCommonDir? } }
+//     ],
+//     cleanup: { state: 'pending' | 'applying' | 'complete' | 'retained',
+//                headSha, reason?, completedAt?, receipt? }
+//   }
+//
+// Safety rules are fail-closed. A path we cannot identify, a tree we cannot read, a worker
+// recorded for this owner or overlapping paths, a process still using the tree, unknown ignored files,
+// nested repositories, stashes, rebases/merges in progress, any unpublished local ref or
+// reflog commit, or evidence that still lives inside the workspace all retain the whole
+// environment. There is no ignored-file stripping.
+
+import { execFileSync } from 'node:child_process'
+import {
+  existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync,
+  realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs'
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
+
+export const LIFECYCLE_VERSION = 1
+export const CLEANUP_STATES = new Set(['pending', 'applying', 'complete', 'retained'])
+export const WORKSPACE_KINDS = new Set(['worktree', 'clone'])
+export const WORKSPACE_STATES = new Set(['preparing', 'ready'])
+export const RESOURCE_KINDS = new Set(['directory', 'clone', 'worktree'])
+export const RESOURCE_ROLES = new Set(['scratch', 'tools', 'review'])
+export const RECEIPT_VERSION = 1
+
+// Bounds for the read-only inventory and for nested-repository / liveness walks. They are
+// deliberately small: this helper runs at the start of a run, not in a filesystem audit.
+export const INVENTORY_MAX_ENTRIES = 5000
+export const INVENTORY_MAX_DEPTH = 8
+const NESTED_SCAN_MAX_ENTRIES = 20000
+const NESTED_SCAN_MAX_DEPTH = 12
+const PROC_SCAN_MAX_PIDS = 5000
+const PROC_SCAN_MAX_FDS = 20000
+const LSOF_TIMEOUT_MS = 3000
+
+const RESOLVE_PATH = realpathSync.native ?? realpathSync
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+
+export class LifecycleError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code
+  }
+}
+
+// ---- paths and identity ----
+
+export function normPath(input) {
+  const s = String(input ?? '')
+  const stripped = s.replace(/\/+$/, '')
+  return stripped || (s.startsWith('/') ? '/' : '')
+}
+
+export function containsPath(parent, child) {
+  const p = normPath(parent)
+  const c = normPath(child)
+  if (!p || !c) return false
+  return p === c || (p === '/' ? c.startsWith('/') : c.startsWith(`${p}${sep}`))
+}
+
+export function isHexSha(value) {
+  return typeof value === 'string' && (/^[0-9a-f]{40}$/.test(value) || /^[0-9a-f]{64}$/.test(value))
+}
+
+function pathIdentity(input) {
+  const recorded = normPath(input)
+  const unresolved = (reason) => ({ recorded, real: null, resolved: false, exists: false, isSymlink: false, reason })
+  if (!recorded) return unresolved('an empty path names no tree')
+  if (!isAbsolute(recorded)) return unresolved(`${recorded} is not an absolute path`)
+
+  let isSymlink = false
+  try {
+    isSymlink = lstatSync(recorded).isSymbolicLink()
+  } catch { /* missing is handled below */ }
+  if (isSymlink) return unresolved(`${recorded} is a symbolic link; owned workspaces and resources must be real directories`)
+
+  const trailing = []
+  let cur = recorded
+  for (let depth = 0; depth < 64; depth++) {
+    try {
+      const real = RESOLVE_PATH(cur)
+      return {
+        recorded,
+        real: normPath(trailing.length ? join(real, ...trailing) : real) || '/',
+        resolved: true,
+        exists: trailing.length === 0 && existsSync(recorded),
+        isSymlink: false,
+        reason: null,
+      }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') return unresolved(`cannot resolve ${cur}: ${error?.code ?? error?.message ?? 'unknown error'}`)
+      let dangling = false
+      try { dangling = lstatSync(cur).isSymbolicLink() } catch { dangling = false }
+      if (dangling) return unresolved(`${cur} is a symbolic link whose target does not exist`)
+      const parent = dirname(cur)
+      if (!parent || parent === cur) return unresolved(`no existing ancestor of ${recorded} could be resolved`)
+      trailing.unshift(cur.slice(parent.length + 1))
+      cur = parent
+    }
+  }
+  return unresolved(`gave up resolving ${recorded} after 64 levels`)
+}
+
+// A symlink anywhere inside the managed root would be a second spelling of an owned path.
+// Ancestors outside the root (macOS `/tmp` -> `/private/tmp`) are normal and are handled by
+// comparing real paths; only the final path and segments below the root are rejected.
+function symlinkBelow(root, candidate) {
+  const rootReal = pathIdentity(root)
+  const candidateReal = pathIdentity(candidate)
+  if (!rootReal.resolved || !candidateReal.resolved) return true
+  if (!containsPath(rootReal.real, candidateReal.real)) return true
+  if (candidateReal.real === rootReal.real) return false
+  // Find the original spelling of the root by walking ancestors, then inspect
+  // each lexical child. This permits OS aliases above the root (/var on macOS)
+  // without letting realpath erase an owned-root symlink such as run/alias/cache.
+  let ancestor = resolve(candidate)
+  const tail = []
+  while (pathIdentity(ancestor).real !== rootReal.real) {
+    const parent = dirname(ancestor)
+    if (parent === ancestor) return true
+    tail.unshift(ancestor.slice(parent.length + 1))
+    ancestor = parent
+  }
+  try { if (lstatSync(ancestor).isSymbolicLink()) return true } catch { return true }
+  let cur = ancestor
+  for (const part of tail) {
+    cur = join(cur, part)
+    try {
+      if (lstatSync(cur).isSymbolicLink()) return true
+    } catch (error) {
+      // A path that does not exist yet is not a symlink. Only an unreadable existing
+      // segment is uncertainty, and uncertainty is refused.
+      if (error?.code === 'ENOENT') return false
+      return true
+    }
+  }
+  return false
+}
+
+function fileIdentity(path) {
+  const st = lstatSync(path)
+  return {
+    realPath: pathIdentity(path).real,
+    dev: typeof st.dev === 'number' ? st.dev : null,
+    ino: typeof st.ino === 'number' ? st.ino : null,
+  }
+}
+
+function sameIdentity(recorded, current) {
+  if (!isObject(recorded) || !isObject(current)) return false
+  if (recorded.realPath !== current.realPath) return false
+  for (const key of ['dev', 'ino']) {
+    if (!Number.isSafeInteger(recorded[key]) || recorded[key] !== current[key]) return false
+  }
+  return true
+}
+
+// ---- git ----
+
+function git(dir, args, { timeout = 30000, maxBuffer = 16 * 1024 * 1024 } = {}) {
+  try {
+    const out = execFileSync('git', ['-C', dir, ...args], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout, maxBuffer,
+      // A dry run must not refresh the index merely by reading it. This disables optional
+      // locks/writes; commands that must write (fetch, worktree add/remove) still do.
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' },
+    })
+    return { ok: true, out: String(out).trimEnd() }
+  } catch (error) {
+    return { ok: false, out: String(error?.stdout ?? '').trimEnd(), err: String(error?.stderr ?? error?.message ?? '').trim() }
+  }
+}
+
+function gitToplevel(dir) {
+  const r = git(dir, ['rev-parse', '--show-toplevel'])
+  return r.ok ? r.out : null
+}
+
+function gitCommonDir(dir) {
+  const r = git(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+  return r.ok ? normPath(r.out) : null
+}
+
+function resolveCommit(repo, ref) {
+  if (!nonEmpty(ref)) return null
+  const r = git(repo, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+  return r.ok && isHexSha(r.out) ? r.out : null
+}
+
+function currentHead(dir) {
+  const r = git(dir, ['rev-parse', '--verify', 'HEAD'])
+  return r.ok && isHexSha(r.out) ? r.out : null
+}
+
+function currentBranch(dir) {
+  const r = git(dir, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  return r.ok ? r.out : null
+}
+
+function remoteUrl(dir, name = 'origin') {
+  // Preserve repository identity before Git's insteadOf transport rewrite.
+  const r = git(dir, ['config', '--get', `remote.${name}.url`])
+  return r.ok && nonEmpty(r.out) ? r.out : null
+}
+
+function sameRepoUrl(a, b) {
+  if (!a || !b) return false
+  const clean = (value) => String(value).trim().replace(/^file:\/\//i, '').replace(/\.git$/i, '').replace(/\/+$/, '')
+  const left = clean(a)
+  const right = clean(b)
+  if (left === right) return true
+  // Compare local paths as trees, so `/tmp/x` and `/private/tmp/x` are one remote.
+  try {
+    const l = pathIdentity(left)
+    const r = pathIdentity(right)
+    if (l.resolved && r.resolved) return l.real === r.real
+  } catch { /* fall through to the text compare */ }
+  return false
+}
+
+function slugFromUrl(url) {
+  if (!url) return null
+  const text = String(url).trim().replace(/\.git$/i, '').replace(/\/+$/, '')
+  const match = text.match(/(?:github\.com[:/])([^/]+)\/([^/]+)$/i)
+  return match ? `${match[1]}/${match[2]}` : null
+}
+
+function worktreeList(repo) {
+  const r = git(repo, ['worktree', 'list', '--porcelain'])
+  if (!r.ok) return null
+  return r.out.split('\n').filter((l) => l.startsWith('worktree ')).map((l) => normPath(l.slice('worktree '.length)))
+}
+
+function isRegisteredWorktree(repo, workspace) {
+  const list = worktreeList(repo)
+  if (!list) return false
+  const target = pathIdentity(workspace)
+  if (!target.resolved) return false
+  return list.some((entry) => {
+    const ident = pathIdentity(entry)
+    return ident.resolved && ident.real === target.real
+  })
+}
+
+// ---- plan reading, ownership, and validation ----
+
+export function planPathFor(run) {
+  return join(resolve(run), 'task-plan.json')
+}
+
+export function readPlan(run) {
+  const path = planPathFor(run)
+  if (!existsSync(path)) throw new LifecycleError('plan-missing', `no task plan at ${path}`)
+  let plan
+  try {
+    plan = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    throw new LifecycleError('plan-invalid', `cannot read ${path}: ${error.message}`)
+  }
+  if (!isObject(plan)) throw new LifecycleError('plan-invalid', `${path} is not a JSON object`)
+  if (plan.units !== undefined && !Array.isArray(plan.units)) throw new LifecycleError('plan-invalid', `${path} has a non-array units field`)
+  if (plan.issues !== undefined && !Array.isArray(plan.issues)) throw new LifecycleError('plan-invalid', `${path} has a non-array issues field`)
+  if (Array.isArray(plan.units) && Array.isArray(plan.issues) && JSON.stringify(plan.units) !== JSON.stringify(plan.issues)) {
+    throw new LifecycleError('plan-contradictory', `${path} has both units and issues, and they disagree; the plan does not say which roster owns the run`)
+  }
+  const units = Array.isArray(plan.units) ? plan.units : (Array.isArray(plan.issues) ? plan.issues : [])
+  if (!Array.isArray(units) || units.length === 0) throw new LifecycleError('plan-invalid', `${path} has no units`)
+  return { path, plan, units }
+}
+
+export function unitOf(plan, unitId) {
+  const units = Array.isArray(plan?.units) ? plan.units : (Array.isArray(plan?.issues) ? plan.issues : [])
+  const matches = units.filter((u) => isObject(u) && String(u.id) === String(unitId))
+  if (matches.length === 0) throw new LifecycleError('unit-missing', `unit ${unitId} is not in the plan`)
+  if (matches.length > 1) throw new LifecycleError('unit-duplicate', `unit ${unitId} appears ${matches.length} times in the plan`)
+  return matches[0]
+}
+
+export function planRevisionOf(plan) {
+  if (!Number.isSafeInteger(plan?.planRevision) || plan.planRevision < 0) {
+    throw new LifecycleError('revision-missing', 'the plan has no nonnegative integer planRevision; bind it through update_plan first')
+  }
+  return plan.planRevision
+}
+
+export function requireRevision(plan, revision) {
+  const expected = planRevisionOf(plan)
+  const actual = Number(revision)
+  if (!Number.isSafeInteger(actual) || actual < 0) throw new LifecycleError('revision-invalid', `--revision must be a nonnegative integer: ${JSON.stringify(revision)}`)
+  if (actual !== expected) {
+    throw new LifecycleError('revision-mismatch', `plan revision is ${expected}, not ${actual}; reread the plan and retry with its persisted revision`)
+  }
+  return expected
+}
+
+// The repository a run belongs to: plan.repoRoot when present, else the nearest ancestor
+// holding `.resolve-issues/rush`. The run must actually sit under that root.
+export function repositoryOf(plan, run) {
+  const runReal = pathIdentity(run)
+  if (!runReal.resolved) throw new LifecycleError('run-unresolved', `cannot resolve run directory ${run}: ${runReal.reason}`)
+  if (nonEmpty(plan?.repoRoot) && !isAbsolute(plan.repoRoot)) {
+    throw new LifecycleError('no-owner', `plan.repoRoot must be an absolute path, not ${JSON.stringify(plan.repoRoot)}`)
+  }
+  let repo = nonEmpty(plan?.repoRoot) ? resolve(plan.repoRoot) : null
+  if (!repo) {
+    const marker = `${sep}.resolve-issues${sep}rush${sep}`
+    const at = `${runReal.real}${sep}`.indexOf(marker)
+    if (at >= 0) repo = runReal.real.slice(0, at)
+  }
+  if (!repo) throw new LifecycleError('no-owner', `cannot tell which repository owns ${run}, and the plan records no repoRoot`)
+  const repoReal = pathIdentity(repo)
+  if (!repoReal.resolved) throw new LifecycleError('no-owner', `the repository root ${repo} does not resolve: ${repoReal.reason}`)
+  const runsRoot = pathIdentity(join(repoReal.real, '.resolve-issues', 'rush'))
+  if (!runsRoot.resolved || !containsPath(runsRoot.real, runReal.real) || !containsPath(repoReal.real, runReal.real)) {
+    throw new LifecycleError('no-owner', `${run} is not under ${join(repo, '.resolve-issues', 'rush')}`)
+  }
+  return repoReal.real
+}
+
+export function canonicalRunDir(repo, run) {
+  const runReal = pathIdentity(run)
+  if (!runReal.resolved) throw new LifecycleError('run-unresolved', `cannot resolve run directory ${run}: ${runReal.reason}`)
+  const runsRoot = pathIdentity(join(repo, '.resolve-issues', 'rush'))
+  if (!runsRoot.resolved || !containsPath(runsRoot.real, runReal.real)) {
+    throw new LifecycleError('containment', `${run} is outside ${join(repo, '.resolve-issues', 'rush')}`)
+  }
+  return runReal.real
+}
+
+const lifecycleResources = (unit) => {
+  const fromLifecycle = unit?.lifecycle?.resources
+  if (Array.isArray(fromLifecycle)) return fromLifecycle
+  if (Array.isArray(unit?.resources)) return unit.resources
+  return []
+}
+
+function validateLifecycleShape(lifecycle, unit) {
+  const errors = []
+  if (lifecycle === undefined || lifecycle === null) return errors
+  if (!isObject(lifecycle)) return [{ code: 'lifecycle-invalid', message: `unit ${unit} has a non-object lifecycle` }]
+  if (lifecycle.version !== LIFECYCLE_VERSION) errors.push({ code: 'lifecycle-version', message: `unit ${unit} lifecycle.version must be ${LIFECYCLE_VERSION}` })
+  const ws = lifecycle.workspace
+  if (!isObject(ws)) errors.push({ code: 'lifecycle-workspace', message: `unit ${unit} lifecycle.workspace is missing` })
+  else {
+    if (!WORKSPACE_KINDS.has(ws.kind)) errors.push({ code: 'lifecycle-workspace-kind', message: `unit ${unit} lifecycle.workspace.kind must be worktree or clone` })
+    if (!WORKSPACE_STATES.has(ws.state)) errors.push({ code: 'lifecycle-workspace-state', message: `unit ${unit} lifecycle.workspace.state must be preparing or ready` })
+    if (ws.baseSha !== undefined && !isHexSha(ws.baseSha)) errors.push({ code: 'lifecycle-base-sha', message: `unit ${unit} lifecycle.workspace.baseSha must be an exact 40 or 64 character hex SHA` })
+    if (ws.identity !== undefined && !isObject(ws.identity)) errors.push({ code: 'lifecycle-identity', message: `unit ${unit} lifecycle.workspace.identity must be an object` })
+  }
+  if (lifecycle.resources !== undefined && !Array.isArray(lifecycle.resources)) {
+    errors.push({ code: 'lifecycle-resources', message: `unit ${unit} lifecycle.resources must be an array` })
+  }
+  for (const [index, resource] of (Array.isArray(lifecycle.resources) ? lifecycle.resources : []).entries()) {
+    if (!isObject(resource)) { errors.push({ code: 'lifecycle-resource', message: `unit ${unit} lifecycle.resources[${index}] is not an object` }); continue }
+    if (!nonEmpty(resource.path) || !isAbsolute(resource.path)) errors.push({ code: 'lifecycle-resource-path', message: `unit ${unit} lifecycle.resources[${index}].path must be an absolute path` })
+    if (!RESOURCE_KINDS.has(resource.kind)) errors.push({ code: 'lifecycle-resource-kind', message: `unit ${unit} lifecycle.resources[${index}].kind must be directory, clone, or worktree` })
+    if (!RESOURCE_ROLES.has(resource.role)) errors.push({ code: 'lifecycle-resource-role', message: `unit ${unit} lifecycle.resources[${index}].role must be scratch, tools, or review` })
+    if (resource.disposable !== true) errors.push({ code: 'lifecycle-resource-disposable', message: `unit ${unit} lifecycle.resources[${index}].disposable must be true` })
+    if (!WORKSPACE_STATES.has(resource.state)) errors.push({ code: 'lifecycle-resource-state', message: `unit ${unit} lifecycle.resources[${index}].state must be preparing or ready` })
+    if (resource.identity !== undefined && !isObject(resource.identity)) errors.push({ code: 'lifecycle-resource-identity', message: `unit ${unit} lifecycle.resources[${index}].identity must be an object` })
+  }
+  const cleanup = lifecycle.cleanup
+  if (cleanup !== undefined) {
+    if (!isObject(cleanup)) errors.push({ code: 'lifecycle-cleanup', message: `unit ${unit} lifecycle.cleanup must be an object` })
+    else {
+      if (!CLEANUP_STATES.has(cleanup.state)) errors.push({ code: 'lifecycle-cleanup-state', message: `unit ${unit} lifecycle.cleanup.state must be pending, applying, complete, or retained` })
+      if (cleanup.headSha !== undefined && !isHexSha(cleanup.headSha)) errors.push({ code: 'lifecycle-cleanup-head', message: `unit ${unit} lifecycle.cleanup.headSha must be an exact 40 or 64 character hex SHA` })
+    }
+  }
+  return errors
+}
+
+// Validate ownership before any mutation. This runs for prepare and cleanup, and it only
+// reads the plan and the filesystem.
+export function validateUnit({ repo, run, plan, unit }) {
+  const errors = []
+  const unitId = String(unit?.id ?? '')
+  if (!isObject(unit)) throw new LifecycleError('unit-missing', 'unit is not an object')
+  if (!nonEmpty(unitId) || unitId.trim() !== unitId || /[\x00-\x1f\x7f]/.test(unitId) || unitId === '.' || unitId === '..' || unitId.includes('/') || unitId.includes('\\')) {
+    errors.push({ code: 'unit-id', message: `unit id ${JSON.stringify(unitId)} cannot name a workspace directory` })
+  }
+  if (!nonEmpty(unit.workspace) || !isAbsolute(unit.workspace)) {
+    errors.push({ code: 'workspace-missing', message: `unit ${unitId} has no absolute unit.workspace; plan the workspace before prepare` })
+  }
+  if (!nonEmpty(unit.branch)) errors.push({ code: 'branch-missing', message: `unit ${unitId} has no unit.branch` })
+  if (!nonEmpty(unit.base)) errors.push({ code: 'base-missing', message: `unit ${unitId} has no unit.base` })
+  errors.push(...validateLifecycleShape(unit.lifecycle, unitId))
+
+  const runDir = canonicalRunDir(repo, run)
+  const runIdent = pathIdentity(runDir)
+  if (!runIdent.resolved) {
+    errors.push({ code: 'run-unresolved', message: `run directory ${runDir} cannot be resolved: ${runIdent.reason}` })
+    return { errors, runDir }
+  }
+  const repoIdent = pathIdentity(repo)
+  if (!repoIdent.resolved) {
+    errors.push({ code: 'repo-unresolved', message: `repository ${repo} cannot be resolved: ${repoIdent.reason}` })
+    return { errors, runDir }
+  }
+
+  const allUnits = Array.isArray(plan?.units) ? plan.units : (Array.isArray(plan?.issues) ? plan.issues : [])
+  const seen = new Map()
+  const claim = (path, owner, role) => {
+    if (!nonEmpty(path) || !isAbsolute(path)) return
+    if (normPath(path) !== resolve(path)) {
+      errors.push({ code: 'path-spelling', message: `${role} ${path} must use a canonical spelling without dot-segment traversal` })
+      return
+    }
+    const ident = pathIdentity(path)
+    if (!ident.resolved) {
+      errors.push({ code: 'path-unresolved', message: `${role} ${path} cannot be resolved: ${ident.reason}` })
+      return
+    }
+    if (ident.real === repoIdent.real) errors.push({ code: 'project-root', message: `${role} ${path} is the project root; an owned workspace is not the repository checkout` })
+    if (containsPath(ident.real, repoIdent.real) && ident.real !== repoIdent.real) errors.push({ code: 'project-root', message: `${role} ${path} contains the project root` })
+    if (containsPath(repoIdent.real, ident.real) && ident.real !== repoIdent.real && !containsPath(runIdent.real, ident.real)) {
+      errors.push({ code: 'project-root', message: `${role} ${path} is inside the project checkout but outside the run directory` })
+    }
+    if (!containsPath(runIdent.real, ident.real)) errors.push({ code: 'containment', message: `${role} ${path} is outside the canonical run directory ${runDir}` })
+    if (ident.real === runIdent.real) errors.push({ code: 'broad-parent', message: `${role} ${path} is the run directory; only a unit's own workspace or resource may be removed` })
+    if (ident.real === '/' || containsPath(ident.real, runIdent.real)) errors.push({ code: 'broad-parent', message: `${role} ${path} contains the run directory or the filesystem root` })
+    if (symlinkBelow(runDir, path)) errors.push({ code: 'symlink', message: `${role} ${path} is a symbolic link, or passes through one below ${runDir}` })
+    const key = ident.real
+    for (const [claimed, claimant] of seen) {
+      if (claimant.owner !== owner && (containsPath(claimed, key) || containsPath(key, claimed))) {
+        errors.push({ code: 'overlapping-path', message: `${role} ${path} overlaps ${claimant.owner}'s ${claimed}` })
+      }
+    }
+    if (seen.has(key)) {
+      errors.push({ code: 'duplicate-path', message: `${role} ${path} is claimed by both ${seen.get(key).owner} and ${owner}` })
+    } else {
+      seen.set(key, { owner, role })
+    }
+  }
+
+  // Cross-unit references: every unit's workspace and resources are collected, so two units
+  // cannot claim one tree and a resource cannot alias another unit's workspace.
+  for (const other of allUnits) {
+    if (!isObject(other)) continue
+    if (nonEmpty(other.workspace) && isAbsolute(other.workspace)) claim(other.workspace, `unit ${other.id}`, 'workspace')
+    for (const resource of lifecycleResources(other)) {
+      if (isObject(resource) && nonEmpty(resource.path) && isAbsolute(resource.path)) claim(resource.path, `unit ${other.id}`, `resource:${resource.role ?? 'unknown'}`)
+    }
+  }
+
+  if (nonEmpty(unit.workspace) && isAbsolute(unit.workspace)) {
+    const ws = pathIdentity(unit.workspace)
+    if (ws.resolved) {
+      const expectedRoot = pathIdentity(join(runDir, 'units', String(unit.id)))
+      if (!expectedRoot.resolved || expectedRoot.real !== ws.real) {
+        errors.push({ code: 'workspace-layout', message: `unit ${unitId} workspace ${unit.workspace} is not under ${join(runDir, 'units', String(unit.id))}` })
+      }
+      const runroot = pathIdentity(runDir)
+      if (runroot.resolved && ws.real === runroot.real) errors.push({ code: 'workspace-layout', message: `unit ${unitId} workspace is the run directory` })
+    }
+    if (existsSync(unit.workspace) && lstatSync(unit.workspace).isSymbolicLink()) {
+      errors.push({ code: 'symlink', message: `unit ${unitId} workspace ${unit.workspace} is a symbolic link` })
+    }
+  }
+
+  const allowedResourcePrefixes = [
+    pathIdentity(join(runDir, 'resources', String(unit.id))),
+    pathIdentity(join(runDir, 'reviews', String(unit.id))),
+    pathIdentity(unit.workspace),
+  ].filter((ident) => ident.resolved).map((ident) => ident.real)
+  for (const resource of lifecycleResources(unit)) {
+    if (!isObject(resource) || !nonEmpty(resource.path) || !isAbsolute(resource.path)) continue
+    const ident = pathIdentity(resource.path)
+    if (!ident.resolved) continue
+    const underWorkspace = nonEmpty(unit.workspace) && containsPath(pathIdentity(unit.workspace).real, ident.real) && ident.real !== pathIdentity(unit.workspace).real
+    const underOwnedRoot = allowedResourcePrefixes.some((prefix) => containsPath(prefix, ident.real) && ident.real !== prefix)
+    const reviewRoot = pathIdentity(join(runDir, 'reviews', String(unit.id))).real
+    const reviewClone = pathIdentity(join(runDir, 'reviews', String(unit.id), 'clone')).real
+    if ((!underWorkspace && !underOwnedRoot) || (containsPath(reviewRoot, ident.real) && ident.real !== reviewClone)) {
+      errors.push({ code: 'resource-layout', message: `unit ${unitId} resource ${resource.path} is not a workspace child, not under ${join(runDir, 'resources', String(unit.id))}, and not under ${join(runDir, 'reviews', String(unit.id))}` })
+    }
+  }
+
+  return { errors, runDir }
+}
+
+function assertValid(result) {
+  if (result.errors.length) {
+    const error = new LifecycleError(result.errors[0].code, result.errors.map((e) => e.message).join('; '))
+    error.details = result.errors
+    throw error
+  }
+}
+
+// ---- locking ----
+
+function safeName(value) {
+  return encodeURIComponent(String(value))
+}
+
+function acquireLock(runDir, unitId) {
+  const dir = join(runDir, '.workspace-locks')
+  if (symlinkBelow(runDir, dir)) throw new LifecycleError('symlink', 'workspace lock directory passes through a symbolic link')
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, `${safeName(unitId)}.lock`)
+  try {
+    mkdirSync(path)
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new LifecycleError('locked', `workspace ${unitId} is locked at ${path}; another prepare or cleanup owns it. The lock is never reclaimed by age`)
+    }
+    throw error
+  }
+  const owner = join(path, 'owner.json')
+  try {
+    writeFileSync(owner, `${JSON.stringify({ pid: process.pid, unit: String(unitId), at: new Date().toISOString() }, null, 2)}\n`)
+  } catch { /* the directory itself is the lock */ }
+  let released = false
+  return {
+    path,
+    release() {
+      if (released) return
+      released = true
+      try { unlinkSync(owner) } catch { /* may be absent */ }
+      try { rmSync(path, { recursive: true, force: true }) } catch { /* a lock left behind is visible in recover */ }
+      // Remove the empty lock directory too, so a read-only dry run after a completed
+      // prepare leaves no lock residue behind.
+      try { rmdirSync(dir) } catch { /* another unit's lock is still there */ }
+    },
+  }
+}
+
+// ---- workspace creation ----
+
+function defaultKind(unit, repo) {
+  const planned = unit?.lifecycle?.workspace?.kind ?? unit?.workspaceKind
+  if (planned !== undefined) return planned
+  return gitToplevel(repo) ? 'worktree' : 'clone'
+}
+
+function baseShaFor(repo, unit) {
+  const planned = unit?.lifecycle?.workspace?.baseSha
+  if (planned !== undefined) {
+    if (!isHexSha(planned)) throw new LifecycleError('lifecycle-base-sha', `unit ${unit.id} lifecycle.workspace.baseSha is not an exact 40 or 64 character hex SHA`)
+    const exists = git(repo, ['cat-file', '-e', `${planned}^{commit}`]).ok
+    if (!exists) throw new LifecycleError('base-missing', `unit ${unit.id} baseSha ${planned} is not a commit in ${repo}`)
+    return planned
+  }
+  const sha = resolveCommit(repo, unit.base)
+  if (!sha) throw new LifecycleError('base-missing', `unit ${unit.id} base ${JSON.stringify(unit.base)} does not resolve to a commit in ${repo}`)
+  return sha
+}
+
+function createWorktree({ repo, workspace, branch, baseSha }) {
+  const branchExists = git(repo, ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]).ok
+  if (branchExists && resolveCommit(repo, `refs/heads/${branch}`) !== baseSha) {
+    throw new LifecycleError('base-mismatch', `existing branch ${branch} is not at the planned base ${baseSha}`)
+  }
+  const args = ['worktree', 'add']
+  if (branchExists) args.push(workspace, branch)
+  else args.push('-b', branch, workspace, baseSha)
+  const result = git(repo, args)
+  if (!result.ok) throw new LifecycleError('worktree-create', `git worktree add failed for ${workspace}: ${result.err || result.out}`)
+}
+
+function createClone({ repo, workspace, branch, baseSha, source = repo }) {
+  // Fetch only the prepared commit from the local source. Cloning that source wholesale
+  // would relabel its private branches as origin/* when the origin URL is changed.
+  const origin = remoteUrl(repo, 'origin')
+  if (!origin) throw new LifecycleError('clone-origin', 'the repository has no recorded origin')
+  const existing = resolveCommit(repo, `refs/heads/${branch}`)
+  if (existing && existing !== baseSha) throw new LifecycleError('base-mismatch', `existing branch ${branch} is not at the planned base ${baseSha}`)
+  const init = git(dirname(workspace), ['init', '--quiet', workspace])
+  if (!init.ok) throw new LifecycleError('clone-create', init.err)
+  for (const args of [
+    ['remote', 'add', 'origin', origin],
+    ['fetch', '--quiet', '--no-tags', '--no-write-fetch-head', source, baseSha],
+    ['checkout', '--quiet', '-b', branch, baseSha],
+  ]) {
+    const result = git(workspace, args)
+    if (!result.ok) throw new LifecycleError('clone-create', `${workspace}: ${result.err || result.out}`)
+  }
+}
+
+function workspaceKindOf(path) {
+  const dotGit = join(path, '.git')
+  if (!existsSync(dotGit)) return null
+  try {
+    return lstatSync(dotGit).isFile() ? 'worktree' : 'clone'
+  } catch {
+    return null
+  }
+}
+
+function workspaceIdentity(workspace) {
+  const ident = fileIdentity(workspace)
+  return {
+    ...ident,
+    gitCommonDir: gitCommonDir(workspace),
+    headSha: currentHead(workspace),
+  }
+}
+
+function resourceIdentity(path) {
+  const ident = fileIdentity(path)
+  const kind = existsSync(join(path, '.git')) ? workspaceKindOf(path) : 'directory'
+  return kind && kind !== 'directory'
+    ? { ...ident, gitCommonDir: gitCommonDir(path) }
+    : ident
+}
+
+function ensureDirectory(path) {
+  if (existsSync(path)) {
+    if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isDirectory()) {
+      throw new LifecycleError('resource-exists', `${path} exists but is not a real directory`)
+    }
+    return
+  }
+  mkdirSync(path, { recursive: true })
+}
+
+function createResources({ unit, repo, workspace }) {
+  const resources = []
+  for (const planned of lifecycleResources(unit)) {
+    if (!isObject(planned)) continue
+    const path = planned.path
+    if (planned.state === 'ready' && !existsSync(path)) {
+      throw new LifecycleError('resource-missing', `unit ${unit.id} recorded ready resource ${path} is missing; not recreating over a lost tree`)
+    }
+    if (existsSync(path)) {
+      if (lstatSync(path).isSymbolicLink()) throw new LifecycleError('symlink', `resource ${path} is a symbolic link`)
+      if (planned.state === 'ready') {
+        const current = resourceIdentity(path)
+        if (!sameIdentity(planned.identity, current) || (planned.identity.gitCommonDir && planned.identity.gitCommonDir !== current.gitCommonDir)) {
+          throw new LifecycleError('resource-identity', `resource ${path} does not match its recorded identity; refusing to adopt a replacement tree`)
+        }
+      }
+    } else {
+      mkdirSync(dirname(path), { recursive: true })
+      if (planned.kind === 'clone') {
+        createClone({ repo, source: workspace, workspace: path, branch: `review-${safeName(unit.id)}`, baseSha: currentHead(workspace) })
+      } else if (planned.kind === 'worktree') {
+        const created = git(repo, ['worktree', 'add', '--quiet', '--detach', path, currentHead(workspace)])
+        if (!created.ok) throw new LifecycleError('resource-create', created.err)
+      } else ensureDirectory(path)
+    }
+    const actualKind = workspaceKindOf(path) ?? 'directory'
+    if (actualKind !== planned.kind) throw new LifecycleError('resource-kind', `resource ${path} is ${actualKind}, not ${planned.kind}; prepare cannot mark an empty directory as a clone`)
+    const identity = resourceIdentity(path)
+    resources.push({
+      ...planned,
+      path: normPath(path),
+      kind: RESOURCE_KINDS.has(planned.kind) ? planned.kind : 'directory',
+      role: RESOURCE_ROLES.has(planned.role) ? planned.role : 'scratch',
+      disposable: true,
+      state: 'ready',
+      identity,
+    })
+  }
+  // A review clone is conventionally `reviews/<unit>` even when it is not listed in the
+  // planned resources: older plans recorded it only by path. It is not adopted or created
+  // here; it is simply never treated as a workspace.
+  return resources
+}
+
+function cleanupFor(unit, headSha) {
+  const previous = isObject(unit?.lifecycle?.cleanup) ? unit.lifecycle.cleanup : {}
+  return {
+    ...previous,
+    state: previous.state && CLEANUP_STATES.has(previous.state) ? previous.state : 'pending',
+    headSha: isHexSha(previous.headSha) ? previous.headSha : headSha,
+    ...(previous.reason ? { reason: previous.reason } : {}),
+  }
+}
+
+export function prepare({
+  run, unit: unitId, revision, apply = false, kind = null,
+}) {
+  run = resolve(run)
+  const first = readPlan(run)
+  const repo = repositoryOf(first.plan, run)
+  requireRevision(first.plan, revision)
+  const unit = unitOf(first.plan, unitId)
+  assertValid(validateUnit({ repo, run, plan: first.plan, unit }))
+  const resolvedKind = kind ?? defaultKind(unit, repo)
+  if (!WORKSPACE_KINDS.has(resolvedKind)) throw new LifecycleError('kind-invalid', `--kind must be worktree or clone, not ${JSON.stringify(kind)}`)
+  if (unit.lifecycle?.workspace?.kind && resolvedKind !== unit.lifecycle.workspace.kind) {
+    throw new LifecycleError('kind-mismatch', `the plan records ${unit.lifecycle.workspace.kind}, not ${resolvedKind}`)
+  }
+  const baseSha = baseShaFor(repo, unit)
+  const workspace = normPath(unit.workspace)
+
+  if (!apply) {
+    return {
+      version: 1,
+      command: 'prepare',
+      ok: true,
+      applied: false,
+      action: existsSync(workspace) ? 'verify' : 'create',
+      repo,
+      run: canonicalRunDir(repo, run),
+      unit: String(unitId),
+      revision: planRevisionOf(first.plan),
+      workspace: {
+        path: workspace,
+        kind: resolvedKind,
+        state: existsSync(workspace) ? 'ready' : 'preparing',
+        baseSha,
+        identity: existsSync(workspace) ? workspaceIdentity(workspace) : null,
+        exists: existsSync(workspace),
+      },
+      resources: lifecycleResources(unit).map((r) => ({
+        path: r.path, kind: r.kind ?? 'directory', role: r.role ?? 'scratch', disposable: true,
+        state: existsSync(r.path) ? 'ready' : 'preparing', identity: existsSync(r.path) ? resourceIdentity(r.path) : null,
+        exists: existsSync(r.path),
+      })),
+      nextLifecycle: {
+        version: 1,
+        workspace: { path: workspace, kind: resolvedKind, state: 'preparing', baseSha, identity: null },
+        resources: lifecycleResources(unit).map((r) => ({ ...r, state: 'preparing', identity: null })),
+        cleanup: cleanupFor(unit, existsSync(workspace) ? currentHead(workspace) : null),
+      },
+      checks: [{ name: 'plan', ok: true, detail: `revision ${planRevisionOf(first.plan)}` }],
+      errors: [],
+    }
+  }
+
+  const runDir = canonicalRunDir(repo, run)
+  const lock = acquireLock(runDir, unitId)
+  try {
+    // Re-read under the lock: a concurrent plan transition or another prepare must not be
+    // overwritten by a decision made against a stale revision.
+    const current = readPlan(run)
+    requireRevision(current.plan, revision)
+    const freshUnit = unitOf(current.plan, unitId)
+    assertValid(validateUnit({ repo, run, plan: current.plan, unit: freshUnit }))
+    if (JSON.stringify(current.plan) !== JSON.stringify(first.plan)) throw new LifecycleError('revision-mismatch', 'plan changed before prepare acquired its lock')
+    const freshBase = baseShaFor(repo, freshUnit)
+    if (freshBase !== baseSha) throw new LifecycleError('revision-mismatch', `unit ${unitId} base changed from ${baseSha} to ${freshBase}; reread the plan`)
+    if (freshUnit.lifecycle?.cleanup?.state === 'complete' && existsSync(workspace)) {
+      throw new LifecycleError('cleanup-final', `unit ${unitId} is recorded complete, but its workspace still exists; the plan and the disk disagree`)
+    }
+
+    let existing = existsSync(workspace)
+    // An empty directory at the planned path is not a used tree: the coordinator planned the
+    // path, and prepare is the operation that fills it. Only an empty directory is replaced;
+    // anything else must already be the recorded workspace.
+    if (existing && !lstatSync(workspace).isDirectory()) {
+      throw new LifecycleError('workspace-invalid', `planned workspace ${workspace} exists but is not a directory`)
+    }
+    if (existing && readdirSync(workspace).length === 0 && !(freshUnit.lifecycle?.workspace?.state === 'ready')) {
+      rmdirSync(workspace)
+      existing = false
+    }
+    let action = 'verify'
+    if (existing) {
+      if (lstatSync(workspace).isSymbolicLink()) throw new LifecycleError('symlink', `workspace ${workspace} is a symbolic link`)
+      if (!freshUnit.lifecycle) throw new LifecycleError('unowned-tree', `workspace ${workspace} exists but the plan records no lifecycle for unit ${unitId}; refusing to adopt it`)
+      if (freshUnit.lifecycle.workspace?.state === 'ready' && !existsSync(join(workspace, '.git'))) {
+        throw new LifecycleError('workspace-missing-git', `workspace ${workspace} is recorded ready but is not a Git workspace`)
+      }
+      const actualKind = workspaceKindOf(workspace)
+      if (!actualKind) throw new LifecycleError('workspace-invalid', `workspace ${workspace} exists but is not a Git worktree or clone`)
+      if (actualKind !== resolvedKind) throw new LifecycleError('kind-mismatch', `workspace ${workspace} is a ${actualKind}, not the recorded ${resolvedKind}`)
+      const branch = currentBranch(workspace)
+      if (branch !== freshUnit.branch) throw new LifecycleError('branch-mismatch', `workspace ${workspace} is on ${branch ?? 'an unknown branch'}, not ${freshUnit.branch}`)
+      if (!git(workspace, ['merge-base', '--is-ancestor', freshBase, 'HEAD']).ok && currentHead(workspace) !== freshBase) {
+        throw new LifecycleError('base-mismatch', `workspace ${workspace} does not contain its recorded base ${freshBase}; refusing to reset a used tree`)
+      }
+      const currentIdentity = workspaceIdentity(workspace)
+      if (freshUnit.lifecycle.workspace?.state === 'ready' && (!sameIdentity(freshUnit.lifecycle.workspace.identity, currentIdentity)
+        || freshUnit.lifecycle.workspace.identity.gitCommonDir !== currentIdentity.gitCommonDir)) {
+        throw new LifecycleError('workspace-identity', `workspace ${workspace} does not match its recorded identity; refusing to adopt a replacement tree`)
+      }
+    } else {
+      if (freshUnit.lifecycle?.workspace?.state === 'ready') {
+        throw new LifecycleError('workspace-lost', `unit ${unitId} records a ready workspace at ${workspace}, but it is missing; not recreating it`)
+      }
+      if (freshUnit.lifecycle?.cleanup?.state === 'complete' || freshUnit.lifecycle?.cleanup?.state === 'retained') {
+        throw new LifecycleError('cleanup-final', `unit ${unitId} is already ${freshUnit.lifecycle.cleanup.state}; prepare will not recreate its workspace`)
+      }
+      action = 'create'
+      mkdirSync(dirname(workspace), { recursive: true })
+      try {
+        if (resolvedKind === 'worktree') createWorktree({ repo, workspace, branch: freshUnit.branch, baseSha: freshBase })
+        else createClone({ repo, workspace, branch: freshUnit.branch, baseSha: freshBase })
+      } catch (error) {
+        // A Pi sandbox can deny linked `.git` files. If the plan did not choose the kind and
+        // `git worktree add` failed before leaving a tree we can identify, fall back to an
+        // independent clone. Never fall back over an existing tree.
+        const branchExistsInRepo = git(repo, ['show-ref', '--verify', '--quiet', `refs/heads/${freshUnit.branch}`]).ok
+        const absentOrEmpty = !existsSync(workspace) || (lstatSync(workspace).isDirectory() && readdirSync(workspace).length === 0)
+        if (resolvedKind === 'worktree' && !kind && !freshUnit.lifecycle?.workspace?.kind && !branchExistsInRepo && absentOrEmpty) {
+          if (existsSync(workspace)) rmdirSync(workspace)
+          createClone({ repo, workspace, branch: freshUnit.branch, baseSha: freshBase })
+        } else {
+          throw error
+        }
+      }
+    }
+
+    const actualKind = workspaceKindOf(workspace)
+    const identity = workspaceIdentity(workspace)
+    if (!identity.headSha) throw new LifecycleError('workspace-invalid', `workspace ${workspace} has no readable HEAD`)
+    const resources = createResources({ unit: freshUnit, repo, workspace })
+    const lifecycle = {
+      ...freshUnit.lifecycle,
+      version: LIFECYCLE_VERSION,
+      workspace: {
+        path: workspace,
+        kind: actualKind,
+        state: 'ready',
+        baseSha: freshBase,
+        identity,
+      },
+      resources,
+      cleanup: cleanupFor(freshUnit, identity.headSha),
+    }
+    return {
+      version: 1,
+      command: 'prepare',
+      ok: true,
+      applied: true,
+      action,
+      repo,
+      run: runDir,
+      unit: String(unitId),
+      revision: planRevisionOf(current.plan),
+      workspace: { ...lifecycle.workspace, exists: true },
+      resources: resources.map((r) => ({ ...r, exists: true })),
+      lifecycle,
+      nextLifecycle: lifecycle,
+      checks: [
+        { name: 'plan', ok: true, detail: `revision ${planRevisionOf(current.plan)}` },
+        { name: 'workspace', ok: true, detail: `${actualKind} ${workspace}` },
+        { name: 'base', ok: true, detail: freshBase },
+      ],
+      errors: [],
+    }
+  } finally {
+    lock.release()
+  }
+}
+
+// ---- liveness and process use ----
+
+// Linux can return EACCES when a task exits during a /proc read. Only signal-0 ESRCH
+// proves that exact PID is gone and permits one fresh scan. All other uncertainty
+// retains the environment (ADR 0023).
+function readProcLink(path, pid) {
+  try { return { link: readlinkSync(path) } } catch (error) {
+    const errno = error?.code ?? 'unknown'
+    if (errno === 'ENOENT' || errno === 'ESRCH') return { link: null }
+    return { failure: { path, operation: 'readlink', errno, pid } }
+  }
+}
+
+function probePid(pid) {
+  const operation = `process.kill(${pid}, 0)`
+  const numeric = Number(pid)
+  if (!Number.isSafeInteger(numeric) || numeric <= 0) return { exited: false, operation, errno: 'EINVAL' }
+  try {
+    process.kill(numeric, 0)
+    return { exited: false, operation, errno: null }
+  } catch (error) {
+    const errno = error?.code ?? 'unknown'
+    return { exited: errno === 'ESRCH', operation, errno }
+  }
+}
+
+// Only an EACCES read attributed to one exact pid may be probed. A failure without a pid
+// (the /proc listing itself) or with another errno is a refusal with no escape hatch.
+function procRefusal(failure) {
+  return {
+    refusal: failure,
+    ...(failure.errno === 'EACCES' && failure.pid ? { probe: String(failure.pid) } : {}),
+  }
+}
+
+// One complete, bounded pass over /proc. Every call builds its own pid set, enumeration and
+// counters, so a restart can never inherit the abandoned pass's budget or findings.
+function scanProcOnce(targets) {
+  const pids = new Set()
+  let fdsSeen = 0
+  let procCount = 0
+  let names = []
+  try { names = readdirSync('/proc') } catch (error) {
+    return { refusal: { path: '/proc', operation: 'readdir', errno: error?.code ?? 'unknown' } }
+  }
+  const overPids = () => ({ refusal: { path: '/proc', operation: 'enumerate-pids', errno: 'PROC_SCAN_MAX_PIDS', limit: PROC_SCAN_MAX_PIDS } })
+  const overFds = (name) => ({ refusal: { path: `/proc/${name}/fd`, operation: 'enumerate-fds', errno: 'PROC_SCAN_MAX_FDS', limit: PROC_SCAN_MAX_FDS } })
+  for (const name of names) {
+    if (!/^\d+$/.test(name)) continue
+    if (procCount++ >= PROC_SCAN_MAX_PIDS) return overPids()
+    const cwd = readProcLink(`/proc/${name}/cwd`, name)
+    if (cwd.failure) return procRefusal(cwd.failure)
+    if (cwd.link && targets.some((target) => containsPath(target, cwd.link))) { pids.add(name); continue }
+    let fds = []
+    try { fds = readdirSync(`/proc/${name}/fd`) } catch (error) {
+      const errno = error?.code ?? 'unknown'
+      if (errno === 'ENOENT' || errno === 'ESRCH') continue
+      return procRefusal({ path: `/proc/${name}/fd`, operation: 'readdir', errno, pid: name })
+    }
+    for (const fd of fds) {
+      if (fdsSeen++ >= PROC_SCAN_MAX_FDS) return overFds(name)
+      const link = readProcLink(`/proc/${name}/fd/${fd}`, name)
+      if (link.failure) return procRefusal(link.failure)
+      if (link.link && targets.some((target) => containsPath(target, link.link))) { pids.add(name); break }
+    }
+    if (fdsSeen > PROC_SCAN_MAX_FDS) return overFds(name)
+  }
+  return { pids: [...pids] }
+}
+
+function linuxProcessesUsing(paths, onUncertain) {
+  if (!existsSync('/proc')) return null
+  const targets = paths.map((p) => pathIdentity(p)).filter((i) => i.resolved).map((i) => i.real)
+  if (!targets.length) return []
+  let restarts = 0
+  for (;;) {
+    const scan = scanProcOnce(targets)
+    if (scan.pids) return scan.pids
+    if (!scan.probe || restarts > 0) {
+      onUncertain?.(scan.refusal)
+      return 'unreadable'
+    }
+    const probe = probePid(scan.probe)
+    if (!probe.exited) {
+      onUncertain?.({ ...scan.refusal, probe })
+      return 'unreadable'
+    }
+    restarts += 1
+  }
+}
+
+function lsofProcessesUsing(paths) {
+  try {
+    // Enumerate open files once, bounded by time and output. No recursive lsof +D walk.
+    const out = execFileSync('lsof', ['-nP', '-Fn'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: LSOF_TIMEOUT_MS, maxBuffer: 32 * 1024 * 1024,
+    })
+    const targets = paths.map((p) => pathIdentity(p)).filter((i) => i.resolved).map((i) => i.real)
+    const pids = new Set()
+    let pid = null
+    for (const line of String(out).split('\n')) {
+      if (line.startsWith('p')) pid = line.slice(1).trim()
+      else if (line.startsWith('n') && pid) {
+        const cwd = line.slice(1)
+        if (targets.some((target) => containsPath(target, cwd))) pids.add(pid)
+      }
+    }
+    return [...pids]
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.status === 127) return 'unavailable'
+    if (error?.status === 1 && !String(error?.stdout ?? '').trim()) return []
+    return 'unreadable'
+  }
+}
+
+export function liveProcessesUsing(paths, options = {}) {
+  const onUncertain = typeof options?.onUncertain === 'function' ? options.onUncertain : null
+  const linux = linuxProcessesUsing(paths, onUncertain)
+  if (linux !== null) return linux
+  return lsofProcessesUsing(paths)
+}
+
+// ---- unpublished work, evidence, nested repos ----
+
+function hasRecordedWorker(plan, unit) {
+  const rosters = [...(plan?.units ?? []), ...(plan?.issues ?? [])]
+  const rows = [...rosters, ...(Array.isArray(plan?.fleet) ? plan.fleet : [])]
+  if (Array.isArray(plan?.workers)) rows.push(...plan.workers)
+  if (isObject(plan?.workers)) rows.push(...Object.values(plan.workers))
+  const paths = [unit.workspace, ...lifecycleResources(unit).map(r => r.path)].map(p => pathIdentity(p).real).filter(Boolean)
+  return rows.filter(row => {
+    if (!isObject(row) || row.worker == null || row.worker === '') return false
+    const owner = row.unit ?? row.unitId ?? (rosters.includes(row) ? row.id : null)
+    const claims = [row.workspace, ...lifecycleResources(row).map(r => r.path)].filter(nonEmpty).map(p => pathIdentity(p).real).filter(Boolean)
+    if (claims.some(p => paths.some(q => containsPath(p, q) || containsPath(q, p)))) return true
+    // A handle without an owner or path is ambiguous, not an unrelated worker.
+    return owner == null || String(owner) === String(unit.id)
+  }).map(row => String(row.worker))
+}
+
+function statusLines(workspace) {
+  const r = git(workspace, ['status', '--porcelain=v1', '--ignored=matching'])
+  if (!r.ok) return null
+  return r.out.split('\n').map((l) => l.replace(/\s+$/, '')).filter(Boolean)
+}
+
+function interruptedGitState(workspace) {
+  const checks = ['rebase-merge', 'rebase-apply', 'MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'BISECT_LOG', 'sequencer']
+  const found = []
+  const dir = git(workspace, ['rev-parse', '--path-format=absolute', '--git-dir'])
+  if (dir.ok && existsSync(join(dir.out, 'locked'))) found.push('locked')
+  for (const name of checks) {
+    const r = git(workspace, ['rev-parse', '--path-format=absolute', '--git-path', name])
+    if (r.ok && existsSync(r.out)) found.push(name)
+  }
+  return found
+}
+
+function nestedRepositories(workspace, skipPaths) {
+  const root = pathIdentity(workspace)
+  if (!root.resolved) return { found: [], truncated: false }
+  const skip = new Set(skipPaths.map((p) => pathIdentity(p)).filter((i) => i.resolved).map((i) => i.real))
+  const found = []
+  let seen = 0
+  let truncated = false
+  const walk = (dir, depth) => {
+    if (truncated) return
+    if (depth > NESTED_SCAN_MAX_DEPTH) { truncated = true; return }
+    let entries = []
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { truncated = true; return }
+    for (const entry of entries) {
+      if (seen++ >= NESTED_SCAN_MAX_ENTRIES) { truncated = true; return }
+      const path = join(dir, entry.name)
+      const ident = pathIdentity(path)
+      if (ident.resolved && skip.has(ident.real)) continue
+      if (entry.name === '.git' && depth === 0) continue
+      if (entry.name === '.git' && depth > 0) { found.push(path); continue }
+      if (entry.isDirectory() && existsSync(join(path, 'HEAD')) && existsSync(join(path, 'objects')) && existsSync(join(path, 'refs'))) { found.push(path); continue }
+      if (!entry.isDirectory()) continue
+      walk(path, depth + 1)
+    }
+  }
+  walk(root.real, 0)
+  return { found, truncated }
+}
+
+function evidenceEntries(unit) {
+  const declarations = [unit?.lifecycle?.evidence, unit?.evidence, unit?.lifecycle?.cleanup?.evidence, unit?.requiredEvidence, unit?.lifecycle?.requiredEvidence].filter(v => v !== undefined)
+  const entries = []
+  for (const raw of declarations) {
+    if (!Array.isArray(raw)) return null
+    for (const entry of raw) {
+      if (typeof entry === 'string' && nonEmpty(entry)) entries.push({ path: entry, required: true })
+      else if (isObject(entry) && nonEmpty(entry.path) && (entry.required === undefined || typeof entry.required === 'boolean')) entries.push({ path: entry.path, required: entry.required !== false })
+      else return null
+    }
+  }
+  return entries
+}
+
+function evidenceReport(unit, workspace) {
+  const roots = [workspace, ...lifecycleResources(unit).map(r => r.path)].map(pathIdentity)
+  const entries = evidenceEntries(unit)
+  if (entries === null) return [{ path: '(invalid evidence declaration)', required: true, location: 'unresolved', preserved: false, exists: false }]
+  return entries.map((entry) => {
+    const ident = pathIdentity(entry.path)
+    const location = !ident.resolved ? 'unresolved'
+      : roots.some(root => root.resolved && containsPath(root.real, ident.real)) ? 'inside-removal-root' : 'outside'
+    return { ...entry, location, preserved: location === 'outside' && ident.exists, exists: ident.exists }
+  })
+}
+
+function targetBranchOf(plan, unit) {
+  const candidates = [plan?.targetBranch, plan?.target]
+  for (const value of candidates) {
+    if (!nonEmpty(value) || isHexSha(value)) continue
+    let name = String(value).trim()
+    name = name.replace(/^refs\/remotes\/origin\//, '').replace(/^refs\/heads\//, '').replace(/^origin\//, '').replace(/^refs\/remotes\//, '')
+    if (name && name !== 'HEAD') return name
+  }
+  return null
+}
+
+// Read the actual origin's current heads/tags. Neither local refs/remotes nor the
+// coordinator's branches are publication authority. Fetch objects only on apply;
+// do not overwrite refs or their reflogs while deciding what work must survive.
+function freshTarget({ workspace, target, apply, origin }) {
+  const remote = git(workspace, ['ls-remote', '--heads', '--tags', origin], { timeout: 60000 })
+  if (!remote.ok) return { ok: false, reason: `cannot read fresh origin refs: ${remote.err || remote.out}` }
+  const refs = new Map()
+  for (const line of remote.out.split('\n').filter(Boolean)) {
+    const [sha, ref] = line.split(/\s+/)
+    if (!isHexSha(sha) || !ref?.startsWith('refs/')) return { ok: false, reason: 'unreadable fresh origin refs' }
+    refs.set(ref, sha)
+  }
+  const commit = refs.get(`refs/heads/${target}`)
+  if (!commit) return { ok: false, reason: `remote has no branch ${target}` }
+  const tips = []
+  for (const sha of new Set(refs.values())) {
+    if (!git(workspace, ['cat-file', '-e', sha]).ok && apply) {
+      const fetched = git(workspace, ['fetch', '--quiet', '--no-tags', '--no-write-fetch-head', '--refmap=', origin, sha], { timeout: 120000 })
+      if (!fetched.ok) return { ok: false, reason: `fresh origin object fetch failed: ${fetched.err || fetched.out}` }
+    }
+    const tip = resolveCommit(workspace, sha)
+    if (tip) tips.push(tip)
+  }
+  if (!tips.includes(commit)) return { ok: false, reason: `fresh target ${commit} is unavailable locally; a dry run does not fetch` }
+  return { ok: true, commit, tips: [...new Set(tips)], fresh: true, method: apply ? 'ls-remote-and-object-fetch' : 'ls-remote' }
+}
+
+function prNumberOf(unit) {
+  const raw = unit?.pr
+  if (Number.isSafeInteger(raw)) return raw
+  if (isObject(raw)) return Number.isSafeInteger(raw.number) ? raw.number : null
+  if (typeof raw === 'string') {
+    const match = raw.match(/\/pull\/(\d+)(?:\b|$)/) ?? raw.match(/^#?(\d+)$/)
+    if (match) return Number(match[1])
+  }
+  return null
+}
+
+function normalizeProof(raw) {
+  if (!isObject(raw)) return null
+  return {
+    repo: raw.repo ?? raw.repository ?? raw.nameWithOwner ?? null,
+    pr: raw.pr ?? raw.number ?? raw.pullRequest ?? null,
+    headRepo: raw.headRepo ?? raw.headRepository?.nameWithOwner ?? raw.headRepository ?? raw.headRepositoryNameWithOwner ?? null,
+    headBranch: raw.headBranch ?? raw.headRefName ?? raw.branch ?? null,
+    headSha: raw.headSha ?? raw.headSHA ?? raw.headRefOid ?? raw.headOid ?? null,
+    dest: raw.dest ?? raw.destination ?? raw.baseRefName ?? raw.base ?? raw.baseBranch ?? null,
+    mergeSha: raw.mergeSha ?? raw.mergeCommit?.oid ?? raw.mergeCommit ?? raw.mergeCommitOid ?? raw.merge_commit_sha ?? null,
+    state: raw.state ?? null,
+    source: raw.__file ?? 'inline',
+  }
+}
+
+function ghProof({ unit, repoSlug, runGh }) {
+  const pr = prNumberOf(unit)
+  if (!pr || !repoSlug || typeof runGh !== 'function') return null
+  try {
+    const out = runGh(['pr', 'view', String(pr), '--repo', repoSlug, '--json', 'number,state,headRefOid,headRefName,headRepository,headRepositoryOwner,baseRefName,mergeCommit'])
+    const raw = JSON.parse(out)
+    return normalizeProof({
+      repo: repoSlug,
+      pr: raw.number,
+      headRepo: raw.headRepository?.nameWithOwner ?? (raw.headRepositoryOwner?.login && raw.headRepository?.name ? `${raw.headRepositoryOwner.login}/${raw.headRepository.name}` : null),
+      headBranch: raw.headRefName,
+      headSha: raw.headRefOid,
+      dest: raw.baseRefName,
+      mergeSha: raw.mergeCommit?.oid ?? null,
+      state: raw.state,
+    })
+  } catch {
+    return null
+  }
+}
+
+function squashProof({ plan, unit, run, repo, workspace, target, fresh, headSha, apply, runGh }) {
+  const repoSlug = slugFromUrl(remoteUrl(repo, 'origin'))
+  // Saved JSON is evidence, not authority to destroy the PR head. An unavailable or
+  // contradictory provider must retain the tree, even if an inline snapshot says merged.
+  const proof = apply && repoSlug && prNumberOf(unit) && typeof runGh === 'function'
+    ? ghProof({ unit, repoSlug, runGh }) : null
+  const snapshots = proof ? [proof] : []
+  const reasons = proof ? [] : ['live authoritative PR proof is unavailable']
+  for (const proof of snapshots) {
+    if (proof.state !== 'MERGED') { reasons.push(`PR state is ${proof.state}`); continue }
+    if (proof.repo !== repoSlug) { reasons.push(`repo ${proof.repo} is not ${repoSlug}`); continue }
+    const pr = prNumberOf(unit)
+    if (proof.pr !== pr) { reasons.push(`PR ${proof.pr} is not ${pr}`); continue }
+    const expectedHeadRepo = unit.headRepo ?? unit.headRepository ?? (isObject(unit.pr) ? (unit.pr.headRepo ?? unit.pr.headRepository) : null) ?? repoSlug
+    if (!/^[\w.-]+\/[\w.-]+$/.test(String(expectedHeadRepo)) || proof.headRepo !== expectedHeadRepo) {
+      reasons.push(`headRepo ${proof.headRepo} is not the recorded ${expectedHeadRepo}`)
+      continue
+    }
+    if (proof.headBranch !== unit.branch) { reasons.push(`headBranch ${proof.headBranch} is not ${unit.branch}`); continue }
+    if (proof.headSha !== headSha) { reasons.push(`headSha ${proof.headSha} is not the recorded ${headSha}`); continue }
+    const dest = String(proof.dest ?? '').replace(/^refs\/heads\//, '').replace(/^origin\//, '')
+    if (dest !== target) { reasons.push(`destination ${proof.dest} is not ${target}`); continue }
+    if (!isHexSha(proof.mergeSha)) { reasons.push('mergeSha is missing or not an exact hex SHA'); continue }
+    if (!git(workspace, ['cat-file', '-e', `${proof.mergeSha}^{commit}`]).ok) { reasons.push(`mergeSha ${proof.mergeSha} is not in the local object store after the fresh target read`); continue }
+    if (!fresh.ok) { reasons.push(fresh.reason); continue }
+    if (!git(workspace, ['merge-base', '--is-ancestor', proof.mergeSha, fresh.commit]).ok) {
+      reasons.push(`mergeSha ${proof.mergeSha} is not reachable from the fresh ${target} ${fresh.commit}`)
+      continue
+    }
+    return { ok: true, proof: { ...proof, source: 'live-github', target: fresh.commit }, reasons }
+  }
+  return { ok: false, reasons }
+}
+
+// ---- cleanup planning ----
+
+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 checkWorkspace({ repo, plan, unit, run, apply, requireApplying, allowGh, runGh }) {
+  const checks = []
+  const add = (name, ok, detail, extra = {}) => { checks.push({ name, ok, detail, ...extra }); return ok }
+  const workspace = normPath(unit?.workspace)
+  const lifecycle = unit?.lifecycle
+  const unitId = String(unit?.id ?? '')
+
+  if (!unitCompleted(unit)) {
+    const delivery = isObject(unit?.delivery) ? (unit.delivery.outcome ?? unit.delivery.state ?? 'unknown') : (unit.delivery ?? 'unknown')
+    return { verdict: 'retain', reason: `unit ${unitId} is not a completed unit (status ${unit.status ?? 'missing'}, delivery ${delivery}); its environment is kept`, checks, workspace }
+  }
+  add('completed', true, `status succeeded, delivery merged`)
+
+  const workers = hasRecordedWorker(plan, unit)
+  if (workers.length) return { verdict: 'retain', reason: `workers are recorded for this unit or overlapping paths (${workers.join(', ')})`, checks, workspace }
+  add('workers', true, 'no worker recorded for this owner or its paths')
+
+  if (!isObject(lifecycle)) return { verdict: 'retain', reason: `unit ${unitId} has no lifecycle record, so the plan does not say what it owns; run inventory/recover`, checks, workspace }
+  add('lifecycle', true, `version ${lifecycle.version}`)
+  if (lifecycle.version !== LIFECYCLE_VERSION) return { verdict: 'retain', reason: `unit ${unitId} lifecycle version ${lifecycle.version} is not ${LIFECYCLE_VERSION}`, checks, workspace }
+  const cleanup = isObject(lifecycle.cleanup) ? lifecycle.cleanup : {}
+  if (requireApplying && cleanup.state !== 'applying' && cleanup.state !== 'complete') {
+    return { verdict: 'refuse', reason: `unit ${unitId} cleanup.state is ${cleanup.state ?? 'missing'}, not applying; the coordinator must bind cleanup.state=applying through update_plan before --apply`, checks, workspace }
+  }
+  add('cleanup-state', true, requireApplying ? String(cleanup.state) : String(cleanup.state ?? 'missing'))
+
+  const wsIdent = pathIdentity(workspace)
+  if (!wsIdent.resolved) return { verdict: 'retain', reason: `workspace ${workspace} cannot be identified: ${wsIdent.reason}`, checks, workspace }
+  if (wsIdent.isSymlink) return { verdict: 'retain', reason: `workspace ${workspace} is a symbolic link`, checks, workspace }
+  if (!wsIdent.exists) {
+    const completion = verifiedReceipt({ repo, run, unit })
+    if (completion.ok && ['applying', 'complete'].includes(cleanup.state)) {
+      return { verdict: 'already-complete', reason: 'the bound cleanup receipt and every removal postcondition agree', checks, workspace, receipt: completion.receipt }
+    }
+    return { verdict: 'retain', reason: `workspace is missing; recovery requires inspection: ${completion.reason}`, checks, workspace }
+  }
+  if (cleanup.state === 'complete') {
+    return { verdict: 'retain', reason: `cleanup.state is complete, but workspace ${workspace} still exists; the plan and the disk disagree, so nothing is removed`, checks, workspace }
+  }
+
+  if (wsIdent.real === pathIdentity(repo).real) return { verdict: 'refuse', reason: `unit ${unitId} workspace is the repository checkout`, checks, workspace }
+  const runIdent = pathIdentity(run)
+  if (!runIdent.resolved || !containsPath(runIdent.real, wsIdent.real)) {
+    return { verdict: 'refuse', reason: `workspace ${workspace} is not inside the canonical run directory ${run}`, checks, workspace }
+  }
+  add('containment', true, workspace)
+
+  const recordedIdentity = lifecycle.workspace?.identity
+  if (!isObject(recordedIdentity)) return { verdict: 'retain', reason: `unit ${unitId} records no workspace identity, so the tree cannot be shown to be the one that was prepared`, checks, workspace }
+  const actualIdentity = workspaceIdentity(workspace)
+  if (!sameIdentity(recordedIdentity, actualIdentity)) {
+    return { verdict: 'retain', reason: `workspace ${workspace} does not match its recorded dev/ino/realPath identity; refusing a replacement tree`, checks, workspace }
+  }
+  add('identity', true, recordedIdentity.realPath)
+
+  const kind = workspaceKindOf(workspace)
+  if (!kind) return { verdict: 'retain', reason: `workspace ${workspace} is not a readable Git worktree or clone`, checks, workspace }
+  if (kind !== lifecycle.workspace.kind) return { verdict: 'retain', reason: `workspace ${workspace} is a ${kind}, not the recorded ${lifecycle.workspace.kind}`, checks, workspace }
+  add('kind', true, kind)
+
+  const head = currentHead(workspace)
+  const recordedHead = cleanup.headSha ?? unit.headSha
+  if (!isHexSha(recordedHead)) return { verdict: 'retain', reason: `unit ${unitId} records no exact headSha for cleanup`, checks, workspace }
+  if (!head || head !== recordedHead) return { verdict: 'retain', reason: `workspace HEAD ${head ?? 'unreadable'} is not the recorded headSha ${recordedHead}`, checks, workspace }
+  if (unit.headSha !== undefined && unit.headSha !== head) return { verdict: 'retain', reason: `unit.headSha ${unit.headSha} is not the workspace HEAD ${head}`, checks, workspace }
+  add('head', true, head)
+  if (currentBranch(workspace) !== unit.branch) return { verdict: 'retain', reason: `workspace branch ${currentBranch(workspace) ?? 'unknown'} is not ${unit.branch}`, checks, workspace }
+  add('branch', true, unit.branch)
+
+  if (kind === 'worktree') {
+    if (!isRegisteredWorktree(repo, workspace)) return { verdict: 'retain', reason: `workspace ${workspace} is a linked worktree but is not registered in ${repo}; only git worktree remove may remove it`, checks, workspace }
+    const common = gitCommonDir(workspace)
+    const repoCommon = gitCommonDir(repo)
+    if (!common || !repoCommon || common !== repoCommon) return { verdict: 'retain', reason: `workspace ${workspace} does not share ${repo}'s Git object store; it is not this repository's linked worktree`, checks, workspace }
+    add('git-ownership', true, common)
+  } else {
+    const list = worktreeList(workspace)
+    if (!list) return { verdict: 'retain', reason: `cannot read the clone's worktree registration`, checks, workspace }
+    if (list.length > 1) return { verdict: 'retain', reason: `clone ${workspace} has ${list.length - 1} linked borrower(s); only independent clones may be removed`, checks, workspace }
+    const common = gitCommonDir(workspace)
+    if (!common || common === gitCommonDir(repo)) return { verdict: 'retain', reason: `clone ${workspace} shares this repository's object store`, checks, workspace }
+    add('git-ownership', true, 'independent clone')
+  }
+
+  const origin = remoteUrl(workspace, 'origin')
+  const repoOrigin = remoteUrl(repo, 'origin')
+  if (!origin) return { verdict: 'retain', reason: `workspace ${workspace} has no origin remote, so a fresh target cannot be read`, checks, workspace }
+  if (!repoOrigin || !sameRepoUrl(origin, repoOrigin)) {
+    return { verdict: 'retain', reason: `workspace origin ${origin} is not the repository origin ${repoOrigin ?? '(missing)'}`, checks, workspace }
+  }
+  add('origin', true, origin)
+
+  const lines = statusLines(workspace)
+  if (lines === null) return { verdict: 'retain', reason: `git status cannot be read in ${workspace}`, checks, workspace }
+  const ignored = lines.filter((l) => l.startsWith('!!')).map((l) => l.slice(3).trim())
+  const declared = lifecycleResources(unit).filter((r) => isObject(r) && nonEmpty(r.path)).map((r) => pathIdentity(r.path)).filter((i) => i.resolved).map((i) => i.real)
+  const underDeclared = (rel) => {
+    const ident = pathIdentity(join(workspace, rel.replace(/^"|"$/g, '')))
+    return ident.resolved && declared.some((prefix) => containsPath(prefix, ident.real))
+  }
+  const statusPath = (line) => line.slice(3).split(' -> ').at(-1).trim().replace(/^"|"$/g, '')
+  const work = lines.filter((l) => !l.startsWith('!!')).filter((l) => !underDeclared(statusPath(l)))
+  if (work.length) return { verdict: 'retain', reason: `workspace ${workspace} holds ${work.length} uncommitted or untracked path(s) outside declared disposable resources; a clean tree is required`, checks, workspace }
+  const unknownIgnored = ignored.filter((rel) => {
+    const abs = join(workspace, rel)
+    const ident = pathIdentity(abs)
+    if (!ident.resolved) return true
+    return !declared.some((prefix) => containsPath(prefix, ident.real))
+  })
+  if (unknownIgnored.length) {
+    return { verdict: 'retain', reason: `workspace ${workspace} holds ${unknownIgnored.length} git-ignored path(s) outside declared disposable resources (${unknownIgnored.slice(0, 3).join(', ')}${unknownIgnored.length > 3 ? ', ...' : ''}); unknown ignored files are never stripped`, checks, workspace }
+  }
+  add('clean', true, 'no uncommitted, untracked, or undeclared ignored paths')
+
+  const interrupted = interruptedGitState(workspace)
+  if (interrupted.length) return { verdict: 'retain', reason: `workspace ${workspace} has an interrupted Git operation (${interrupted.join(', ')})`, checks, workspace }
+  add('git-operation', true, 'none in progress')
+  const stashes = git(workspace, ['stash', 'list'])
+  if (!stashes.ok || stashes.out.split('\n').filter(Boolean).length) {
+    return { verdict: 'retain', reason: `workspace ${workspace} has ${stashes.ok ? stashes.out.split('\n').filter(Boolean).length : 'unreadable'} stash(es)`, checks, workspace }
+  }
+  add('stash', true, 'none')
+
+  const branchTip = git(workspace, ['rev-parse', '--verify', `refs/heads/${unit.branch}`])
+  if (!branchTip.ok || branchTip.out !== head) {
+    return { verdict: 'retain', reason: `branch ${unit.branch} is not at the recorded head ${head}; the workspace has local commits beyond the prepared head`, checks, workspace }
+  }
+  add('branch-tip', true, head)
+
+  // Refs and reflogs are checked below against the fresh origin ref set, after
+  // delivery proof identifies the only head eligible for a squash exemption.
+
+  for (const resource of lifecycleResources(unit)) {
+    if (!existsSync(resource.path)) return { verdict: 'retain', reason: `declared resource ${resource.path} is missing; inspect partial cleanup`, checks, workspace }
+    const actual = resourceIdentity(resource.path)
+    if (!sameIdentity(resource.identity, actual)) return { verdict: 'retain', reason: `declared resource ${resource.path} does not match its recorded identity`, checks, workspace }
+    const actualKind = workspaceKindOf(resource.path) ?? 'directory'
+    if (actualKind !== resource.kind) return { verdict: 'retain', reason: `declared resource ${resource.path} is ${actualKind}, not recorded ${resource.kind}`, checks, workspace }
+    const failure = removalTreeSafety({ repo, path: resource.path, kind: actualKind, identity: resource.identity, declared })
+    if (failure) return { verdict: 'retain', reason: failure, checks, workspace }
+  }
+  const workspaceFailure = removalTreeSafety({ repo, path: workspace, kind, identity: recordedIdentity, declared })
+  if (workspaceFailure) return { verdict: 'retain', reason: workspaceFailure, checks, workspace }
+  add('resources', true, 'every removal path passed Git, identity, nested-repository and lock checks')
+
+  const nested = nestedRepositories(workspace, declared)
+  if (nested.truncated) return { verdict: 'retain', reason: `nested-repository scan of ${workspace} hit its bound before finishing; cannot prove there is no nested repository`, checks, workspace }
+  if (nested.found.length) return { verdict: 'retain', reason: `workspace ${workspace} contains nested Git repository ${nested.found.slice(0, 3).join(', ')}, which this cleanup does not own`, checks, workspace }
+  add('nested-repos', true, 'none')
+
+  const evidence = evidenceReport(unit, workspace)
+  if (symlinkBelow(run, join(run, 'results'))) return { verdict: 'retain', reason: 'receipt directory passes through a symbolic link', checks, workspace, evidence }
+  const receiptPath = join(run, 'results', `${safeName(unit.id)}-cleanup.json`)
+  if (existsSync(receiptPath) && !lstatSync(receiptPath).isFile()) return { verdict: 'retain', reason: 'cleanup receipt destination is not a regular file', checks, workspace, evidence }
+  const blockingEvidence = evidence.filter((e) => e.required && !(e.location === 'outside' && e.exists))
+  if (blockingEvidence.length) {
+    return { verdict: 'retain', reason: `required evidence is not preserved outside the workspace (${blockingEvidence.slice(0, 3).map((e) => e.path).join(', ')}); no transcripts are copied automatically`, checks, workspace, evidence }
+  }
+  add('evidence', true, evidence.length ? `${evidence.length} required path(s) outside the workspace` : 'none recorded')
+
+  // The refusal detail is collected per proof, not in module state: a second cleanup must
+  // not report the first one's read.
+  const uncertain = []
+  const live = liveProcessesUsing([workspace, ...declared], { onUncertain: (detail) => uncertain.push(detail) })
+  if (live === 'unreadable') return { verdict: 'retain', reason: `could not determine whether a process is using ${workspace}${uncertaintyDetail(uncertain)}; uncertainty never authorizes cleanup`, checks, workspace }
+  if (live === 'unavailable') return { verdict: 'retain', reason: `no portable process-use check is available here, so ${workspace} cannot be shown to be idle`, checks, workspace }
+  if (Array.isArray(live) && live.length) return { verdict: 'retain', reason: `${live.length} process(es) are using ${workspace} (${live.slice(0, 3).join(', ')}); a clean tree can still have live work in it`, checks, workspace }
+  add('live-use', true, 'no use found by the bounded OS cwd/open-file scan')
+
+  const target = targetBranchOf(plan, unit)
+  if (!target) return { verdict: 'retain', reason: `unit ${unitId} records no target branch, so merge into the target cannot be proved`, checks, workspace }
+  const fresh = freshTarget({ workspace, target, apply, origin: repoOrigin })
+  if (!fresh.ok) return { verdict: 'retain', reason: fresh.reason, checks, workspace }
+  add('fresh-target', true, `${target} ${fresh.commit}`)
+
+  const direct = git(workspace, ['merge-base', '--is-ancestor', head, fresh.commit]).ok
+  const proof = direct ? null : squashProof({ plan, unit, run, repo, workspace, target, fresh, headSha: head, apply, runGh: allowGh ? runGh : null })
+  if (!direct && !proof.ok) return {
+    verdict: 'retain', reason: `cannot prove ${head} merged into fresh origin/${target}: ${proof.reasons.join('; ')}`,
+    checks, workspace, target, targetCommit: fresh.commit, evidence,
+  }
+  for (const tree of [{ path: workspace, kind }, ...lifecycleResources(unit)]) {
+    if (tree.kind === 'directory') continue
+    const published = tree.path === workspace ? fresh : freshTarget({ workspace: tree.path, target, apply, origin: repoOrigin })
+    if (!published.ok) return { verdict: 'retain', reason: published.reason, checks, workspace, evidence }
+    const failure = unpublishedWork(tree.path, tree.kind, published.tips, head)
+    if (failure) return { verdict: 'retain', reason: failure, checks, workspace, evidence }
+  }
+  add('local-refs', true, 'all removable refs and reflogs are published or reachable from the verified delivered head')
+  add('merged', true, direct ? `${head} is on fresh origin/${target}` : `live PR proof for ${proof.proof.mergeSha}`)
+  return {
+    verdict: 'remove', reason: direct ? `clean and merged: ${head} is on fresh origin/${target}` : `clean and squash-merged: ${head} has live PR proof`,
+    checks, workspace, target, targetCommit: fresh.commit, evidence,
+    ...(proof?.ok ? { mergeProof: proof.proof } : {}),
+  }
+}
+
+// The liveness refusal names what it could not read, so an operator sees the path, the
+// operation and the errno instead of only "unreadable". `details` is the caller's own list.
+function uncertaintyDetail(details) {
+  const detail = details[0]
+  if (!detail) return ''
+  const where = [detail.path, detail.operation].filter(Boolean).join(' ')
+  const limit = detail.limit ? ` (limit ${detail.limit})` : ''
+  const probe = detail.probe
+    ? `; ${detail.probe.operation} ${detail.probe.errno ? `failed with ${detail.probe.errno}` : 'showed the pid still alive'}`
+    : ''
+  return ` (${where || 'a /proc read'} failed with ${detail.errno ?? 'an unknown error'}${limit}${probe})`
+}
+
+function removalTreeSafety({ repo, path, kind, identity, declared }) {
+  if (!lstatSync(path).isDirectory()) return `${path} is not a real directory`
+  const children = declared.filter(p => p !== pathIdentity(path).real && containsPath(pathIdentity(path).real, p))
+  const nested = nestedRepositories(path, children)
+  if (nested.truncated || nested.found.length) return `${path}: nested repository scan ${nested.truncated ? 'is incomplete' : `found ${nested.found.join(', ')}`}`
+  if (kind === 'directory') {
+    if (existsSync(join(path, '.git')) || (existsSync(join(path, 'HEAD')) && existsSync(join(path, 'objects')) && existsSync(join(path, 'refs')))) return `${path}: directory contains Git metadata`
+    return null
+  }
+  const common = gitCommonDir(path)
+  if (!common || (identity?.gitCommonDir && common !== identity.gitCommonDir)) return `${path}: Git identity changed or is unreadable`
+  if (kind === 'worktree') {
+    if (common !== gitCommonDir(repo) || !isRegisteredWorktree(repo, path)) return `${path}: worktree is not registered in its recorded repository`
+  } else {
+    const list = worktreeList(path)
+    if (!list || list.length !== 1 || !containsPath(pathIdentity(path).real, pathIdentity(common).real)) return `${path}: clone has linked borrowers or an external Git object store`
+    if (existsSync(join(common, 'objects', 'info', 'alternates'))) return `${path}: clone borrows an external Git object store`
+  }
+  const interrupted = interruptedGitState(path)
+  if (interrupted.length) return `${path}: locked or interrupted Git operation (${interrupted.join(', ')})`
+  const lines = statusLines(path)
+  if (!lines) return `${path}: cannot read Git status`
+  // Only untracked/ignored paths may be covered by a declared disposable child.
+  // Tracked changes are always work, including a changed submodule entry.
+  const work = lines.filter(line => {
+    if (!line.startsWith('?? ') && !line.startsWith('!! ')) return true
+    const rel = line.slice(3).replace(/^"|"$/g, '')
+    const ident = pathIdentity(join(path, rel))
+    return !ident.resolved || !children.some(child => containsPath(child, ident.real))
+  })
+  if (work.length) return `${path}: uncommitted, untracked or ignored work must be preserved`
+  const stash = git(path, ['stash', 'list'])
+  if (!stash.ok || stash.out) return `${path}: stash is present or unreadable`
+  const origin = remoteUrl(path)
+  if (!sameRepoUrl(origin, remoteUrl(repo))) return `${path}: origin is not the recorded repository origin`
+  return null
+}
+
+function unpublishedWork(path, kind, published, deliveredHead) {
+  const exclusions = [...published]
+  if (resolveCommit(path, deliveredHead)) exclusions.push(deliveredHead)
+  const refs = git(path, ['for-each-ref', '--format=%(refname)'])
+  if (!refs.ok) return `${path}: cannot read local refs`
+  const names = refs.out.split('\n').filter(Boolean)
+  const candidates = [currentHead(path)].filter(Boolean)
+  if (kind === 'clone') {
+    for (const ref of names) {
+      // Replacement refs can change the meaning of every ancestry query. Do not
+      // discard them based on commit reachability, which does not preserve that mapping.
+      if (ref.startsWith('refs/replace/')) return `${path}: local replace ref ${ref} must be preserved`
+      const commit = resolveCommit(path, ref)
+      if (!commit) return `${path}: local ref ${ref} is not a verifiable commit`
+      candidates.push(commit)
+    }
+  } else {
+    // Common refs survive git worktree remove. They can preserve this worktree's
+    // former HEADs without making another unit's private branch a global blocker.
+    for (const ref of names) {
+      const commit = resolveCommit(path, ref)
+      if (commit) exclusions.push(commit)
+    }
+    // Worktree-private refs do NOT survive removal.
+    const privateRefs = names.filter(ref => /^(refs\/(worktree|bisect|rewritten)\/)/.test(ref))
+    if (privateRefs.length) return `${path}: private worktree refs must be preserved`
+  }
+  const outside = git(path, ['rev-list', '--count', ...candidates, '--not', ...exclusions])
+  if (!outside.ok || outside.out !== '0') return `${path}: unpublished local ref or HEAD commit(s) must be preserved`
+  const reflogs = git(path, ['reflog', 'show', ...(kind === 'clone' ? ['--all'] : ['HEAD']), '--format=%H'])
+  if (!reflogs.ok) return `${path}: cannot read reflog`
+  const tips = [...new Set(reflogs.out.split('\n').filter(isHexSha))]
+  if (tips.length) {
+    const result = git(path, ['rev-list', '--count', ...tips, '--not', ...exclusions])
+    if (!result.ok || result.out !== '0') return `${path}: unpublished reflog commit(s) must be preserved`
+  }
+  return null
+}
+
+// ---- removal ----
+
+function removePath(path) {
+  try {
+    rmSync(path, { recursive: true, force: true })
+    return null
+  } catch (error) {
+    try {
+      execFileSync('chmod', ['-R', 'u+w', path], { stdio: 'ignore' })
+      rmSync(path, { recursive: true, force: true })
+      return null
+    } catch {
+      return `${path}: ${error?.code ?? error?.message ?? 'removal failed'}`
+    }
+  }
+}
+
+function writeReceipt(run, unitId, payload) {
+  const dir = join(run, 'results')
+  if (symlinkBelow(run, dir)) throw new LifecycleError('symlink', 'receipt directory passes through a symbolic link')
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, `${safeName(unitId)}-cleanup.json`)
+  const temporary = `${path}.${process.pid}.tmp`
+  try {
+    writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { flag: 'wx' })
+    renameSync(temporary, path)
+  } finally {
+    try { unlinkSync(temporary) } catch { /* rename consumed it */ }
+  }
+  return path
+}
+
+function removalRecords(unit) {
+  return [{ path: unit.workspace, kind: unit.lifecycle.workspace.kind, identity: unit.lifecycle.workspace.identity }, ...lifecycleResources(unit)]
+}
+
+function verifiedReceipt({ repo, run, unit }) {
+  const fail = reason => ({ ok: false, reason })
+  const receipt = join(run, 'results', `${safeName(unit.id)}-cleanup.json`)
+  let saved
+  try {
+    if (symlinkBelow(run, receipt)) return fail('receipt path passes through a symbolic link')
+    saved = JSON.parse(readFileSync(receipt, 'utf8'))
+  } catch { return fail('no readable cleanup receipt') }
+  const ws = unit.lifecycle?.workspace
+  if (saved.version !== RECEIPT_VERSION || saved.kind !== 'workspace-cleanup-postcondition'
+    || saved.unit !== String(unit.id) || saved.run !== normPath(run) || saved.repo !== normPath(repo)
+    || !isHexSha(saved.headSha) || saved.headSha !== unit.lifecycle?.cleanup?.headSha
+    || (unit.headSha !== undefined && saved.headSha !== unit.headSha)
+    || saved.workspace?.path !== normPath(unit.workspace) || saved.workspace?.kind !== ws?.kind
+    || saved.workspace?.removed !== true || !sameIdentity(ws?.identity, saved.workspace?.identity)
+    || JSON.stringify(ws?.identity) !== JSON.stringify(saved.workspace?.identity)) return fail('receipt does not bind this run, unit, head and workspace identity')
+  const records = removalRecords(unit)
+  if (!Array.isArray(saved.resources) || saved.resources.length !== records.length - 1
+    || !Array.isArray(saved.removedPaths) || saved.removedPaths.length !== records.length
+    || new Set(saved.removedPaths).size !== records.length) return fail('receipt does not cover every removal path')
+  const list = worktreeList(repo)
+  if (!list) return fail('worktree registrations cannot be read')
+  for (const record of records) {
+    if (!saved.removedPaths.includes(normPath(record.path))) return fail(`receipt omits ${record.path}`)
+    if (record !== records[0]) {
+      const item = saved.resources.find(r => r.path === record.path)
+      if (!item || item.removed !== true || item.kind !== record.kind || JSON.stringify(item.identity) !== JSON.stringify(record.identity)) return fail(`receipt does not bind resource ${record.path}`)
+    }
+    const ident = pathIdentity(record.path)
+    if (!ident.resolved || ident.exists || symlinkBelow(run, record.path)) return fail(`removal path still exists or cannot be identified: ${record.path}`)
+    if (list.some(p => pathIdentity(p).real === ident.real)) return fail(`worktree remains registered: ${record.path}`)
+  }
+  if (evidenceReport(unit, unit.workspace).some(e => e.required && !e.preserved)) return fail('required evidence is not preserved')
+  return { ok: true, receipt }
+}
+
+function removeOwnedTree({ repo, path, kind }) {
+  if (kind === 'worktree') {
+    if (!isRegisteredWorktree(repo, path)) return `${path}: not a registered worktree; refusing a raw removal`
+    const result = git(repo, ['worktree', 'remove', path], { timeout: 120000 })
+    if (!result.ok) return `${path}: git worktree remove failed: ${result.err || result.out}`
+    if (existsSync(path)) return `${path}: still exists after git worktree remove`
+    return null
+  }
+  return removePath(path)
+}
+
+function applyRemoval({ repo, run, plan, unit, planResult }) {
+  const unitId = String(unit.id)
+  const workspace = normPath(unit.workspace)
+  const lifecycle = unit.lifecycle
+  const failures = []
+  const removed = []
+  const resources = lifecycleResources(unit)
+  // Recheck the plan after remote/provider calls and before the first deletion.
+  const latest = readPlan(run)
+  requireRevision(latest.plan, plan.planRevision)
+  if (JSON.stringify(latest.plan) !== JSON.stringify(plan)) throw new LifecycleError('revision-mismatch', 'plan changed during cleanup preflight')
+  const records = removalRecords(unit).sort((a, b) => b.path.split(sep).length - a.path.split(sep).length)
+  const declared = resources.map(r => pathIdentity(r.path).real)
+  for (const record of records) {
+    if (symlinkBelow(run, record.path) || !sameIdentity(record.identity, resourceIdentity(record.path))
+      || (workspaceKindOf(record.path) ?? 'directory') !== record.kind) return { failures: [`${record.path}: identity or kind changed before deletion`], removed }
+    const failure = removalTreeSafety({ repo, ...record, declared })
+    if (failure) return { failures: [failure], removed }
+  }
+  if (currentHead(workspace) !== planResult.cleanup.headSha) return { failures: ['workspace HEAD changed during preflight'], removed }
+  // Children precede their containers. Git worktrees always go through Git, never rm.
+  for (const record of records) {
+    try {
+      if (symlinkBelow(run, record.path) || !sameIdentity(record.identity, resourceIdentity(record.path))) {
+        failures.push(`${record.path}: identity changed during removal`)
+        break
+      }
+      const failure = removeOwnedTree({ repo, path: record.path, kind: record.kind })
+      if (failure) { failures.push(failure); break }
+      removed.push(normPath(record.path))
+    } catch (error) {
+      failures.push(`${record.path}: ${error.message}`)
+      break
+    }
+  }
+  const registrations = worktreeList(repo)
+  if (!registrations) failures.push('cannot verify final worktree registrations')
+  for (const record of records) {
+    const postcondition = pathIdentity(record.path)
+    if (!postcondition.resolved || postcondition.exists || symlinkBelow(run, record.path)) failures.push(`${record.path}: removal postcondition is not established`)
+    if (registrations?.some(p => pathIdentity(p).real === pathIdentity(record.path).real)) failures.push(`${record.path}: still registered after removal`)
+  }
+  if (failures.length) return { failures, removed }
+
+  const receiptPayload = {
+    version: RECEIPT_VERSION,
+    kind: 'workspace-cleanup-postcondition',
+    unit: unitId,
+    run: normPath(run),
+    repo: normPath(repo),
+    at: new Date().toISOString(),
+    planRevision: plan.planRevision,
+    headSha: planResult.cleanup.headSha,
+    workspace: {
+      path: workspace,
+      kind: lifecycle.workspace.kind,
+      identity: lifecycle.workspace.identity,
+      removed: true,
+    },
+    resources: resources.map((r) => ({ path: r.path, role: r.role, kind: r.kind, identity: r.identity, removed: !existsSync(r.path) })),
+    removedPaths: removed,
+    target: planResult.target ?? null,
+    targetCommit: planResult.targetCommit ?? null,
+    mergeProof: planResult.mergeProof ?? null,
+    evidence: planResult.evidence ?? [],
+  }
+  let receipt = null
+  try { receipt = writeReceipt(run, unitId, receiptPayload) } catch (error) { failures.push(`could not write cleanup receipt: ${error.message}`) }
+  return { failures, removed, receipt }
+}
+
+export function cleanup({
+  run, unit: unitId, revision, apply = false, requireApplying = true, allowGh = true, runGh = null,
+}) {
+  run = resolve(run)
+  const first = readPlan(run)
+  const repo = repositoryOf(first.plan, run)
+  requireRevision(first.plan, revision)
+  const unit = unitOf(first.plan, unitId)
+  assertValid(validateUnit({ repo, run, plan: first.plan, unit }))
+  const runDir = canonicalRunDir(repo, run)
+
+  if (!apply) {
+    // A dry run previews the same checks, but it does not demand the coordinator's applying
+    // binding yet: that binding is what --apply checks, and the plan must be able to see what
+    // it would remove before making the transition.
+    const check = checkWorkspace({ repo, plan: first.plan, unit, run: runDir, apply: false, requireApplying: false, allowGh, runGh })
+    const lifecycle = isObject(unit.lifecycle) ? unit.lifecycle : null
+    const needsBinding = requireApplying && lifecycle?.cleanup?.state !== 'applying' && lifecycle?.cleanup?.state !== 'complete'
+    const wouldRemove = check.verdict === 'remove'
+    return {
+      version: 1,
+      command: 'cleanup',
+      ok: check.verdict === 'remove' || check.verdict === 'already-complete',
+      applied: false,
+      action: check.verdict,
+      wouldRemove,
+      authorizationRequired: needsBinding && check.verdict === 'remove' ? 'applying' : null,
+      repo,
+      run: runDir,
+      unit: String(unitId),
+      revision: planRevisionOf(first.plan),
+      workspace: { path: normPath(unit.workspace), exists: existsSync(unit.workspace), kind: lifecycle?.workspace?.kind ?? null },
+      lifecycle: null,
+      nextLifecycle: lifecycle,
+      requiredTransition: needsBinding && check.verdict === 'remove'
+        ? { cleanup: { state: 'applying', headSha: lifecycle?.cleanup?.headSha ?? unit.headSha ?? check.checks.find((c) => c.name === 'head')?.detail } }
+        : null,
+      checks: check.checks,
+      paths: check.verdict === 'remove' ? [unit.workspace, ...lifecycleResources(unit).map((r) => r.path)] : [],
+      reason: needsBinding && check.verdict === 'remove'
+        ? `${check.reason}; bind cleanup.state=applying through update_plan before --apply`
+        : check.reason,
+      receipt: check.receipt ?? null,
+      evidence: check.evidence ?? [],
+      errors: [],
+    }
+  }
+
+  const lock = acquireLock(runDir, unitId)
+  try {
+    // Revision and identity are rechecked under the lock, immediately before mutation.
+    const current = readPlan(run)
+    requireRevision(current.plan, revision)
+    const freshUnit = unitOf(current.plan, unitId)
+    assertValid(validateUnit({ repo, run, plan: current.plan, unit: freshUnit }))
+    const check = checkWorkspace({ repo, plan: current.plan, unit: freshUnit, run: runDir, apply: true, requireApplying, allowGh, runGh })
+
+    if (check.verdict === 'remove') {
+      const removal = applyRemoval({
+        repo, run: runDir, plan: current.plan, unit: freshUnit,
+        planResult: { cleanup: { headSha: check.checks.find((c) => c.name === 'head')?.detail ?? freshUnit.lifecycle?.cleanup?.headSha }, target: check.target, targetCommit: check.targetCommit, mergeProof: check.mergeProof, evidence: check.evidence },
+      })
+      if (removal.failures.length) {
+        const lifecycle = {
+          ...freshUnit.lifecycle,
+          cleanup: { ...(freshUnit.lifecycle.cleanup ?? {}), state: 'applying', headSha: freshUnit.lifecycle.cleanup?.headSha ?? currentHead(freshUnit.workspace), reason: removal.failures.join('; '), removedPaths: removal.removed, failureCount: removal.failures.length },
+        }
+        return {
+          version: 1, command: 'cleanup', ok: false, applied: true, action: 'retain', code: 'retained',
+          repo, run: runDir, unit: String(unitId), revision: planRevisionOf(current.plan),
+          workspace: { path: normPath(freshUnit.workspace), exists: existsSync(freshUnit.workspace), kind: freshUnit.lifecycle.workspace.kind },
+          lifecycle, nextLifecycle: lifecycle, checks: check.checks,
+          paths: removal.removed, reason: removal.failures.join('; '), receipt: null,
+          evidence: check.evidence ?? [], errors: removal.failures,
+        }
+      }
+      const lifecycle = {
+        ...freshUnit.lifecycle,
+        cleanup: {
+          ...(freshUnit.lifecycle.cleanup ?? {}),
+          state: 'complete',
+          headSha: freshUnit.lifecycle.cleanup?.headSha ?? check.checks.find((c) => c.name === 'head')?.detail,
+          completedAt: new Date().toISOString(),
+          ...(removal.receipt ? { receipt: removal.receipt } : {}),
+        },
+      }
+      return {
+        version: 1, command: 'cleanup', ok: true, applied: true, action: 'remove', code: 'removed',
+        repo, run: runDir, unit: String(unitId), revision: planRevisionOf(current.plan),
+        workspace: { path: normPath(freshUnit.workspace), exists: false, kind: freshUnit.lifecycle.workspace.kind },
+        lifecycle, nextLifecycle: lifecycle, checks: check.checks,
+        paths: removal.removed, reason: check.reason, receipt: removal.receipt,
+        evidence: check.evidence ?? [], errors: [],
+      }
+    }
+
+    if (check.verdict === 'already-complete') {
+      const receipt = check.receipt
+      const lifecycle = {
+        ...freshUnit.lifecycle,
+        cleanup: { ...(freshUnit.lifecycle.cleanup ?? {}), state: 'complete', ...(receipt ? { receipt } : {}) },
+      }
+      return {
+        version: 1, command: 'cleanup', ok: true, applied: false, action: 'already-complete', code: 'complete',
+        repo, run: runDir, unit: String(unitId), revision: planRevisionOf(current.plan),
+        workspace: { path: normPath(freshUnit.workspace), exists: existsSync(freshUnit.workspace), kind: freshUnit.lifecycle.workspace.kind },
+        lifecycle, nextLifecycle: lifecycle, checks: check.checks, paths: [],
+        reason: check.reason, receipt, evidence: check.evidence ?? [], errors: [],
+      }
+    }
+
+    const baseLifecycle = isObject(freshUnit.lifecycle) ? freshUnit.lifecycle : null
+    const lifecycle = baseLifecycle
+      ? {
+        ...baseLifecycle,
+        cleanup: { ...(baseLifecycle.cleanup ?? {}), state: !existsSync(freshUnit.workspace) && baseLifecycle.cleanup?.state === 'applying' ? 'applying' : 'retained', headSha: currentHead(freshUnit.workspace) ?? baseLifecycle.cleanup?.headSha ?? null, reason: check.reason },
+      }
+      : null
+    return {
+      version: 1, command: 'cleanup', ok: false, applied: false, action: check.verdict, code: check.verdict === 'refuse' ? 'refused' : 'retained',
+      repo, run: runDir, unit: String(unitId), revision: planRevisionOf(current.plan),
+      workspace: { path: normPath(freshUnit.workspace), exists: existsSync(freshUnit.workspace), kind: baseLifecycle?.workspace?.kind ?? null },
+      lifecycle, nextLifecycle: lifecycle, checks: check.checks, paths: [],
+      reason: check.reason, receipt: null, evidence: check.evidence ?? [], errors: [],
+    }
+  } finally {
+    lock.release()
+  }
+}
+
+// ---- legacy --merged compatibility ----
+
+// The old flow (`cleanup-runs.mjs --merged <workspace> --apply`) had no --run or --unit.
+// Resolve the saved run and unit that own the path, then use the same checks. An unowned
+// path is retained: a path that no plan claims is not cleaned by a glob.
+export function resolveMerged(repo, targetPath, { discoveryRoot = null } = {}) {
+  const path = pathIdentity(resolve(targetPath))
+  if (!path.resolved) return { found: false, reason: `cannot resolve ${targetPath}: ${path.reason}` }
+  const roots = []
+  if (discoveryRoot) roots.push(discoveryRoot)
+  else {
+    const marker = `${sep}.resolve-issues${sep}rush${sep}`
+    const text = `${path.real}${sep}`
+    const at = text.indexOf(marker)
+    if (at >= 0) roots.push(text.slice(0, at + marker.length - 1))
+  }
+  if (!roots.length && repo) roots.push(join(repo, '.resolve-issues', 'rush'))
+  const runsRoot = roots[0]
+  if (!runsRoot) return { found: false, reason: `${targetPath} is not under a .resolve-issues/rush directory` }
+  let names = []
+  try { names = readdirSync(runsRoot) } catch { return { found: false, reason: `cannot read ${runsRoot}` } }
+  for (const name of names) {
+    const run = join(runsRoot, name)
+    let plan
+    try { plan = readPlan(run).plan } catch { continue }
+    const units = Array.isArray(plan.units) ? plan.units : (Array.isArray(plan.issues) ? plan.issues : [])
+    for (const unit of units) {
+      if (!isObject(unit)) continue
+      if (nonEmpty(unit.workspace)) {
+        const ws = pathIdentity(unit.workspace)
+        if (ws.resolved && ws.real === path.real) return { found: true, run, repo: repositoryOf(plan, run), plan, unit, role: 'workspace' }
+      }
+      for (const resource of lifecycleResources(unit)) {
+        if (!isObject(resource) || !nonEmpty(resource.path)) continue
+        const ident = pathIdentity(resource.path)
+        if (ident.resolved && ident.real === path.real) return { found: true, run, repo: repositoryOf(plan, run), plan, unit, role: 'resource', resource }
+      }
+    }
+  }
+  return { found: false, reason: `no saved run or unit claims ${targetPath}; an unowned path is retained` }
+}
+
+export function cleanupMerged({ repo, path, apply = false, requireApplying = false, runGh = null }) {
+  const resolved = resolveMerged(repo, path)
+  if (!resolved.found) {
+    return {
+      version: 1, command: 'merged', ok: false, applied: false, action: 'refuse',
+      repo, run: null, unit: null, revision: null, workspace: { path: normPath(path), exists: existsSync(path) },
+      lifecycle: null, nextLifecycle: null, checks: [], paths: [], reason: resolved.reason, receipt: null, evidence: [], errors: [],
+    }
+  }
+  // Compatibility resolves ownership only; both workspace and resource requests enter
+  // the same whole-environment checks, lock, revision binding and receipt path.
+  const result = cleanup({ run: resolved.run, unit: resolved.unit.id, revision: resolved.plan.planRevision, apply, requireApplying, runGh })
+  return { ...result, command: 'merged' }
+}
+
+// ---- safe --repo sweep ----
+
+export function sweep({ repo, apply = false, runGh = null }) {
+  repo = resolve(repo)
+  const runsRoot = join(repo, '.resolve-issues', 'rush')
+  const result = {
+    version: 1,
+    command: 'sweep',
+    ok: true,
+    applied: Boolean(apply),
+    repo: normPath(repo),
+    runsRoot,
+    runs: [],
+    unknownEntries: [],
+    summary: { runs: 0, completed: 0, removed: 0, retained: 0, refused: 0, unknown: 0 },
+    errors: [],
+  }
+  if (!existsSync(runsRoot)) return result
+  let names = []
+  try { names = readdirSync(runsRoot, { withFileTypes: true }) } catch (error) {
+    return { ...result, ok: false, errors: [`cannot read ${runsRoot}: ${error.message}`] }
+  }
+  for (const entry of names) {
+    if (!entry.isDirectory()) { result.unknownEntries.push(entry.name); continue }
+    const run = join(runsRoot, entry.name)
+    if (!existsSync(join(run, 'task-plan.json'))) { result.unknownEntries.push(entry.name); continue }
+    result.summary.runs++
+    let planRead
+    try { planRead = readPlan(run) } catch (error) {
+      result.runs.push({ run: normPath(run), action: 'inspect', reason: `${error.code}: ${error.message}` })
+      result.summary.retained++
+      continue
+    }
+    const { plan, units } = planRead
+    const runRow = { run: normPath(run), revision: plan.planRevision ?? null, units: [] }
+    for (const unit of units) {
+      if (!isObject(unit)) continue
+      const unitId = String(unit.id ?? '')
+      if (!unitCompleted(unit)) {
+        runRow.units.push({ unit: unitId, action: 'retain', reason: 'not a completed unit' })
+        result.summary.retained++
+        continue
+      }
+      result.summary.completed++
+      const lifecycle = unit.lifecycle
+      if (!isObject(lifecycle)) {
+        runRow.units.push({ unit: unitId, action: 'retain', reason: 'no lifecycle record; the sweep does not adopt an unrecorded tree' })
+        result.summary.retained++
+        continue
+      }
+      try {
+        const observed = cleanup({ run, unit: unitId, revision: plan.planRevision, apply, requireApplying: false, runGh })
+        runRow.units.push(observed)
+        if (observed.action === 'remove' && observed.applied) result.summary.removed++
+        else if (observed.action === 'refuse') result.summary.refused++
+        else if (!observed.ok) result.summary.retained++
+      } catch (error) {
+        runRow.units.push({ unit: unitId, action: 'inspect', reason: `${error.code ?? 'error'}: ${error.message}` })
+        result.summary.retained++
+      }
+    }
+    result.runs.push(runRow)
+  }
+  result.summary.unknown = result.unknownEntries.length
+  return result
+}
+
+// ---- recover (read-only) ----
+
+export function recover({ repo, runGh = null }) {
+  repo = resolve(repo)
+  const runsRoot = join(repo, '.resolve-issues', 'rush')
+  const out = {
+    version: 1,
+    command: 'recover',
+    ok: true,
+    readonly: true,
+    repo: normPath(repo),
+    runsRoot,
+    runs: [],
+    worktrees: [],
+    locks: [],
+    due: [],
+    unknownEntries: [],
+  }
+  const owned = new Map()
+  let names = []
+  try { names = readdirSync(runsRoot, { withFileTypes: true }) } catch (error) {
+    return { ...out, ok: false, errors: [`cannot read ${runsRoot}: ${error.message}`] }
+  }
+  for (const entry of names) {
+    if (!entry.isDirectory()) { out.unknownEntries.push(entry.name); continue }
+    const run = join(runsRoot, entry.name)
+    if (!existsSync(join(run, 'task-plan.json'))) { out.unknownEntries.push(entry.name); continue }
+    let planRead
+    try { planRead = readPlan(run) } catch (error) {
+      out.runs.push({ run: normPath(run), action: 'inspect', reason: `${error.code}: ${error.message}`, units: [] })
+      continue
+    }
+    const { plan, units } = planRead
+    const runRow = { run: normPath(run), revision: plan.planRevision ?? null, units: [] }
+    for (const unit of units) {
+      if (!isObject(unit)) continue
+      const unitId = String(unit.id ?? '')
+      if (nonEmpty(unit.workspace)) {
+        const ident = pathIdentity(unit.workspace)
+        if (ident.resolved) owned.set(ident.real, `${unitId}:workspace`)
+      }
+      for (const resource of lifecycleResources(unit)) {
+        if (!isObject(resource) || !nonEmpty(resource.path)) continue
+        const ident = pathIdentity(resource.path)
+        if (ident.resolved) owned.set(ident.real, `${unitId}:resource:${resource.role ?? 'unknown'}`)
+      }
+      const lifecycle = isObject(unit.lifecycle) ? unit.lifecycle : null
+      const row = {
+        unit: unitId,
+        status: unit.status ?? null,
+        delivery: isObject(unit.delivery) ? (unit.delivery.outcome ?? unit.delivery.state ?? null) : (unit.delivery ?? null),
+        workspace: { path: unit.workspace ?? null, exists: nonEmpty(unit.workspace) ? existsSync(unit.workspace) : false, kind: lifecycle?.workspace?.kind ?? null },
+        cleanup: lifecycle?.cleanup ?? null,
+        resources: lifecycleResources(unit).map((r) => ({ path: r.path, role: r.role, exists: existsSync(r.path), state: r.state })),
+        action: 'none',
+        reason: null,
+      }
+      const cleanup = lifecycle?.cleanup ?? null
+      if (lifecycle?.workspace?.state === 'preparing' && cleanup?.state !== 'complete' && cleanup?.state !== 'retained') {
+        row.action = 'prepare'
+        row.reason = `lifecycle.workspace.state is preparing; prepare the recorded ${lifecycle.workspace.kind} and persist its ready identity`
+        out.due.push({ run: normPath(run), unit: unitId, operation: 'prepare', workspace: unit.workspace ?? null, reason: row.reason })
+      } else if (isObject(cleanup) && cleanup.state === 'complete') {
+        const completion = verifiedReceipt({ repo: repositoryOf(plan, run), run: canonicalRunDir(repo, run), unit })
+        if (!completion.ok) {
+          row.action = 'inspect'
+          row.reason = `completion cannot be verified: ${completion.reason}`
+          out.due.push({ run: normPath(run), unit: unitId, operation: 'inspect', workspace: unit.workspace, reason: row.reason })
+        }
+      } else if (isObject(cleanup) && cleanup.state === 'applying') {
+        if (!row.workspace.exists) {
+          const completion = verifiedReceipt({ repo: repositoryOf(plan, run), run: canonicalRunDir(repo, run), unit })
+          row.action = completion.ok ? 'postcondition' : 'inspect'
+          row.reason = completion.ok ? `verified cleanup receipt ${completion.receipt}; persist complete` : `ambiguous partial cleanup: ${completion.reason}`
+          out.due.push({ run: normPath(run), unit: unitId, operation: completion.ok ? 'recover-postcondition' : 'inspect', workspace: unit.workspace ?? null, receipt: completion.receipt ?? null, reason: row.reason })
+        } else {
+          row.action = 'cleanup-due'
+          row.reason = 'cleanup.state is applying and the workspace still exists; rerun cleanup --apply'
+          out.due.push({ run: normPath(run), unit: unitId, operation: 'cleanup', workspace: unit.workspace ?? null, reason: row.reason })
+        }
+      } else if (unitCompleted(unit) && lifecycle && cleanup?.state !== 'complete' && row.workspace.exists) {
+        row.action = 'cleanup-due'
+        row.reason = `unit is completed and cleanup.state is ${cleanup?.state ?? 'missing'}; verify and bind applying before apply`
+        out.due.push({ run: normPath(run), unit: unitId, operation: 'cleanup', workspace: unit.workspace ?? null, reason: row.reason })
+      } else if (!row.workspace.exists && lifecycle?.workspace?.state === 'ready') {
+        row.action = 'inspect'
+        row.reason = 'lifecycle records a ready workspace that is missing'
+        out.due.push({ run: normPath(run), unit: unitId, operation: 'inspect', workspace: unit.workspace ?? null, reason: row.reason })
+      }
+      runRow.units.push(row)
+    }
+    out.runs.push(runRow)
+    try {
+      const locks = readdirSync(join(run, '.workspace-locks'), { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name.replace(/\.lock$/, ''))
+      for (const lock of locks) {
+        const path = join(run, '.workspace-locks', `${lock}.lock`)
+        out.locks.push({ run: normPath(run), unit: lock, path })
+        out.due.push({ run: normPath(run), unit: lock, operation: 'lock', path, reason: 'a workspace lock is held; the lock is never reclaimed by age, so inspect the owner and remove it only after confirming no prepare or cleanup is running' })
+      }
+    } catch { /* no locks directory */ }
+  }
+  const listed = worktreeList(repo)
+  if (listed) {
+    const runsReal = pathIdentity(runsRoot).real
+    for (const path of listed) {
+      const ident = pathIdentity(path)
+      if (!ident.resolved) {
+        out.worktrees.push({ path, resolved: false, ownedBy: owned.get(ident.recorded) ?? null, insideRoot: false })
+        continue
+      }
+      const isRepository = ident.real === pathIdentity(repo).real
+      out.worktrees.push({
+        path: ident.real,
+        ownedBy: owned.get(ident.real) ?? null,
+        insideRoot: runsReal ? containsPath(runsReal, ident.real) : false,
+        isRepository,
+      })
+      if (!isRepository && !owned.get(ident.real)) {
+        out.due.push({ operation: 'orphan-worktree', path: ident.real, reason: 'a registered worktree is not owned by any unit in a saved plan; inventory only, never removed by pattern or age' })
+      }
+    }
+  }
+  out.ownedPaths = [...owned.entries()].map(([path, owner]) => ({ path, owner }))
+  return out
+}
+
+// ---- inventory (read-only, bounded, no symlink traversal) ----
+
+export function inventory({ repo, root = null, maxEntries = INVENTORY_MAX_ENTRIES, maxDepth = INVENTORY_MAX_DEPTH }) {
+  repo = resolve(repo)
+  if (!Number.isSafeInteger(maxEntries) || maxEntries <= 0) throw new LifecycleError('inventory-bound', '--max-entries must be a positive integer')
+  if (!Number.isSafeInteger(maxDepth) || maxDepth < 0) throw new LifecycleError('inventory-bound', '--max-depth must be a nonnegative integer')
+  const defaultRoot = join(repo, '.resolve-issues', 'rush')
+  const inventoryRoot = root ? resolve(root) : defaultRoot
+  const out = {
+    version: 1,
+    command: 'inventory',
+    ok: true,
+    readonly: true,
+    repo: normPath(repo),
+    root: normPath(inventoryRoot),
+    maxEntries,
+    maxDepth,
+    entries: [],
+    runs: [],
+    registeredWorktrees: [],
+    truncated: false,
+    unknownEntries: [],
+  }
+  const owned = new Map()
+  const registered = new Set()
+  const runs = []
+  if (existsSync(defaultRoot)) {
+    let names = []
+    try { names = readdirSync(defaultRoot, { withFileTypes: true }) } catch { names = [] }
+    for (const entry of names) {
+      if (!entry.isDirectory()) { out.unknownEntries.push(entry.name); continue }
+      const run = join(defaultRoot, entry.name)
+      if (!existsSync(join(run, 'task-plan.json'))) { out.unknownEntries.push(entry.name); continue }
+      try {
+        const { plan, units } = readPlan(run)
+        const runRow = { run: normPath(run), revision: plan.planRevision ?? null, units: [] }
+        for (const unit of units) {
+          if (!isObject(unit)) continue
+          const unitId = String(unit.id ?? '')
+          const lifecycle = isObject(unit.lifecycle) ? unit.lifecycle : null
+          runRow.units.push({
+            unit: unitId,
+            workspace: unit.workspace ?? null,
+            branch: unit.branch ?? null,
+            lifecycle: lifecycle ? { state: lifecycle.workspace?.state, kind: lifecycle.workspace?.kind, cleanup: lifecycle.cleanup ?? null } : null,
+            resources: lifecycleResources(unit).map((r) => ({ path: r.path, role: r.role, state: r.state })),
+          })
+          if (nonEmpty(unit.workspace)) {
+            const ident = pathIdentity(unit.workspace)
+            if (ident.resolved) owned.set(ident.real, `${unitId}:workspace`)
+          }
+          for (const resource of lifecycleResources(unit)) {
+            if (!isObject(resource) || !nonEmpty(resource.path)) continue
+            const ident = pathIdentity(resource.path)
+            if (ident.resolved) owned.set(ident.real, `${unitId}:resource:${resource.role ?? 'unknown'}`)
+          }
+        }
+        runs.push(runRow)
+      } catch (error) {
+        out.unknownEntries.push(entry.name)
+        runs.push({ run: normPath(run), action: 'inspect', reason: `${error.code}: ${error.message}` })
+      }
+    }
+  }
+  out.runs = runs
+
+  // Walk the requested root without following symlinks. A symlink is reported as an entry
+  // and never traversed; the bound is on entries, not on the size of the filesystem.
+  const rootIdent = pathIdentity(inventoryRoot)
+  let rootIsSymlink = false
+  try { rootIsSymlink = lstatSync(inventoryRoot).isSymbolicLink() } catch { /* missing is handled below */ }
+  if (!rootIdent.resolved || !rootIdent.exists) {
+    out.reason = rootIdent.resolved ? `${inventoryRoot} does not exist` : rootIdent.reason
+  } else if (rootIsSymlink) {
+    out.reason = `${inventoryRoot} is a symbolic link; inventory does not follow it`
+  } else {
+    const queue = [{ path: rootIdent.real, depth: 0 }]
+    while (queue.length) {
+      if (out.entries.length >= maxEntries) { out.truncated = true; break }
+      const { path, depth } = queue.shift()
+      let entries = []
+      try { entries = readdirSync(path, { withFileTypes: true }) } catch { continue }
+      for (const entry of entries) {
+        if (out.entries.length >= maxEntries) { out.truncated = true; break }
+        const child = join(path, entry.name)
+        let kind = 'other'
+        if (entry.isSymbolicLink()) kind = 'symlink'
+        else if (entry.isDirectory()) kind = 'directory'
+        else if (entry.isFile()) kind = 'file'
+        const ident = pathIdentity(child)
+        const ownedBy = ident.resolved ? owned.get(ident.real) ?? null : null
+        const row = {
+          path: child,
+          depth,
+          kind,
+          ownedBy,
+          registeredWorktree: false,
+        }
+        try { row.size = entry.isFile() ? statSync(child).size : null } catch { row.size = null }
+        out.entries.push(row)
+        if (kind === 'directory' && depth + 1 <= maxDepth) queue.push({ path: child, depth: depth + 1 })
+        else if (kind === 'directory') out.truncated = true
+      }
+    }
+  }
+
+  const listed = worktreeList(repo)
+  if (listed) {
+    const rootReal = pathIdentity(inventoryRoot).real
+    out.registeredWorktrees = listed.map((path) => {
+      const ident = pathIdentity(path)
+      if (ident.resolved) registered.add(ident.real)
+      return {
+        path: ident.resolved ? ident.real : path,
+        ownedBy: ident.resolved ? owned.get(ident.real) ?? null : null,
+        insideRoot: ident.resolved && rootReal ? containsPath(rootReal, ident.real) : false,
+        exists: ident.resolved ? ident.exists : false,
+      }
+    })
+    for (const row of out.entries) row.registeredWorktree = registered.has(row.path)
+  }
+  return out
+}