@1aboveio/skills 0.10.0

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

@@ -0,0 +1,829 @@
+// workspaces — a tree per unit, and a reap that cannot destroy work (ADR 0001 decisions
+// 3 and 4).
+//
+// A WORKSPACE belongs to a UNIT, from its first producer spawn until the unit is delivered
+// or handed back. Fix rounds reuse it, so a dependency install is paid once per unit rather
+// than once per round, and a spawn that dies leaves a partial its replacement resumes in
+// place.
+//
+// Decision 4 is what most of this file is: **preserved on death, reaped only on success.**
+// Nothing is destroyed while it holds unpublished work. That makes every rule here fail
+// CLOSED — unreadable, unrecognized and still-in-use all preserve — because the two errors
+// are not symmetric. A workspace kept too long is a directory a human deletes; a workspace
+// removed too early is work that existed nowhere else.
+//
+// The defect this addresses is live, not hypothetical: `git worktree list` in this repo on
+// 2026-07-26 showed ten leftovers across four naming schemes, at ONE workspace per run.
+// Per-unit multiplies that by the roster, so the reap lands with the parallelism.
+//
+//   node workspaces.mjs path <slug> <unitId> [--repo-dir DIR]   # the path a unit's workspace takes
+//   node workspaces.mjs reap <slug> [--apply] [--repo-dir DIR]  # plan (default) / perform the reap
+//   node workspaces.mjs --help
+//
+// EXIT CODES (reap):
+//   0  every recorded workspace is accounted for AND the orphan sweep ran; nothing was
+//      preserved for cause
+//   1  something was preserved or refused, or (under --apply) a removal FAILED and the tree
+//      is still there — read the rows before touching anything by hand
+//   2  usage error
+//   3  no manifest for that slug (absent is normal — run-state's own convention)
+//   4  the orphan sweep could NOT run (no workspace root recorded, or `git worktree list`
+//      could not be read). Nothing is wrong with what was checked — the point is that the
+//      disk was not checked, and that used to exit 0 looking like a clean sweep. It
+//      OUTRANKS 1: the orchestrator's checkout is refused on every real run, so a code
+//      ranked under 1 would never be seen
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+import { terminalDisposition } from './terminal-dispositions.mjs'
+// One rule for where a run's manifest lives. A second copy here would be a reap reading a
+// different file from the one the run writes — and reaping against it. The import is
+// one-way on purpose: `run-state.mjs` must not import this module back, because a cycle
+// plus the entrypoint's top-level await deadlocks the CLI (caught by the bundled-script
+// --help screen, which is what that screen is for).
+import { fileFor, readManifest } from './run-state.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0
+const arr = (v) => (Array.isArray(v) ? v : [])
+
+// ---- where a unit's workspace lives ----
+
+// Beside the repo, never inside it: a workspace inside the checkout lands in `git status`,
+// in every unit's diff, and in the glob every test discovery walks. Namespaced by run AND
+// unit — two units sharing a tree is the corruption this whole change exists to remove, so
+// the path derivation must make it impossible rather than merely unlikely.
+export function unitWorkspacePathFor(toplevel, slug, unitId) {
+  const base = String(toplevel || '').replace(/\/+$/, '')
+  const safe = (v, fallback) => {
+    const s = String(v ?? '').replace(/[^\w.-]+/g, '-').replace(/^-+|-+$/g, '')
+    return s.length ? s : fallback
+  }
+  return `${base}-workspaces/${safe(slug, 'run')}/${safe(unitId, 'unit')}`
+}
+
+// ---- who still holds a workspace ----
+
+// The unit owns its tree until it is DELIVERED or HANDED BACK. Everything short of that —
+// queued, in-progress, merge-ready-awaiting-delivery, blocked — still holds it.
+//
+// `blocked` is deliberately holding. A blocked unit is parked on a human decision, and its
+// partial is exactly what that human comes back to; reaping it would delete the evidence
+// the decision is about. `merge-ready` with no terminal outcome is the epic-986 shape: it
+// reads as finished everywhere and is still in flight.
+export function unitHoldsWorkspace(unit) {
+  if (!isObject(unit)) return false
+  const disposition = terminalDisposition(unit)
+  if (disposition && disposition !== 'blocked') return false
+  return true
+}
+
+// ---- observing a workspace ----
+
+function git(args, cwd) {
+  try {
+    return { ok: true, out: execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }) }
+  } catch (error) {
+    return { ok: false, out: '', error }
+  }
+}
+
+// Which processes are running INSIDE a tree. `lsof -t +D <path>` lists every PID with a file
+// or cwd under that directory; it is slow on huge trees but this runs once per workspace at
+// reap time, not in a loop.
+//
+// Four answers, and the last two are NOT the same fact:
+//   []             nothing holds it (including lsof's exit-1-found-nothing)
+//   ['123', ...]   these PIDs do — preserve
+//   'unreadable'   lsof exists and the call failed — preserve, same reasoning as an
+//                  unreadable `git status` not being allowed to read as clean
+//   'unavailable'  lsof is not installed here — the check cannot run at all; see the catch
+//
+// Deliberately not a process-name allowlist: what matters is that SOMETHING holds the tree,
+// not what it is. A node test runner, a Playwright worker and a shell all lose work the same
+// way. See the preserve branch in reapDecision for the incident.
+export function liveProcessesIn(workspacePath, { run = execFileSync } = {}) {
+  const p = String(workspacePath ?? '')
+  if (!p) return []
+  let out
+  try {
+    out = run('lsof', ['-t', '+D', p], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+  } catch (error) {
+    // lsof exits 1 when it simply found nothing: a clean negative, not a failure.
+    if (error && error.status === 1 && !String(error.stdout ?? '').trim()) return []
+    // NOT INSTALLED is a different fact from RAN AND FAILED, and conflating them bricks the
+    // reap. `lsof` is absent on a stock GitHub Linux runner, so treating its absence as
+    // "unreadable" made every workspace preserve — the reap stopped removing anything and
+    // four pre-existing tests went red. Caught by CI on this very change.
+    //
+    // The liveness check is an ADDITION to a ladder that was already safe on tree contents
+    // alone. Where the tool does not exist, degrading to that prior behaviour is right;
+    // refusing to reap anything is not. Where the tool DOES exist and failed, something is
+    // wrong on this machine and caution is right. Hence two values, not one — and the
+    // caller surfaces `unavailable` in the plan so the downgrade is visible rather than a
+    // guard that quietly stopped guarding.
+    if (error && (error.code === 'ENOENT' || error.status === 127)) return 'unavailable'
+    return 'unreadable'
+  }
+  const pids = String(out ?? '').split('\n').map((l) => l.trim()).filter(Boolean)
+  const self = new Set([String(process.pid), String(process.ppid)])
+  return [...new Set(pids.filter((pid) => !self.has(pid)))]
+}
+
+// Everything the reap decision needs, read from the tree itself. Three separate kinds of
+// unpublished work, because they fail differently:
+//
+//   dirty      modified tracked files — what `git status` is usually checked for.
+//   untracked  files nobody has ever committed, let alone pushed. Cheap to overlook and
+//              total to lose.
+//   unpushed   commits contained in no remote-tracking ref. This is the one a status-only
+//              check calls CLEAN: the tree is spotless and the entire unit lives in a
+//              branch that exists on one machine.
+export function observeWorkspace(workspacePath, { runGit = git, liveProcesses = liveProcessesIn } = {}) {
+  const p = String(workspacePath ?? '')
+  const empty = { exists: false, readable: false, dirty: [], untracked: [], unpushed: [], branch: null, head: null, gitCommonDir: null, liveProcesses: [] }
+  if (!p || !fs.existsSync(p)) return empty
+
+  const live = liveProcesses(p)
+  const head = runGit(['rev-parse', 'HEAD'], p)
+  if (!head.ok) return { ...empty, exists: true, liveProcesses: live }
+  const status = runGit(['status', '--porcelain'], p)
+  // An unreadable status is NOT "clean" — that is the fabricated-evidence direction, and
+  // here it costs work rather than a review round.
+  if (!status.ok) return { ...empty, exists: true, head: head.out.trim(), liveProcesses: live }
+
+  const lines = status.out.split('\n').map((l) => l.replace(/\s+$/, '')).filter(Boolean)
+  const untracked = lines.filter((l) => l.startsWith('??'))
+  const dirty = lines.filter((l) => !l.startsWith('??'))
+
+  // Contained in NO remote-tracking ref. Worktrees share the object store and the remotes
+  // with their parent, so this reads the same refs a push would have updated.
+  const revs = runGit(['rev-list', '--max-count=50', 'HEAD', '--not', '--remotes'], p)
+  if (!revs.ok) return { exists: true, readable: false, dirty, untracked, unpushed: [], branch: null, head: head.out.trim(), liveProcesses: live }
+  const unpushed = revs.out.split('\n').map((l) => l.trim()).filter(Boolean)
+
+  const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD'], p)
+  const common = runGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], p)
+  return {
+    exists: true,
+    readable: true,
+    dirty,
+    untracked,
+    unpushed,
+    branch: branch.ok ? branch.out.trim() : null,
+    head: head.out.trim(),
+    gitCommonDir: common.ok ? common.out.trim() : null,
+    liveProcesses: live,
+  }
+}
+
+// ---- the reap decision ----
+
+// Trailing slashes are noise. The filesystem ROOT is not — `/` is a real directory, and
+// stripping it to `''` is what turned a declared scope of `/` into "this run declared no
+// scope" and a protected `/` into "nothing to protect". Both are the set-but-read-as-unset
+// class (#591 F1): a value somebody set, silently read as absent, one layer down from where
+// it was written. `''` stays `''`, because that is what unrecorded genuinely looks like.
+const norm = (p) => {
+  const s = String(p ?? '')
+  return s.replace(/\/+$/, '') || (s.startsWith('/') ? '/' : '')
+}
+
+// "Nobody recorded a path", as distinct from "somebody recorded a bad one": absent, null,
+// or a string with nothing in it. Exactly `run-state.mjs`'s `unrecordedPath` plus nullish,
+// so the validator and the guard carve out the same set rather than two overlapping ones.
+//
+// This is the predicate the whole class turns on. PRESENCE and USABILITY are two questions,
+// and `nonEmpty(v)` only answers the second — reading its `false` as "unset" is what let a
+// non-string, a whitespace-only string and an all-slash root each arrive as a declaration
+// nobody made, and be replaced by a scope the manifest never named. A value that is present
+// and unusable must reach the guard and be REFUSED there, never routed around.
+const unrecorded = (v) => v === undefined || v === null || (typeof v === 'string' && v.trim().length === 0)
+
+// `parent` is, or contains, `child` — both already canonical absolute paths.
+//
+// `${parent}/` is the obvious way to write the prefix test and it is wrong at exactly one
+// value: for `parent === '/'` it is `//`, which prefixes nothing. So the one directory that
+// contains every path there is answered "contains none" — and that is not academic, it is
+// what let a tree resolving to `/` walk past the protected-path guard and come back REAP.
+const contains = (parent, child) => (
+  parent === child || (parent === '/' ? child.startsWith('/') : child.startsWith(`${parent}/`))
+)
+
+// The filesystem root is never a tree this loop owns, on any side of any decision: as a
+// sweep scope it is every worktree on the machine, as a candidate it is the whole disk.
+// Refused on its own account rather than as a consequence of some protected path happening
+// to be configured, because "it depended on unrelated configuration" is the shape of the
+// last three defects here.
+const isFilesystemRoot = (ident) => isObject(ident) && ident.resolved === true && ident.real === '/'
+
+// A path is a directory on disk, not a string. Compared as text, any SECOND SPELLING of one
+// directory walks past every guard below — and the second spelling is not exotic: on macOS
+// `/tmp` IS a symlink to `/private/tmp`, so a workspace created as `/tmp/x` and a guard
+// written as `/private/tmp/x` name one tree and match nothing.
+//
+// There are three such spellings, and CASE is the one a symlink resolver does not close.
+// `fs.realpathSync` — the JS implementation — resolves links but hands the case back
+// untouched: on a case-insensitive filesystem (default APFS, and NTFS) it answers
+// `/PRIVATE/TMP` for `/PRIVATE/TMP` while that IS `/private/tmp`, and the guard then ranks
+// the orchestrator's own checkout REAP under a shouted name. `fs.realpathSync.native` asks
+// the OS instead of walking the links in JS, so it answers with the real on-disk spelling.
+// That is the default here, and it is deliberately not backed by a fallback: falling back to
+// the JS resolver would restore the case-blind compare invisibly, and every OS this runs on
+// has shipped `.native` since Node 9.2. If it were ever absent the call throws inside the
+// loop below, which fails CLOSED — the direction that cannot lose work.
+//
+// What `.native` changes BEYOND case, checked rather than assumed (Node 22, darwin/linux):
+// error codes are identical on every path this walk depends on — ENOENT for a missing entry
+// and for a dangling symlink, ENOTDIR through a non-directory, ELOOP on a symlink cycle — so
+// the ENOENT walk-up below is unaffected and a not-yet-created path still resolves through
+// its nearest real ancestor. The one behavioural difference is at the empty string, where
+// the JS implementation resolves to the process CWD and `.native` throws ENOENT; that input
+// is already refused above, and `.native`'s answer is the safer of the two anyway.
+//
+// Returns { recorded, real, resolved, reason }. `resolved: false` is the answer that
+// matters — it means "this path's identity is unknowable", and every caller here treats
+// that as protected, because the whole point of a guard is that uncertainty must not
+// authorize a deletion.
+//
+// A path that does not exist YET is NOT uncertainty: nothing is there to destroy, and a
+// unit's workspace path is derived before the worktree is added. So resolution walks up to
+// the nearest ancestor that DOES exist and re-appends the rest — `/tmp/run/u1` resolves to
+// `/private/tmp/run/u1` whether or not `u1` was created. Only the ancestor that EXISTS gets
+// canonicalized, because a segment that is not on disk has no on-disk spelling to read — the
+// trailing segments are re-appended exactly as recorded. That is the right answer and not a
+// residual case hole: a path whose parent does not exist cannot be inside anything the guard
+// protects, and there is nothing under it to destroy. Genuine uncertainty is everything
+// else: a relative path (its tree depends on the caller's cwd), a dangling symlink (it
+// exists, and nobody can say what it names), a permission or symlink-loop refusal, an ENOENT
+// with no resolvable ancestor at all.
+// Exported so a test can pin WHICH resolver is the default, which is an implementation
+// assertion on purpose. On a case-SENSITIVE filesystem — ext4, i.e. this repo's Linux CI —
+// no BEHAVIOURAL test can tell the two resolvers apart, because there an uppercase spelling
+// genuinely names a different directory and the case tests skip for cause. Without this pin,
+// the one-identifier revert that reopens the whole case class goes green on the only machine
+// that gates a merge.
+export const RESOLVE_PATH = fs.realpathSync.native
+
+export function pathIdentity(input, { realpath = RESOLVE_PATH, lstat = fs.lstatSync } = {}) {
+  const recorded = norm(input)
+  const unresolved = (reason) => ({ recorded, real: null, resolved: false, reason })
+  if (!recorded) return unresolved('an empty path names no tree')
+  // A RELATIVE path is the third spelling that evades the guard, after the symlink alias and
+  // the trailing slash — and it is the worst of the three, because `realpath` would resolve
+  // it against whatever `cwd` the reap happens to run from rather than the tree it was
+  // recorded against. `unitWorkspacePathFor` derives from `git rev-parse --show-toplevel`
+  // and `git worktree list --porcelain` prints absolute paths, so nothing legitimate is
+  // relative; what does arrive this way is a hand-edited manifest (`run-state.mjs validate`
+  // says "must be a non-empty absolute path" but only checks non-empty) or a non-string
+  // coerced by `norm` — `42` and `[object Object]` are both relative paths under a cwd.
+  if (!path.isAbsolute(recorded)) return unresolved(`${recorded} is not an absolute path, so which tree it names depends on the working directory the reap happens to run from`)
+
+  const trailing = []
+  let cur = recorded
+  // Bounded: a pathological input must not spin. 64 is far past any real workspace depth.
+  for (let depth = 0; depth < 64; depth++) {
+    try {
+      const real = realpath(cur)
+      return { recorded, real: norm(trailing.length ? path.join(real, ...trailing) : real) || '/', resolved: true, reason: null }
+    } catch (error) {
+      const code = error?.code
+      if (code !== 'ENOENT') {
+        return unresolved(`realpath refused ${cur} (${code ?? error?.message ?? 'unknown error'})`)
+      }
+      // ENOENT from realpath but the entry itself is there = a symlink whose target is
+      // gone. "Does not exist" and "points somewhere unknown" are different answers.
+      let dangling = false
+      try { lstat(cur); dangling = true } catch { dangling = false }
+      if (dangling) return unresolved(`${cur} is a symlink whose target does not exist, so what it names cannot be established`)
+      const parent = path.dirname(cur)
+      if (!parent || parent === cur) return unresolved(`no existing ancestor of ${recorded} could be resolved`)
+      trailing.unshift(path.basename(cur))
+      cur = parent
+    }
+  }
+  return unresolved(`gave up resolving ${recorded} after 64 levels`)
+}
+
+// True when removing `candidate` would take `protectedPath` with it, in either direction:
+// the same tree, a parent of it, or a child of it. A child matters because a unit workspace
+// nested inside the orchestrator's checkout is itself the decision-3 violation — it is not
+// a separate tree at all.
+//
+// Takes IDENTITIES, not strings, and an unresolvable identity on either side collides:
+// a tree nobody can identify cannot be shown to be a different tree from the checkout.
+function collides(candidate, guarded) {
+  if (!isObject(candidate) || !isObject(guarded)) return true
+  if (!candidate.resolved || !guarded.resolved) return true
+  const a = candidate.real
+  const b = guarded.real
+  if (!a || !b) return true
+  return contains(b, a) || contains(a, b)
+}
+
+// The whole safety rule, as one decidable function over an observation.
+//
+// Order matters and is deliberate: identity and the protected-path guard run BEFORE any
+// evidence is weighed, so no amount of cleanliness can talk the reap into removing the
+// orchestrator's checkout. Everything after them preserves on any doubt.
+//
+// `claimants` is every unit the manifest says owns this path. More than one is a corrupt
+// manifest, and it is refused rather than resolved — see the ambiguity guard below.
+export function reapDecision({ path: candidate, unit = null, claimants = null, observation = {}, protectedPaths = [], orchestratorGitCommonDir = null, requireGitOwnership = false, identify = pathIdentity } = {}) {
+  const p = norm(candidate)
+  const id = isObject(unit) && nonEmpty(unit.id) ? unit.id : null
+  // `liveProcesses` rides on every row so the plan header can report a platform that
+  // cannot run the check at all — a downgrade the per-row reasons would never show.
+  const row = (verdict, reason) => ({ path: p, unit: id, verdict, reap: verdict === 'reap', reason, liveProcesses: (isObject(observation) ? observation : {}).liveProcesses ?? null })
+
+  // Identity first: a path whose tree on disk cannot be established cannot be shown to be
+  // outside the orchestrator's checkout, so the guard below would be deciding on a name
+  // rather than on a directory.
+  // `resolved` is a claim, and `real` is the thing every guard below actually compares. An
+  // identity that claims resolution without naming a tree is not a resolution — `collides`
+  // already refuses on an empty `real`, but only once there is a protected path to compare
+  // against, so with none configured a lying resolver would fall straight through to REAP.
+  // `pathIdentity` cannot produce that shape; an injected `identify` can, and the seam is
+  // exported.
+  const me = identify(p)
+  if (!isObject(me) || !me.resolved || !nonEmpty(me.real)) {
+    return row('refuse', `refuses ${p}: its identity on disk cannot be established — ${isObject(me) ? (me.reason ?? 'it resolved to no path at all') : 'no identity was returned'}. A path that will not resolve cannot be shown to be a different tree from the orchestrator's checkout, and uncertainty never authorizes a removal`)
+  }
+
+  // The filesystem root, before the protected paths, because it is the one candidate whose
+  // refusal must not depend on one being configured. `/`, `/.`, `/..` and a symlink to `/`
+  // are one directory arriving under four ordinary-looking absolute spellings, and it
+  // contains every protected path there could be.
+  if (isFilesystemRoot(me)) {
+    return row('refuse', `refuses ${p}: it resolves to the filesystem root (/), which is not a unit's workspace — it is every checkout, every worktree and everything else on the machine. No unit owns it and nothing here removes it`)
+  }
+
+  // Decision 3, enforced: the orchestrator's checkout is not a unit's workspace and a
+  // unit's workspace is not the orchestrator's checkout. It follows that the reap may
+  // never touch it — and this repo's own 2026-07-26 incident is what makes the rule
+  // explicit rather than assumed.
+  for (const guarded of arr(protectedPaths).filter((g) => !unrecorded(g))) {
+    const g = identify(norm(guarded))
+    if (!isObject(g) || !g.resolved) {
+      return row('refuse', `refuses ${p}: the protected path ${norm(guarded)} will not resolve on disk — ${isObject(g) ? g.reason : 'no identity was returned'}, so nothing can be shown to be a different tree from the orchestrator's checkout`)
+    }
+    if (collides(me, g)) {
+      const via = me.real !== me.recorded || g.real !== norm(guarded) ? ` — ${me.real} and ${g.real} are one tree under two spellings` : ''
+      return row('refuse', `refuses ${p}: it is, contains, or sits inside the orchestrator's own checkout (${norm(guarded)})${via}. A workspace belongs to a unit; the orchestrator's tree belongs to no unit, and removing it would take the run with it`)
+    }
+  }
+
+  // A manifest that gives one tree to two units is corrupt — `run-state.mjs validate`
+  // already calls it an error (ADR 0001 decision 3). Keying by path and letting the last
+  // claimant win drops the other one silently, and the dropped claimant is exactly the unit
+  // whose work may be sitting in the tree. Refusing is the only answer that cannot be wrong.
+  const owners = arr(claimants).filter((u) => isObject(u) && nonEmpty(u.id)).map((u) => u.id)
+  if (owners.length > 1) {
+    return row('refuse', `refuses ${p}: units ${owners.join(', ')} all claim this workspace, so the manifest does not say whose work is in it — a workspace belongs to ONE unit, and \`run-state.mjs validate\` refuses this state. Nothing here is removed on an ambiguous claim; fix the manifest, then re-run`)
+  }
+
+  const o = isObject(observation) ? observation : {}
+  if (!o.exists) return row('absent', `nothing at ${p} — recorded but not on disk (already removed, or the run never created it). Reported rather than counted as a reap`)
+
+  if (unit && unitHoldsWorkspace(unit)) {
+    return row('preserve', `${id} still holds this workspace — it has not been delivered or handed back (status ${unit.status ?? 'queued'}${isObject(unit.delivery) && unit.delivery.outcome ? `, delivery ${unit.delivery.outcome}` : ''}). A dead spawn's replacement resumes here`)
+  }
+
+  // A LIVE PROCESS is the one hazard every other check here is blind to. The rest of this
+  // ladder reads the tree's *contents* — clean, published, owned — and a tree can satisfy
+  // all of it while an agent is mid-run inside it. Removing it then does not lose committed
+  // work; it destroys work in flight, and it does so silently from the reaper's side.
+  //
+  // fmm-express epic-894: the orchestrator pre-authorized an agent to keep running repeat
+  // measurements, read its interim report as terminal, and ran `reap --apply`. The tree was
+  // clean and its unit delivered, so the ladder said REAP. Git de-registered the worktree and
+  // half-deleted node_modules under a live Playwright worker — one run collapsed with 36
+  // `worker process exited unexpectedly`, the next could not start at all, and the crash
+  // produced a red mark on a test that read as a real regression until the agent opened the
+  // JSON. That near-miss is the cost: a destroyed measurement can also FABRICATE evidence.
+  //
+  // Preserve rather than warn: this is the same "uncertainty never authorizes cleanup" rule
+  // the Git-ownership checks below apply. An unreadable process table preserves too.
+  if (arr(o.liveProcesses).length) {
+    const n = o.liveProcesses.length
+    return row('preserve', `${n} process${n === 1 ? ' is' : 'es are'} still running inside ${p} (${o.liveProcesses.slice(0, 3).join(', ')}${n > 3 ? `, +${n - 3} more` : ''}). A clean, published tree can still have an agent mid-run in it; removing it destroys work in flight rather than work on disk. Wait for the agent to report done AND go idle, then re-run`)
+  }
+  // `unavailable` (no lsof on this platform) deliberately does NOT preserve — see
+  // liveProcessesIn. `unreadable` (lsof present, call failed) does.
+  if (o.liveProcesses === 'unreadable') {
+    return row('preserve', `could not determine whether any process is running inside ${p}, so it cannot be shown to be idle — the process table is as load-bearing as the Git state here, and uncertainty never authorizes cleanup`)
+  }
+
+  if (!o.readable) {
+    return row('preserve', `git could not be read at ${p}, so nothing here can be shown to be published — unreadable is not empty`)
+  }
+
+  // A producer may isolate itself by replacing a linked-worktree pointer with an embedded
+  // standalone Git directory (`.git-local`, `.pi-git`, or any equivalent). The tree can be
+  // clean and published while no longer belonging to the orchestrator repo's worktree set;
+  // sending it to `git worktree remove` then fails late with an opaque validation error.
+  // Preserve it at planning time. Cleanup is intentionally reversible and remains human-
+  // visible: move the standalone clone aside, prune the stale parent registration, then
+  // send the moved clone to Trash after checking this same publication evidence.
+  if (requireGitOwnership && (!nonEmpty(orchestratorGitCommonDir) || !nonEmpty(o.gitCommonDir))) {
+    return row('preserve', `Git ownership could not be established for ${p} (workspace common dir ${o.gitCommonDir ?? 'unreadable'}, orchestrator common dir ${orchestratorGitCommonDir ?? 'unreadable'}), so the orchestrator cannot prove \`git worktree remove\` owns this path. Resolve both with \`git rev-parse --path-format=absolute --git-common-dir\`; uncertainty never authorizes cleanup`)
+  }
+  if (nonEmpty(orchestratorGitCommonDir) && nonEmpty(o.gitCommonDir)
+    && path.resolve(o.gitCommonDir) !== path.resolve(orchestratorGitCommonDir)) {
+    return row('preserve', `clean published workspace is now a standalone Git checkout in a different Git object store (${o.gitCommonDir}), so the orchestrator repo cannot remove it with \`git worktree remove\`. Move it aside, prune the stale parent worktree registration, then send the moved clone to Trash after rechecking publication; never force-remove or raw-delete it`)
+  }
+
+  const held = []
+  if (arr(o.dirty).length) held.push(`${o.dirty.length} uncommitted change${o.dirty.length === 1 ? '' : 's'}`)
+  if (arr(o.untracked).length) held.push(`${o.untracked.length} untracked file${o.untracked.length === 1 ? '' : 's'}`)
+  if (arr(o.unpushed).length) held.push(`${o.unpushed.length} commit${o.unpushed.length === 1 ? '' : 's'} on no remote (unpushed)`)
+  if (held.length) {
+    return row('preserve', `holds unpublished work: ${held.join(', ')}. Push or salvage it first — this is the one rule that never bends`)
+  }
+
+  return row('reap', `clean and fully published${o.branch ? ` (branch ${o.branch})` : ''}, and its unit is ${id ? 'delivered or handed back' : 'no longer in the roster'} — safe to remove`)
+}
+
+// ---- the plan ----
+
+// Reads the manifest-recorded paths AND the worktrees actually on disk, because those two
+// sets differ in exactly the case that matters: a session that died before recording the
+// path it had already created. A manifest walk alone leaves those orphans forever; a disk
+// walk alone loses the unit each path belongs to.
+// `knownWorktrees` distinguishes three states on purpose. An array is a listing that was
+// taken (empty = looked, found none); `null`/omitted means NO listing was taken or it could
+// not be read — which is reported as such, never as an empty disk.
+export function planReap(manifest = {}, { orchestratorCheckout = null, orchestratorGitCommonDir = null, requireGitOwnership = false, knownWorktrees = null, observe = observeWorkspace, identify = pathIdentity } = {}) {
+  const m = isObject(manifest) ? manifest : {}
+  const units = arr(m.units).filter((u) => isObject(u) && nonEmpty(u.id))
+
+  // One identity per distinct spelling, computed once: every guard below decides on the
+  // tree a path names rather than on the text of the path.
+  const cache = new Map()
+  const idOf = (p) => {
+    const k = norm(p)
+    if (!cache.has(k)) cache.set(k, identify(k))
+    return cache.get(k)
+  }
+  // A tree nobody can identify still needs a stable key, and it must never collide with
+  // another unidentifiable one — two unresolvable paths are not known to be the same tree.
+  const keyOf = (p) => {
+    const ident = idOf(p)
+    return isObject(ident) && ident.resolved ? ident.real : `unresolved:${norm(p)}`
+  }
+
+  // The run-level checkout is the orchestrator's own tree under `workspaceMode: worktree`.
+  // It is protected here for the same reason the primary checkout is: it belongs to no
+  // unit, and the handoff removes it separately, last, after every branch is pushed.
+  // Filtered on `unrecorded`, not on `nonEmpty`: a run-level `workspacePath` of `42` was
+  // dropped here outright, and one of `/` survived the filter only to be `norm`ed to `''`
+  // and dropped by the `nonEmpty` filters downstream. Either way the run's own checkout
+  // stopped being protected while the manifest still named it. A guard nobody can read now
+  // reaches `reapDecision` and refuses every candidate, which is the fail-closed answer.
+  const protectedPaths = [orchestratorCheckout, m.workspacePath].filter((p) => !unrecorded(p)).map(norm)
+
+  // Claims, keyed by identity rather than by spelling — so two spellings of one tree are
+  // one row with two claimants (ambiguous, refused), not two rows that each half-decide.
+  const claims = new Map()
+  const claim = (p, unit) => {
+    const key = keyOf(p)
+    if (!claims.has(key)) claims.set(key, { path: norm(p), units: [] })
+    if (unit) claims.get(key).units.push(unit)
+    return claims.get(key)
+  }
+  for (const u of units) {
+    // Same rule as everywhere else: a unit that recorded NOTHING has no tree to claim; a
+    // unit that recorded something unreadable does, and dropping its claim silently would
+    // leave that tree unowned — collectable as an orphan by a sweep that never heard of it.
+    if (unrecorded(u.workspacePath)) continue
+    claim(u.workspacePath, u)
+  }
+
+  // Orphans: a worktree on disk under this run's workspace root that no unit claims.
+  const scope = sweepScope(m, { identify: idOf, protectedPaths })
+  const listed = Array.isArray(knownWorktrees)
+  const onDisk = arr(knownWorktrees).filter((p) => !unrecorded(p)).map(norm)
+  let collected = 0
+  let unexamined = 0
+  let unidentified = 0
+  for (const wt of onDisk) {
+    if (claims.has(keyOf(wt))) continue
+    const ident = idOf(wt)
+    // A tree whose identity will not resolve can be placed neither INSIDE the scope nor
+    // outside it. Skipping it answered "outside" and dropped the row, so with no protected
+    // path configured the plan reported a sweep that ran and said nothing whatever about a
+    // tree it could not look at — #586 NOTE-1 one row down. Worse, the silence was
+    // conditional: with a protected path, `collides` fails closed on an unresolved identity
+    // and the same input DID produce a row. It gets one either way now, and `reapDecision`
+    // refuses it on the same rule every other unidentifiable path meets.
+    if (!isObject(ident) || !ident.resolved) {
+      claim(wt, null)
+      unidentified++
+      continue
+    }
+    const isProtected = protectedPaths.some((g) => collides(ident, idOf(g)))
+    const underRoot = Boolean(scope.ok && contains(scope.id.real, ident.real))
+    if (!isProtected && !underRoot) {
+      // Skipped because it is out of scope (a scope IS established and this sits outside
+      // it), or because there is no scope to compare it to. Only the second is a failure
+      // to look.
+      if (!scope.ok) unexamined++
+      continue
+    }
+    claim(wt, null)
+    if (!isProtected) collected++
+  }
+
+  // "Nothing to collect" and "I could not look" are different answers, and reporting them
+  // identically is what keeps orphans invisible (#586 NOTE-1). Same shape as
+  // `record-gate-result`: a sweep that did not run owes a REASON.
+  const collection = !listed
+    ? {
+      ran: false,
+      scanned: 0,
+      collected: 0,
+      unexamined: 0,
+      unidentified: 0,
+      reason: 'no `git worktree list` result was available, so nothing outside the manifest was examined — the trees a dead session left behind are exactly the ones the manifest does not name',
+    }
+    : !scope.ok
+      ? {
+        ran: false,
+        scanned: onDisk.length,
+        collected: 0,
+        unexamined,
+        unidentified,
+        reason: `this run's workspace root could not be established — ${scope.reason}. ${unexamined} worktree${unexamined === 1 ? '' : 's'} on disk ${unexamined === 1 ? 'was' : 'were'} never examined for orphans. This is "could not look", not "all clear": declare the scope with \`run-state.mjs set <slug> workspaceRoot <abs-path>\` (or record units[].workspacePath as workspaces are handed out), and read \`git worktree list\` by hand meanwhile`,
+      }
+      : { ran: true, scanned: onDisk.length, collected, unexamined: 0, unidentified, reason: null }
+
+  const decisions = [...claims.values()].map(({ path: p, units: owners }) => reapDecision({
+    path: p,
+    unit: owners[0] ?? null,
+    claimants: owners,
+    observation: observe(p),
+    protectedPaths,
+    orchestratorGitCommonDir,
+    requireGitOwnership,
+    identify: idOf,
+  }))
+
+  return {
+    root: scope.root,
+    protectedPaths,
+    collection,
+    decisions,
+    reapable: decisions.filter((d) => d.verdict === 'reap'),
+    preserved: decisions.filter((d) => d.verdict === 'preserve'),
+    refused: decisions.filter((d) => d.verdict === 'refuse'),
+    absent: decisions.filter((d) => d.verdict === 'absent'),
+  }
+}
+
+// The orphan sweep's SCOPE — the directory every one of this run's unit workspaces sits
+// under — decided rather than assumed. Returns `{ root, id, ok, reason }`; `ok: false` is a
+// "could not look", never a clean sweep, and it always names a reason.
+//
+// It used to be `dirname` of the FIRST recorded workspace path, which is arbitrary in one
+// direction and dangerous in the other. Arbitrary: with several recorded paths, the first
+// entry decides the scope for all of them and nothing checks that the rest agree.
+// Dangerous: `dirname` of a unit mis-recorded as the checkout itself is the repo's PARENT —
+// a directory holding every OTHER checkout on the machine, whose worktrees then rank as
+// this run's orphans. Only clean, fully-pushed trees could ever have been removed, so the
+// evidence rules bounded the blast radius; that is not the same as the scope being right.
+//
+// So, in order:
+//
+//   declared     `workspaceRoot` on the manifest is the run SAYING where its trees live.
+//                It wins outright — the recorded paths do not get a vote.
+//   inferred     the fallback, kept because a run whose paths were chosen by an older
+//                scheme still deserves its orphans collected. It now requires AGREEMENT:
+//                every recorded path must sit under one parent TREE (two spellings of one
+//                directory agree; two directories do not). Disagreement yields no scope
+//                rather than the first entry's, which reads downstream as "could not look".
+//   bounded      whichever way it arrived, a root that is, contains, or sits inside a
+//                protected tree is refused. Declared does not mean unchecked: a run may no
+//                more declare `/` than infer the repo's parent.
+export function sweepScope(manifest, { identify = pathIdentity, protectedPaths = [] } = {}) {
+  const m = isObject(manifest) ? manifest : {}
+  const no = (root, reason) => ({ root, id: null, ok: false, reason })
+
+  // `unrecorded`, not `nonEmpty`, and `=== null`, not falsy — both halves matter, and both
+  // were the same mistake. DECLARED is a question about presence; whether the declaration is
+  // usable is a separate question, answered below by `identify` and the bounds. Deciding
+  // presence off "did this normalize to something truthy" is what discarded a declared `42`,
+  // a declared `'   '` and a declared `/` alike and swept an INFERRED scope instead — the
+  // manifest's own words overruled by a guess, in the one direction that removes things.
+  // A declared root that will not resolve, or that IS the filesystem root, now falls out of
+  // the checks below as a refusal, which is where it belongs.
+  let root = unrecorded(m.workspaceRoot) ? null : norm(m.workspaceRoot)
+  if (root === null) {
+    const recorded = arr(m.units).map((u) => (isObject(u) ? u.workspacePath : null)).filter((p) => !unrecorded(p))
+    if (!recorded.length) {
+      return no(null, 'no unit on this manifest records a workspacePath and the run declares no workspaceRoot')
+    }
+    const parents = recorded.map((p) => norm(path.dirname(norm(p))))
+    // Keyed by identity, like every other compare in this file: `/tmp/run` and
+    // `/private/tmp/run` are one parent, and two unresolvable parents are never known to be.
+    const keys = new Set(parents.map((p) => {
+      const ident = identify(p)
+      return isObject(ident) && ident.resolved ? ident.real : `unresolved:${p}`
+    }))
+    if (keys.size !== 1) {
+      return no(null, `this run's ${recorded.length} recorded workspaces sit under ${keys.size} different parents (${[...new Set(parents)].join(', ')}), so none of them is the run's root — picking the first is picking one at random`)
+    }
+    root = parents[0]
+  }
+
+  const id = identify(root)
+  if (!isObject(id) || !id.resolved) {
+    return no(root, `${root} will not resolve on disk (${isObject(id) ? (id.reason ?? 'it resolved to no path at all') : 'no identity was returned'})`)
+  }
+  // Bounded on its own account first, because `/` is the one scope whose refusal must not
+  // depend on a protected path being configured — and because `/`, `//`, `/.`, `/..` and a
+  // symlink to `/` are five spellings of it, only the first two of which look alarming.
+  if (isFilesystemRoot(id)) {
+    return no(root, `${root} resolves to the filesystem root (/), which holds every checkout and every worktree on the machine — a scope of / proposes all of them as this run's orphans. A run may no more declare / than infer the repo's parent`)
+  }
+  for (const guarded of arr(protectedPaths).filter((g) => !unrecorded(g))) {
+    if (collides(id, identify(norm(guarded)))) {
+      return no(root, `${root} is, contains, or sits inside the orchestrator's checkout (${norm(guarded)}) — a scope holding the checkout holds every other checkout beside it too, and their worktrees are not this run's orphans`)
+    }
+  }
+  return { root, id, ok: true, reason: null }
+}
+
+// What root a manifest names, with no judgement about whether it is usable. `sweepScope` is
+// what the reap decides on; this stays for callers that only want the path.
+export function runWorkspaceRoot(manifest, opts = {}) {
+  return sweepScope(manifest, opts).root
+}
+
+// ---- CLI ----
+
+// `null`, not `[]`, when git could not answer: an empty array is the claim that the disk
+// was read and held nothing, which is the conflation this whole path exists to remove.
+export function listWorktrees(repoDir) {
+  const r = git(['worktree', 'list', '--porcelain'], repoDir)
+  if (!r.ok) return null
+  return r.out.split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice('worktree '.length).trim())
+}
+
+export function renderPlan(plan) {
+  const c = plan.collection ?? { ran: false, reason: 'orphan collection reported nothing about itself' }
+  const out = [
+    'REAP PLAN',
+    // No reason of its own: `root` is null for several different causes — nothing recorded,
+    // recorded paths that disagree about their parent, a declaration that cannot be read —
+    // and this line used to assert the first one for all of them. A wrong reason on a
+    // correct refusal sends a human looking for a field that is not missing (#591 F3). The
+    // one true reason is already one line down, on the collection row.
+    `  workspace root: ${plan.root ?? '— not established; see orphan collection below'}`,
+    c.ran
+      ? `  orphan collection: ran over ${c.scanned} worktree${c.scanned === 1 ? '' : 's'} on disk; ${c.collected} orphan${c.collected === 1 ? '' : 's'} collected${c.unidentified ? `; ${c.unidentified} could not be identified and ${c.unidentified === 1 ? 'is' : 'are'} refused below` : ''}`
+      : `  orphan collection: NOT RUN — ${c.reason}`,
+  ]
+  // A guard that silently stopped guarding is worse than no guard: the plan would read
+  // exactly as it did before the liveness check existed. Say so once, at the top, where the
+  // reader is already deciding whether to trust the REAP rows.
+  if (plan.decisions.some((d) => d.liveProcesses === 'unavailable')) {
+    out.push('  live-process check: NOT AVAILABLE — `lsof` is not installed here, so a tree'
+      + ' holding a running agent cannot be told from an idle one. Rows below are decided on'
+      + ' tree contents alone. Confirm your agents are done before --apply.')
+  }
+  out.push('')
+  for (const d of plan.decisions) {
+    const mark = { reap: 'REAP    ', preserve: 'PRESERVE', refuse: 'REFUSE  ', absent: 'absent  ' }[d.verdict]
+    out.push(`  ${mark} ${d.path}${d.unit ? `  (${d.unit})` : '  (orphan — no unit claims it)'}`)
+    out.push(`           ${d.reason}`)
+  }
+  if (!plan.decisions.length) out.push('  nothing recorded and nothing on disk under this run — no workspaces to reap')
+  return out.join('\n')
+}
+
+// `listWorktrees` is a seam, and a narrow one on purpose. `--apply`'s exit fold —
+// `notRemoved ||` below — is unreachable through the real CLI: `git worktree list` always
+// includes the orchestrator's own checkout, which is always REFUSED, so `plan.refused`
+// carries exit 1 on every real invocation and a revert of the fold is invisible. Injecting
+// the listing is the smallest thing that lets a test reach the fold on the fold alone; the
+// worktree, git's refusal and `applyReap` all stay real (see `workspaces.test.mjs`).
+export function runCli(argv, { readManifestFor, cwd = process.cwd(), listWorktrees: listOnDisk = listWorktrees } = {}) {
+  const positional = []
+  const opts = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--apply') opts.apply = true
+    else if (a === '--json') opts.json = true
+    else if (a === '--repo-dir') opts.repoDir = argv[++i]
+    else if (a === '--file') opts.file = argv[++i]
+    else if (a === '--help' || a === '-h') opts.help = true
+    else if (a.startsWith('--')) { console.error(`workspaces: unrecognized flag ${a}`); return 2 }
+    else positional.push(a)
+  }
+  if (opts.help || !positional.length) {
+    console.log(`workspaces path <slug> <unitId> [--repo-dir DIR]
+workspaces reap <slug> [--apply] [--json] [--repo-dir DIR] [--file PATH]
+
+A workspace belongs to a unit, from its first producer spawn until the unit is
+delivered or handed back. It is PRESERVED ON DEATH and reaped only on success —
+branch pushed, nothing unpublished. \`reap\` plans by default and removes only with
+--apply; it refuses the orchestrator's own checkout outright.
+
+exit 0 = all clear · 1 = something preserved/refused, or --apply could not remove it
+     2 = usage · 3 = no manifest
+     4 = the orphan sweep could not run (nothing recorded to scope it, or no
+         \`git worktree list\`) — "could not look", never reported as "all clear"`)
+    return opts.help ? 0 : 2
+  }
+
+  const repoDir = opts.repoDir || cwd
+  const [cmd, slug, unitId] = positional
+
+  if (cmd === 'path') {
+    const top = git(['rev-parse', '--show-toplevel'], repoDir)
+    if (!top.ok) { console.error(`workspaces path: ${repoDir} is not a git repository`); return 2 }
+    if (!nonEmpty(slug) || !nonEmpty(unitId)) { console.error('workspaces path: <slug> and <unitId> are both required'); return 2 }
+    console.log(unitWorkspacePathFor(top.out.trim(), slug, unitId))
+    return 0
+  }
+
+  if (cmd !== 'reap') { console.error(`workspaces: unknown command ${cmd}`); return 2 }
+
+  const manifest = readManifestFor ? readManifestFor(slug, opts) : null
+  if (manifest == null) {
+    console.error(`workspaces reap: no manifest for ${slug} (absent is normal — the run dir is temp). Nothing recorded means nothing to reap BY PATH; check \`git worktree list\` by hand.`)
+    return 3
+  }
+  const top = git(['rev-parse', '--show-toplevel'], repoDir)
+  const common = git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoDir)
+  const plan = planReap(manifest, {
+    orchestratorCheckout: top.ok ? top.out.trim() : repoDir,
+    orchestratorGitCommonDir: common.ok ? common.out.trim() : null,
+    requireGitOwnership: true,
+    knownWorktrees: listOnDisk(repoDir),
+  })
+  if (!opts.json) console.log(renderPlan(plan))
+
+  let notRemoved = 0
+  let applied = null
+  if (opts.apply) {
+    applied = applyReapResult(plan, repoDir, { log: opts.json ? () => {} : console.log })
+    notRemoved = applied.removalFailures.length
+  } else if (plan.reapable.length && !opts.json) {
+    console.log(`\n  ${plan.reapable.length} removable — re-run with --apply to remove them.`)
+  }
+  if (opts.json) console.log(JSON.stringify(applied ?? { collection: plan.collection, decisions: plan.decisions, removed: [], remaining: [...plan.preserved, ...plan.refused].map((row) => row.path), removalFailures: [] }, null, 2))
+  // 4 outranks 1 — deliberately, and this is the whole reason it is a code and not just a
+  // line of output. The orchestrator's own checkout is in `git worktree list` on every real
+  // invocation and is always REFUSED, so 1 fires almost always; a "could not look" ranked
+  // under it would never once be visible in the exit status, and the fix would live only in
+  // prose nobody reads. Both codes mean "read the rows"; 4 additionally means the disk was
+  // never swept, which is the one thing the rows themselves cannot tell you.
+  if (!plan.collection.ran) return 4
+  if (notRemoved || plan.preserved.length || plan.refused.length) return 1
+  return 0
+}
+
+// `--apply` is the only step in this loop that touches the disk, and a removal git REFUSED
+// is not a removal. It used to be reported on stdout and nowhere else, so a caller scripting
+// `reap --apply` read exit 0 over a printed FAILED — the same defect shape as a status-only
+// reap calling an unpushed tree clean: a destructive operation reporting success it did not
+// have. The count folds into exit 1 rather than taking a new code, because 1 already means
+// "something was left in place, read the rows before touching anything by hand", and that is
+// precisely what a refused removal is.
+//
+// Never `--force`, and never fall back to `fs.rm`: `git worktree remove` refusing is the
+// last guard between this loop and work that exists nowhere else, and the caller who reads
+// the row is better placed than this script to decide what the refusal meant.
+export function applyReapResult(plan, repoDir, { remove = (p, cwd) => git(['worktree', 'remove', p], cwd), log = console.log } = {}) {
+  const removed = []
+  const removalFailures = []
+  for (const d of arr(isObject(plan) ? plan.reapable : null)) {
+    const r = remove(d.path, repoDir)
+    if (isObject(r) && r.ok) { removed.push(d.path); log(`removed ${d.path}`); continue }
+    const error = (isObject(r) && r.error?.message) || 'git refused'
+    removalFailures.push({ path: d.path, error })
+    log(`FAILED to remove ${d.path} — ${error}; left in place`)
+  }
+  const remaining = [
+    ...arr(plan?.preserved).map((row) => row.path),
+    ...arr(plan?.refused).map((row) => row.path),
+    ...removalFailures.map((row) => row.path),
+  ]
+  return { collection: structuredClone(plan?.collection ?? null), decisions: structuredClone(arr(plan?.decisions)), removed, remaining, removalFailures }
+}
+
+export function applyReap(plan, repoDir, options = {}) {
+  return applyReapResult(plan, repoDir, options).removalFailures.length
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(runCli(process.argv.slice(2), {
+    readManifestFor: (slug, opts) => {
+      try { return readManifest(fileFor(slug, opts)) } catch { return null }
+    },
+  }))
+}