@ran-sh/dsh-crew 1.9.1 → 1.10.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "1.9.1",
+  "version": "1.10.1",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "1.9.1",
+  "version": "1.10.1",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {
@@ -29,7 +29,8 @@
     "build:client": "tsdown src/client/entry.tsx --format cjs --platform browser --target es2022 --tsconfig tsconfig.client.json --deps.never-bundle react --deps.never-bundle react/jsx-runtime --deps.never-bundle react-dom --deps.never-bundle react-dom/client --out-dir .client-build --clean --logLevel warn && tsdown src/client/quick-entry.tsx --format cjs --platform browser --target es2022 --tsconfig tsconfig.client.json --deps.never-bundle react --deps.never-bundle react/jsx-runtime --deps.never-bundle react-dom --deps.never-bundle react-dom/client --out-dir .client-build --no-clean --logLevel warn && node scripts/build-client.mjs",
     "verify:npm-install": "node scripts/verify-npm-install.mjs",
     "verify:npm-install:official": "node scripts/verify-npm-install.mjs --with-official-dsh",
-    "verify:official-bridge": "node scripts/verify-official-bridge-e2e.mjs --diagnostic-only"
+    "verify:official-bridge": "node scripts/verify-official-bridge-e2e.mjs --diagnostic-only",
+    "test": "node --test \"test/*.test.mjs\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.4",

package/src/history/service.mjs

@@ -8,7 +8,12 @@ import { readHistoryState, writeHistoryState, historyPending, publicHistoryState
 import { readSessionOrigins } from '../session-origins.mjs';
 import { defaultWorktreeRoot } from '../workspace-isolation.mjs';
 
-export function createHistoryService({ crewRoot, agents, persistence, runtimeId, launch, now = Date.now }) {
+// `readOrigins` is injectable because the provenance ledger it reads by default
+// is machine-global, and the plan revision hashes the whole set: anything that
+// appends to that file between a preview and its execute invalidates the plan.
+// That is correct in production, where the ledger is this machine's own record,
+// but a caller that cannot control the ledger cannot control its own revisions.
+export function createHistoryService({ crewRoot, agents, persistence, runtimeId, launch, now = Date.now, readOrigins = readSessionOrigins }) {
   const gate = installHistoryAdmissionGate(agents, () => historyPending(crewRoot));
   const plans = new Map();
   let entering = false;
@@ -67,7 +72,7 @@ export function createHistoryService({ crewRoot, agents, persistence, runtimeId,
     });
     // A retained child keeps its ancestor chain; do not leave a newer fork orphaned.
     const workspaces = Object.entries(store.tables.workspaces).map(([id, row]) => ({ id, ...row }));
-    const crewSessionIds = [...readSessionOrigins()];
+    const crewSessionIds = [...readOrigins()];
     const crewSet = new Set(crewSessionIds);
     for (const row of sessions) if (crewSet.has(row.id)) row.crew = true;
     // The isolated-workspace marker: the hub stamps every worktree session with a

package/src/hub/entry.mjs

@@ -10,7 +10,7 @@
 import { apply as applyHub, inject, name, WorkerRegistry } from './index.mjs';
 import { getHubRuntimeIdentity } from '../runtime-identity.mjs';
 import { getProcessAdaptiveHealthStore } from '../adaptive-routing.mjs';
-import { claimReleaseInUse } from '../release-in-use.mjs';
+import { claimReleaseInUse, clearReleaseClaim } from '../release-in-use.mjs';
 
 const RUNTIME_PATH = '/_dsh/dsh-crew/runtime';
 const ADAPTIVE_OBSERVER_INSTALLED = Symbol.for('@ran-sh/dsh-crew/adaptive-observer-installed');
@@ -97,8 +97,37 @@ export async function apply(ctx) {
   // modules lazily with a cache-busting query, so deleting the release under a
   // running process would break those routes with no way to recover but a
   // restart. Retention reads these claims and leaves a live release alone.
-  claimReleaseInUse();
-  registerRuntimeEndpoint(ctx);
-  installAdaptiveHealthObserver();
-  return applyHub(ctx);
+  //
+  // A claim that could not be written is worth saying out loud: retention cannot
+  // see an unclaimed release, so this process is then the one that a later update
+  // may delete from under itself.
+  const claimFile = claimReleaseInUse();
+  if (!claimFile) {
+    ctx.logger?.warn?.('dsh-crew: could not record this release as in use; a later update may prune it while this Hub is running');
+  }
+  try {
+    registerRuntimeEndpoint(ctx);
+    installAdaptiveHealthObserver();
+    const disposeHub = await applyHub(ctx);
+    // Release the claim on disposal, and only once teardown has actually
+    // finished: clearing it first would say "this release is unused" while the
+    // Hub is still running. Nothing else may remove a claim file — the reader
+    // deliberately never unlinks one, because it cannot tell its object from a
+    // successor published at the same name — but the process that owns a claim
+    // may remove its own, and it removes *this* claim rather than any other this
+    // process happens to hold.
+    return async () => {
+      try { if (typeof disposeHub === 'function') await disposeHub(); }
+      // Only a claim this mount actually holds. A null handle means the claim was
+      // never acquired, and clearing something anyway could remove a sibling
+      // mount's protection.
+      finally { if (claimFile) { try { clearReleaseClaim({ file: claimFile }); } catch { /* best effort */ } } }
+    };
+  } catch (error) {
+    // No disposer will ever be returned for a failed mount, so the claim has to
+    // be released here or the release stays pinned by a process that never
+    // provided anything.
+    if (claimFile) { try { clearReleaseClaim({ file: claimFile }); } catch { /* best effort */ } }
+    throw error;
+  }
 }

package/src/install/npx-lifecycle.mjs

@@ -42,7 +42,7 @@ import { homedir } from 'node:os';
 import * as realInstaller from './install.mjs';
 import { samePayloadContent, capturePayloadContent } from './payload-content.mjs';
 import { crewDshHome, crewProfileDir } from './install.mjs';
-import { liveReleaseClaims } from '../release-in-use.mjs';
+import { releaseClaimsState } from '../release-in-use.mjs';
 import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration, migrateCrewDshRuntime, installDshInto, restoreRetainedRuntime, crewDshRuntimeRoot, payloadDshVersion, TARGET_DSH_VERSION } from '../dsh-cli-runtime.mjs';
 import {
   ensureOfficialWebIntegration,
@@ -1084,14 +1084,26 @@ const STALE_INCOMPLETE_MS = 24 * 60 * 60 * 1000;
 function gcOldReleases({ home, keep = KEEP_RELEASES, protect = null }) {
   const pointer = readCurrentPointer({ home });
   const releasesDir = crewReleasesDir({ home });
-  if (!existsSync(releasesDir)) return;
+  if (!existsSync(releasesDir)) return [];
   const removed = [];
   // A running Hub keeps executing the release it started from and re-reads
   // several modules from disk on every request, so removing that release breaks
   // those routes with no recovery but a restart. Protect what live processes
   // claim, not just what the pointer names.
-  const claimed = liveReleaseClaims({ home }).map((dir) => resolve(dir));
-  const live = new Set([...(protect ? [resolve(protect)] : []), ...claimed]);
+  //
+  // Liveness has to be known, not merely unrefuted: if the claim directory
+  // cannot be read, "no live claims" is an absence of evidence, and deleting on
+  // it reproduces the outage this protection exists to prevent. Pruning is
+  // optional and a skipped pass costs disk; guessing wrong costs a broken Hub.
+  const claims = releaseClaimsState({ home });
+  if (!claims.reliable) {
+    // Say so rather than passing over it in silence: nothing is pruned until the
+    // claim directory can be read again, and an operator who never hears about
+    // that finds out when the disk fills.
+    process.emitWarning(`dsh-crew: release liveness could not be read (${claims.error ?? 'unknown cause'}); skipping release pruning this pass`);
+    return removed;
+  }
+  const live = new Set([...(protect ? [resolve(protect)] : []), ...claims.live.map((dir) => resolve(dir))]);
   const dirs = readdirSync(releasesDir)
     .map((name) => join(releasesDir, name))
     .filter((dir) => (!pointer || dir !== pointer.path) && !live.has(resolve(dir)));

package/src/release-in-use.mjs

@@ -16,13 +16,21 @@
 // release with a live claim. Liveness is decided by the pid, not by the file, so
 // a process that dies without cleaning up cannot pin a release forever.
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const IN_USE_DIRNAME = 'in-use';
 
+// A claim file is `<pid>.json` or `<pid>-<nonce>.json`. The PID alone is not
+// enough to identify a claim: two mounts inside one process would publish to the
+// same pathname, and whichever disposed first would remove the other's
+// protection. A claim is owned by the mount that wrote it, so it needs a name
+// that says which one that was.
+const CLAIM_NAME_RE = /^(\d+)(?:-[0-9a-f]+)?\.json$/;
+
 export function releaseInUseDir({ home = homedir() } = {}) {
   return join(home, '.config', 'dsh-crew', 'app', IN_USE_DIRNAME);
 }
@@ -55,8 +63,13 @@ function isAlive(pid) {
 
 /**
  * Record that this process is running `releasePath`. Best effort: failing to
- * claim must never stop the Hub from starting, because the cost of a missed
- * claim is a possible retention of one extra release.
+ * claim must never stop the Hub from starting.
+ *
+ * A null return is a real degradation, not a footnote. Retention cannot see a
+ * release that was never claimed, so an unclaimable release is one that a later
+ * update may delete from under this process — the 500-answering routes this
+ * module exists to prevent. Callers should surface it; `releaseClaimsState`
+ * gives retention the matching fail-closed signal.
  */
 export function claimReleaseInUse({ moduleUrl = import.meta.url, releasePath, home = homedir(), pid = process.pid, now = Date.now() } = {}) {
   try {
@@ -64,47 +77,122 @@ export function claimReleaseInUse({ moduleUrl = import.meta.url, releasePath, ho
     if (!target) return null;
     const dir = releaseInUseDir({ home });
     mkdirSync(dir, { recursive: true });
-    const file = join(dir, `${pid}.json`);
-    writeFileSync(file, JSON.stringify({ pid, release: resolve(target), claimed_at: now }) + '\n');
+    // The nonce makes this claim the property of this call. Clearing by PID would
+    // let one mount remove a sibling mount's only protection.
+    const nonce = randomBytes(8).toString('hex');
+    const file = join(dir, `${pid}-${nonce}.json`);
+    // Write then rename: a reader that lists the directory can otherwise see this
+    // filename while its JSON is still empty or half-written, and an unparseable
+    // claim is indistinguishable from a dead one.
+    const pending = `${file}.tmp`;
+    writeFileSync(pending, JSON.stringify({ pid, nonce, release: resolve(target), claimed_at: now }) + '\n');
+    renameSync(pending, file);
     return file;
   } catch { return null; }
 }
 
+/** The unbranded per-PID claim path, as written by releases before claims were per-mount. */
 export function releaseClaimFile({ home = homedir(), pid = process.pid } = {}) {
   return join(releaseInUseDir({ home }), `${pid}.json`);
 }
 
 export function releaseClaimInUse({ home = homedir(), pid = process.pid } = {}) {
-  const file = releaseClaimFile({ home, pid });
-  return existsSync(file) || false;
+  let names;
+  try { names = readdirSync(releaseInUseDir({ home })); } catch { return false; }
+  return names.some((name) => CLAIM_NAME_RE.exec(name)?.[1] === String(pid));
+}
+
+/**
+ * Remove the claim whose handle `claimReleaseInUse` returned.
+ *
+ * A missing handle is not permission to remove something: without one there is
+ * no way to know which claim this caller owns, and guessing by PID can remove a
+ * sibling mount's protection. Legacy unbranded claims are removed by
+ * `clearLegacyReleaseClaim`, which says so in its name.
+ */
+export function clearReleaseClaim({ file = null } = {}) {
+  if (!file) return false;
+  try { rmSync(file, { force: true }); return true; } catch { return false; }
 }
 
-export function clearReleaseClaim({ home = homedir(), pid = process.pid } = {}) {
+/**
+ * Remove the unbranded `<pid>.json` claim written by releases before claims were
+ * per-mount. Separate from `clearReleaseClaim` because it can take a claim this
+ * caller did not write, and that should never happen by falling through a
+ * missing argument.
+ */
+export function clearLegacyReleaseClaim({ home = homedir(), pid = process.pid } = {}) {
   try { rmSync(releaseClaimFile({ home, pid }), { force: true }); return true; } catch { return false; }
 }
 
 /**
- * Releases currently held by a live process. Dead claims are removed as they are
- * encountered, so the directory cannot accumulate stale files.
+ * Releases currently held by a live process, plus whether that answer is
+ * trustworthy.
+ *
+ * `reliable: false` means liveness could not be determined, so an empty `live`
+ * list is not evidence that nothing is running. A caller that deletes releases
+ * must treat unknown as "do not delete": reading an unreadable claim directory
+ * as "no claims" is exactly how a release disappears from under a running Hub,
+ * and the damage is to the process, not to the files.
+ *
+ * Nothing is deleted here. A claim is only ever a protection, so a reaper that
+ * unlinks one has to be certain the object it inspected is still the object it
+ * is removing — and it cannot be, because the pathname outlives the claim and a
+ * process restarting with a reused PID publishes a new file at the same one.
+ * Checking liveness and then unlinking is a check-then-act over a name, and
+ * losing that race deletes a live process's protection. Stale files therefore
+ * stay; a Hub clears its own claim on a clean shutdown, and one file per
+ * hard-killed process is not worth a race over a safety mechanism.
  */
-export function liveReleaseClaims({ home = homedir(), alive = isAlive } = {}) {
+export function releaseClaimsState({ home = homedir(), alive = isAlive } = {}) {
   const dir = releaseInUseDir({ home });
   let names;
-  // A state directory that is unreadable — or replaced by a file — must read as
-  // "no claims" rather than throwing: this runs inside install, and failing it
-  // would block an update over a problem that only affects pruning.
-  try { names = readdirSync(dir); } catch { return []; }
+  try { names = readdirSync(dir); } catch (error) {
+    // A directory that does not exist yet reliably holds no claims; any other
+    // failure — permissions, a file where the directory should be — does not.
+    if (error?.code === 'ENOENT') return { live: [], reliable: true };
+    return { live: [], reliable: false, error: String(error?.message ?? error) };
+  }
   const live = [];
+  let unknown = null;
   for (const name of names) {
     if (!name.endsWith('.json')) continue;
     const file = join(dir, name);
-    let record;
-    try { record = JSON.parse(readFileSync(file, 'utf8')); } catch { record = null; }
-    if (record && Number.isInteger(record.pid) && typeof record.release === 'string' && alive(record.pid)) {
-      live.push(resolve(record.release));
+    // The filename carries the PID, and the name is complete before any content
+    // exists — so a torn write still says whose claim it was, which is what
+    // keeps one old unusable file from disabling pruning forever.
+    const pidFromName = CLAIM_NAME_RE.exec(name) ? Number.parseInt(name, 10) : null;
+
+    let parsed = null;
+    try { parsed = JSON.parse(readFileSync(file, 'utf8')); } catch { parsed = null; }
+
+    const wellFormed = parsed && typeof parsed === 'object'
+      && Number.isInteger(parsed.pid) && parsed.pid > 0
+      && typeof parsed.release === 'string' && parsed.release !== ''
+      && parsed.pid === pidFromName;
+
+    if (wellFormed) {
+      // A well-formed claim for a process that is gone simply protects nothing;
+      // it is inert, not a reason to distrust the rest.
+      if (alive(parsed.pid)) live.push(resolve(parsed.release));
       continue;
     }
-    try { rmSync(file, { force: true }); } catch { /* best effort */ }
+
+    // Anything else is not evidence of a dead process. Syntax that happens to
+    // parse is not a schema: `{}` and `{"pid":123}` say nothing about liveness.
+    // The filename is the only identity left, and a claim whose named process is
+    // positively gone is inert for the same reason.
+    if (pidFromName !== null && !alive(pidFromName)) continue;
+    // No usable PID, or the PID may still be running. A reused PID is
+    // indistinguishable from the original here, so this stays unknown rather
+    // than guessing; that is a fail-closed condition, not a resolved one.
+    unknown ??= `unusable claim: ${file}`;
   }
-  return [...new Set(live)];
+  if (unknown) return { live: [...new Set(live)], reliable: false, error: unknown };
+  return { live: [...new Set(live)], reliable: true };
+}
+
+/** Releases currently held by a live process. See `releaseClaimsState`. */
+export function liveReleaseClaims(opts = {}) {
+  return releaseClaimsState(opts).live;
 }

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '1.9.1';
+export const RUNTIME_VERSION = '1.10.1';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/src/workspace-isolation.mjs

@@ -11,10 +11,10 @@
 // lock blocks cleanup.
 
 import { execFile } from 'node:child_process';
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
 import { readFile, lstat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, resolve, basename } from 'node:path';
+import { join, resolve, basename, dirname } from 'node:path';
 import { randomBytes, createHash } from 'node:crypto';
 import { promisify } from 'node:util';
 import { isSensitivePath, parseChanges, DIFF_LIMIT, GIT_TIMEOUT_MS } from './workspace-audit.mjs';
@@ -31,17 +31,22 @@ export const CANDIDATE_CAPTURE_FAILED = 'CANDIDATE_CAPTURE_FAILED';
 export const MAX_PARALLEL_CAP = 16;
 export const DEFAULT_MAX_PARALLEL = 3;
 // Worktree names read `Crew_YYYYMMDD_HHMMSS_<purpose>` so an operator can tell
-// from the directory alone when a job ran and what it was for. The legacy
-// prefix stays recognised as ours, so worktrees created by an earlier release
-// are still adopted and cleaned up rather than orphaned.
+// from the directory alone when a job ran and what it was for. Worktrees from
+// an earlier release used `dsh-crew-<job>-<hex>` and stay recognised, so old
+// trees are still adopted and cleaned up rather than orphaned.
+//
+// The shapes are matched exactly rather than by prefix, because the prefix
+// alone is not proof of ownership: cleanup `--force`-deletes what it adopts,
+// and a directory a user happened to name Crew_manual-testing or
+// dsh-crew-backup would go with its uncommitted contents.
 const WORKTREE_PREFIX = 'Crew_';
-const LEGACY_WORKTREE_PREFIXES = Object.freeze(['dsh-crew-']);
+const WORKTREE_NAME_RE = /^Crew_\d{8}_\d{6}_[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*(?:-\d+)?$/;
+const LEGACY_WORKTREE_RE = /^dsh-crew-[A-Za-z0-9._-]+-[0-9a-f]{8}$/;
 
 /** Whether a directory name is a worktree Crew created. */
 export function isCrewWorktreeName(name) {
   const value = String(name ?? '');
-  return value.startsWith(WORKTREE_PREFIX)
-    || LEGACY_WORKTREE_PREFIXES.some((prefix) => value.startsWith(prefix));
+  return WORKTREE_NAME_RE.test(value) || LEGACY_WORKTREE_RE.test(value);
 }
 
 async function defaultRunner(args, { cwd }) {
@@ -80,23 +85,27 @@ function stamp(at) {
     + `_${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
 
-/**
- * `Crew_<date>_<time>_<purpose>`, with a numeric suffix only when that name is
- * already taken. Parallel jobs can start inside the same second, so the suffix is
- * what keeps the name unique without putting random noise in every name.
- */
 /**
  * `Crew_<date>_<time>_<purpose>`, reserved by creating the directory.
  *
  * The reservation is a mkdir, not a lookup: two jobs starting in the same second
  * both probe before either has created anything, so a check-then-act name would
  * hand them the same path and one `git worktree add` would fail. mkdir
- * fails on EEXIST, which makes the suffix loop race-free.
+ * fails on EEXIST, which makes the suffix loop race-free, and a numeric suffix
+ * is added only when the name is already taken.
  */
-function reserveWorktreeDir({ root, purpose, at }) {
-  mkdirSync(root, { recursive: true });
+export function reserveWorktreeDir({ root, purpose, at }) {
+  try {
+    mkdirSync(root, { recursive: true });
+  } catch (error) {
+    return { ok: false, error: `cannot create worktree root: ${error?.message ?? error}` };
+  }
+  // Truncate before trimming. Trimming first lets a 32-character slice end on
+  // the separator it just created, and the resulting name fails
+  // `isCrewWorktreeName` — so Crew would create a worktree it no longer
+  // recognises as its own, and stale pruning would never adopt it again.
   const safe = String(purpose ?? 'job').replace(/[^A-Za-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '').slice(0, PURPOSE_MAX) || 'job';
+    .slice(0, PURPOSE_MAX).replace(/^-+|-+$/g, '') || 'job';
   const base = `${WORKTREE_PREFIX}${stamp(at)}_${safe}`;
   for (let n = 1; n <= 100; n += 1) {
     const name = n === 1 ? base : `${base}-${n}`;
@@ -114,6 +123,138 @@ export function defaultWorktreeRoot() {
   return join(tmpdir(), 'dsh-crew-worktrees');
 }
 
+// ---------- ownership record ----------
+//
+// A name is not proof that Crew made a worktree. `dsh-crew-backup-deadbeef`
+// satisfies the legacy grammar, and `detached` describes HEAD rather than who
+// created the tree, so both can be true of a worktree a user made — and cleanup
+// `--force` deletes what it adopts. Crew therefore records what it creates,
+// beside the worktrees it creates it in, and only ever adopts what a valid
+// record claims. Anything else that looks like a leftover is reported for a
+// human instead of removed.
+//
+// The record lives under the worktree root rather than in the Crew home so it
+// travels with the trees it describes: if the root is wiped, the trees are gone
+// with it and there is nothing left to adopt.
+//
+// A record is evidence only when it can be read and matches: its shape is
+// validated, its name has to be this worktree's name, and its repository has to
+// be the repository being scanned. An unreadable, truncated, malformed or
+// mismatched record reads as "not owned", which withholds deletion rather than
+// granting it — the one direction where being wrong is survivable.
+
+const OWNED_DIRNAME = '.crew-owned';
+const OWNED_SCHEMA = 2;
+// Stored inside the worktree's git administrative directory, which git destroys
+// with the worktree.
+const INCARNATION_FILE = 'crew-owned';
+
+function ownedMarkerPath(worktreePath) {
+  const abs = resolve(worktreePath);
+  return join(dirname(abs), OWNED_DIRNAME, `${basename(abs)}.json`);
+}
+
+/**
+ * Prove which *incarnation* of a worktree this is.
+ *
+ * A path can be reused. Git removes a worktree and later another one is created
+ * in the same place — same name, same repository — so a record keyed on those
+ * alone can be inherited by a successor that Crew never created, and inherited
+ * again after Crew's own cleanup if releasing the record failed. The worktree's
+ * git administrative directory does not have that problem: git deletes it along
+ * with the worktree, so a value kept there cannot outlive the tree it describes.
+ */
+async function gitDirOf(run, cwd) {
+  const abs = await runGit(run, ['rev-parse', '--path-format=absolute', '--git-dir'], { cwd });
+  if (abs.ok && abs.stdout.trim()) return resolve(abs.stdout.trim());
+  const rel = await runGit(run, ['rev-parse', '--git-dir'], { cwd });
+  if (!rel.ok || !rel.stdout.trim()) return null;
+  return resolve(cwd, rel.stdout.trim());
+}
+
+/** The nonce this worktree incarnation was stamped with, if any. */
+async function incarnationOf(run, worktreePath) {
+  const gitDir = await gitDirOf(run, worktreePath);
+  if (!gitDir) return null;
+  let nonce;
+  try { nonce = readFileSync(join(gitDir, INCARNATION_FILE), 'utf8').trim(); } catch { return null; }
+  return nonce ? { gitDir, nonce } : null;
+}
+
+/** Stamp a freshly created worktree so its record cannot be inherited later. */
+async function claimIncarnation(run, worktreePath) {
+  const gitDir = await gitDirOf(run, worktreePath);
+  if (!gitDir) return null;
+  const nonce = randomBytes(16).toString('hex');
+  try { writeFileSync(join(gitDir, INCARNATION_FILE), `${nonce}\n`); } catch { return null; }
+  return { gitDir, nonce };
+}
+
+function recordOwnership({ worktreePath, repo, incarnation, head, purpose, at }) {
+  const marker = ownedMarkerPath(worktreePath);
+  const record = {
+    schemaVersion: OWNED_SCHEMA,
+    name: basename(resolve(worktreePath)),
+    worktree: pathIdentity(worktreePath),
+    // Binding the record to a repository is what stops a stale record from
+    // licensing a delete for a worktree of some other repository that later
+    // occupies the same path. The identity is the git *common* directory, not
+    // `--show-toplevel`: that returns the linked worktree's own path when run
+    // inside one, so it names different directories for the same repository
+    // depending on where it is asked.
+    repo: pathIdentity(repo),
+    git_dir: pathIdentity(incarnation.gitDir),
+    nonce: incarnation.nonce,
+    // The revision Crew left the worktree at. An operator who commits or checks
+    // out something else has taken the worktree over, and moving HEAD is how
+    // that shows up: being on a branch is only one way to do it.
+    head,
+    purpose: purpose ?? null,
+    created_at: at ?? Date.now(),
+  };
+  try {
+    mkdirSync(dirname(marker), { recursive: true });
+    const pending = `${marker}.${process.pid}.tmp`;
+    writeFileSync(pending, JSON.stringify(record) + '\n');
+    renameSync(pending, marker);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function releaseOwnership({ worktreePath }) {
+  try { rmSync(ownedMarkerPath(worktreePath), { force: true }); return true; } catch { return false; }
+}
+
+/**
+ * The validated ownership record for `worktreePath`, or null when there is no
+ * usable evidence that Crew created *this* worktree in `repo`.
+ *
+ * This answers identity only — was it Crew's worktree? — and deliberately not
+ * state, which is a question for the caller: `head` and `detached` describe what
+ * the worktree looks like now, and a worktree whose operator has moved HEAD is
+ * still Crew's worktree, just no longer a disposable one. All of shape, name,
+ * path, repository and incarnation have to match; every failure reads as "not
+ * owned", which withholds deletion rather than granting it.
+ */
+function readOwnership({ worktreePath, repo, incarnation }) {
+  let raw;
+  try { raw = readFileSync(ownedMarkerPath(worktreePath), 'utf8'); } catch { return null; }
+  let record;
+  try { record = JSON.parse(raw); } catch { return null; }
+  if (!record || typeof record !== 'object' || record.schemaVersion !== OWNED_SCHEMA) return null;
+  if (typeof record.name !== 'string' || record.name !== basename(resolve(worktreePath))) return null;
+  if (typeof record.worktree !== 'string' || record.worktree !== pathIdentity(worktreePath)) return null;
+  // An unknown identity on either side cannot be matched, so it cannot be
+  // adopted: an unverifiable record is not evidence.
+  if (!repo || typeof record.repo !== 'string' || record.repo !== pathIdentity(repo)) return null;
+  if (!incarnation) return null;
+  if (typeof record.nonce !== 'string' || record.nonce !== incarnation.nonce) return null;
+  if (typeof record.git_dir !== 'string' || record.git_dir !== pathIdentity(incarnation.gitDir)) return null;
+  return record;
+}
+
 /**
  * Resolve repository root + HEAD. Dirty detection is advisory: inability to
  * read `git status` must not turn an otherwise valid repository into a hard
@@ -140,6 +281,10 @@ export async function inspectRepository({ cwd, git, runner } = {}) {
 
 export async function createIsolatedWorkspace({ cwd, jobId, purpose, baseRevision, at, root = defaultWorktreeRoot(), git } = {}) {
   const run = git ?? defaultRunner;
+  // A relative root would be resolved against this process's cwd for the
+  // mkdir reservation but against the repo root for the git invocation, so the
+  // two could land in different places. Anchor it once.
+  root = resolve(root);
   const repo = await inspectRepository({ cwd, git: run });
   if (!repo.ok) return { ok: false, reason: repo.reason, error: repo.error };
   const rev = baseRevision ?? repo.baseRevision;
@@ -148,11 +293,44 @@ export async function createIsolatedWorkspace({ cwd, jobId, purpose, baseRevisio
   const { dir, name } = reserved;
   const res = await runGit(run, ['worktree', 'add', '--detach', dir, rev], { cwd: repo.repoRoot });
   if (!res.ok) {
-    // Release the name so a retry is not blocked by an empty directory.
-    try { rmSync(dir, { recursive: true, force: true }); } catch {}
-    return { ok: false, reason: res.reason, error: res.error };
+    // A nonzero exit does not mean git did nothing: a failing post-checkout hook
+    // leaves the worktree registered and populated, and a transient Windows lock
+    // can defeat the unregister. Go through the same verified, retrying cleanup
+    // the normal path uses, and report a blocked reservation rather than
+    // pretending the name was released — a stranded registration makes every
+    // later attempt on this name fail with no way for the caller to tell why.
+    const released = await cleanupIsolatedWorkspace({ worktreePath: dir, repoRoot: repo.repoRoot, git: run, reservation: true });
+    return {
+      ok: false,
+      reason: res.reason,
+      error: res.error,
+      ...(released.ok ? {} : { cleanupBlocked: true, cleanupError: released.error }),
+    };
   }
-  return { ok: true, worktreePath: dir, baseRevision: rev, repoRoot: repo.repoRoot, name };
+  // Recorded only after git succeeded, so a failed creation never leaves a claim
+  // on a tree that does not exist. A record that cannot be written costs the
+  // automatic prune of this one worktree; it never costs the worktree itself.
+  //
+  // `owned` is only true when a record that `readOwnership` would actually
+  // accept was written: a record missing its repository or incarnation identity
+  // can never authorize cleanup, and reporting it as owned would be a leak
+  // dressed up as success.
+  // The revision Git actually left the worktree at, not the string we asked for:
+  // a caller may pass a branch or tag, and recording that name would never match
+  // the commit OID `worktree list` reports, so the worktree could never be
+  // recognized as untouched.
+  const headRes = await runGit(run, ['rev-parse', 'HEAD'], { cwd: dir });
+  const created = headRes.ok ? headRes.stdout.trim() : '';
+
+  const commonDir = await commonDirOf(run, repo.repoRoot);
+  const incarnation = commonDir ? await claimIncarnation(run, dir) : null;
+  // All four identities are required, and an unresolvable HEAD is not a fallback
+  // to the requested string: recording a symbolic name would produce a record
+  // that can never match, which is a worktree that can never be cleaned up
+  // reported as owned.
+  const owned = Boolean(commonDir && incarnation && created)
+    && recordOwnership({ worktreePath: dir, repo: commonDir, incarnation, head: created, purpose, at });
+  return { ok: true, worktreePath: dir, baseRevision: rev, repoRoot: repo.repoRoot, name, owned };
 }
 
 function splitFirstTab(line) {
@@ -328,30 +506,114 @@ function trackedIn(nameStatus, untracked) {
   return out;
 }
 
+/**
+ * Parse `git worktree list --porcelain` into records. Git documents that the
+ * main working tree is the first record; `detached` marks the ones Crew creates,
+ * since every Crew worktree is added with `--detach`.
+ */
+function parseWorktrees(stdout) {
+  const out = [];
+  for (const block of String(stdout ?? '').split('\n\n')) {
+    const lines = block.split('\n');
+    const path = lines.find((line) => line.startsWith('worktree '))?.slice('worktree '.length)?.trim();
+    if (!path) continue;
+    out.push({
+      path: resolve(path),
+      detached: lines.includes('detached'),
+      head: lines.find((line) => line.startsWith('HEAD '))?.slice('HEAD '.length)?.trim() ?? null,
+    });
+  }
+  return out;
+}
+
 async function mainRepoRoot(run, worktreePath) {
-  const common = await runGit(run, ['rev-parse', '--git-common-dir'], { cwd: worktreePath });
-  if (!common.ok) return null;
-  const dir = String(common.stdout ?? '').trim();
-  if (!dir) return null;
-  return resolve(dir, '..');
+  // The main working tree is the first record of `git worktree list`; deriving
+  // it from `--git-common-dir` breaks for a bare main repository, where that
+  // path is the bare repository itself and its parent is not a git directory at
+  // all. The first record is the same ordering guarantee the stale-list scan
+  // already relies on.
+  const list = await runGit(run, ['worktree', 'list', '--porcelain'], { cwd: worktreePath });
+  if (!list.ok) return null;
+  return parseWorktrees(list.stdout)[0]?.path ?? null;
 }
 
 const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 
+/**
+ * A path identity safe to compare for equality.
+ *
+ * `realpathSync` returns the on-disk spelling, so two aliases of one directory —
+ * a symlinked repo root, a mapped drive, a differently cased path — collapse to
+ * the same string without guessing. Lower-casing on Windows used to stand in for
+ * this, but Windows supports per-directory case sensitivity, where `Foo` and
+ * `foo` really are two directories and folding them together would license a
+ * delete against the wrong repository.
+ */
 const pathIdentity = (value) => {
   const resolved = resolve(String(value));
-  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+  try { return realpathSync.native ? realpathSync.native(resolved) : realpathSync(resolved); }
+  catch { return resolved; }
 };
 
 async function worktreeRegistered({ worktreePath, git, cwd }) {
   const res = await runGit(git, ['worktree', 'list', '--porcelain'], { cwd });
   if (!res.ok) return null;
   const target = pathIdentity(worktreePath);
-  for (const block of String(res.stdout).split('\n\n')) {
-    const path = block.split('\n').find((line) => line.startsWith('worktree '))?.slice('worktree '.length)?.trim();
-    if (path && pathIdentity(path) === target) return true;
-  }
-  return false;
+  return parseWorktrees(res.stdout).some((record) => pathIdentity(record.path) === target);
+}
+
+/**
+ * The repository's common git directory as seen from `cwd`, or null when git
+ * cannot say. `--path-format=absolute` needs git 2.31+, so the relative form is
+ * resolved against `cwd` for older installations.
+ */
+async function commonDirOf(run, cwd) {
+  const abs = await runGit(run, ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd });
+  if (abs.ok && abs.stdout.trim()) return resolve(abs.stdout.trim());
+  const rel = await runGit(run, ['rev-parse', '--git-common-dir'], { cwd });
+  if (!rel.ok || !rel.stdout.trim()) return null;
+  return resolve(cwd, rel.stdout.trim());
+}
+
+/**
+ * Whether `worktreePath` carries git metadata for the same repository as `root`.
+ *
+ * A directory name is not proof of ownership, and the filesystem fallback below
+ * force-deletes what it adopts — so the last resort asks git which repository the
+ * directory belongs to and refuses when the answer is unavailable or different.
+ * An unrelated directory that merely happens to be named like a Crew worktree
+ * therefore survives.
+ */
+async function sameRepository(run, worktreePath, root) {
+  const [a, b] = await Promise.all([commonDirOf(run, worktreePath), commonDirOf(run, root)]);
+  return Boolean(a && b && pathIdentity(a) === pathIdentity(b));
+}
+
+function emptyDirectory(path) {
+  try { return readdirSync(path).length === 0; } catch { return false; }
+}
+
+/**
+ * Why `worktreePath` is no longer the worktree the caller validated, or null when
+ * it still is.
+ *
+ * Checking ownership and then deleting by pathname is check-then-act: whatever
+ * occupies the path when the delete runs is what gets deleted. Re-reading the
+ * incarnation, registration, HEAD and detached state immediately before the
+ * removal narrows that window to the removal itself.
+ */
+async function ownershipDrift(run, worktreePath, expect) {
+  const incarnation = await incarnationOf(run, worktreePath);
+  if (!incarnation) return 'its incarnation stamp is gone';
+  if (incarnation.nonce !== expect.incarnation?.nonce) return 'its incarnation nonce changed';
+  if (pathIdentity(incarnation.gitDir) !== pathIdentity(expect.incarnation?.gitDir)) return 'its git directory changed';
+  const listed = await runGit(run, ['worktree', 'list', '--porcelain'], { cwd: worktreePath });
+  if (!listed.ok) return 'it is no longer registered';
+  const record = parseWorktrees(listed.stdout).find((r) => pathIdentity(r.path) === pathIdentity(worktreePath));
+  if (!record) return 'it is no longer registered';
+  if (!record.detached) return 'it is no longer detached';
+  if (expect.head && record.head !== expect.head) return `its HEAD moved from ${expect.head} to ${record.head}`;
+  return null;
 }
 
 /**
@@ -372,36 +634,140 @@ export async function cleanupIsolatedWorkspace({
   git,
   retries = WORKTREE_CLEANUP_RETRIES,
   backoffMs = WORKTREE_CLEANUP_BACKOFF_MS,
+  reservation = false,
+  // Callers that own the worktree (the Hub allocated it, this process holds the
+  // job) may force it away. Callers that merely recognised it — background
+  // pruning — must not: forcing discards any changes the tree now holds, which is
+  // precisely what a takeover looks like.
+  force = true,
+  // What the caller validated before deciding to delete. Re-checked here, because
+  // deciding on one observation and acting on a pathname is a different object.
+  expect = null,
 } = {}) {
   const run = git ?? defaultRunner;
   if (!worktreePath) return { ok: false, reason: NOT_GIT_REPOSITORY, error: 'worktree path required' };
   const root = repoRoot ?? (await mainRepoRoot(run, worktreePath));
   const owned = isCrewWorktreeName(basename(resolve(worktreePath)));
 
+  if (expect) {
+    const drift = await ownershipDrift(run, worktreePath, expect);
+    if (drift) {
+      return { ok: false, reason: WORKTREE_LOCKED, error: `refusing to remove ${worktreePath}: ${drift}`, cleanupBlocked: true };
+    }
+  }
+
+  if (!force) {
+    // Measured, not assumed: git refuses modified, staged and untracked files
+    // without `--force`, but it removes a worktree whose only remaining content
+    // is *ignored* — build output, a log, local config — and takes that content
+    // with it. Ask about ignored files directly, and treat an unanswerable
+    // question as a reason not to delete.
+    const ignored = await runGit(run, ['ls-files', '--others', '--ignored', '--exclude-standard'], { cwd: worktreePath });
+    if (!ignored.ok || ignored.stdout.trim() !== '') {
+      return {
+        ok: false,
+        reason: WORKTREE_LOCKED,
+        error: `refusing to remove ${worktreePath} without --force: it holds files that are not Crew's, or its contents could not be read`,
+        cleanupBlocked: true,
+      };
+    }
+    // And the index flags, which are the same class of hole one level down: a
+    // tracked file with `assume-unchanged` or `skip-worktree` set is invisible to
+    // `status`, to the untracked query and to the ignored query alike, and git
+    // removes the worktree without complaint — taking the operator's edit with
+    // it. Measured on git 2.47.3. In `ls-files -v` a lowercase letter means
+    // assume-unchanged and `S` means skip-worktree; the ordinary state is `H`.
+    const flags = await runGit(run, ['ls-files', '-v'], { cwd: worktreePath });
+    const hidden = flags.ok
+      ? flags.stdout.split('\n').find((line) => /^([a-z]|S)/.test(line)) ?? null
+      : 'unknown';
+    if (!flags.ok || hidden) {
+      return {
+        ok: false,
+        reason: WORKTREE_LOCKED,
+        error: `refusing to remove ${worktreePath} without --force: its index carries assume-unchanged or skip-worktree entries, which hide a modification from every status query`,
+        cleanupBlocked: true,
+      };
+    }
+  }
+
   if (root) {
-    // Preferred path: `git worktree remove --force` (removes registration and
-    // directory atomically). Retry bounded times to recover transient locks.
+    // Preferred path: `git worktree remove` (removes registration and directory
+    // atomically). Retry bounded times to recover transient locks.
+    //
+    // The ownership re-check above narrows the window between deciding and
+    // deleting, but it does not close it: git has no "remove only if HEAD and
+    // incarnation still equal X" primitive, so a worktree that changes in the
+    // moments between the two is removed anyway. That residual is accepted and
+    // stated rather than papered over; closing it needs a lease on the worktree,
+    // not another read.
+    const args = force
+      ? ['worktree', 'remove', '--force', worktreePath]
+      : ['worktree', 'remove', worktreePath];
     for (let attempt = 0; attempt < retries; attempt += 1) {
-      const res = await runGit(run, ['worktree', 'remove', '--force', worktreePath], { cwd: root });
-      if (res.ok) return { ok: true, removed: true, actions: [`removed worktree ${worktreePath}`] };
+      const res = await runGit(run, args, { cwd: root });
+      if (res.ok) {
+        const released = releaseOwnership({ worktreePath });
+        return {
+          ok: true,
+          removed: true,
+          actions: [`removed worktree ${worktreePath}`],
+          // The worktree is gone but its record is not: worth saying, because the
+          // record is what would have authorized a later cleanup.
+          ...(released ? {} : { ownershipRecordStale: true }),
+        };
+      }
       if (attempt < retries - 1) await sleep(backoffMs);
     }
+    if (!force) {
+      // Non-forced removal failed: git is refusing, or the tree is locked. The
+      // filesystem fallback deletes unconditionally, so it must not run here.
+      return { ok: false, reason: WORKTREE_LOCKED, error: `git declined to remove ${worktreePath} without --force`, cleanupBlocked: true };
+    }
   }
 
   // Last resort, only for Crew-owned disposable paths: remove the directory and
   // verify the git registration actually went away before claiming success.
+  //
+  // Ownership here is not the name alone. An earlier revision adopted anything
+  // whose basename matched, so a directory the user had named (or a worktree they
+  // had made) could be force-deleted for resembling Crew's.
   if (owned && root && pathIdentity(worktreePath) !== pathIdentity(root)) {
+    // Ask git BEFORE deleting anything. The reverse order — delete, then check —
+    // destroys the files of a worktree git still tracks and then reports the
+    // registration stranded, which is the outcome the caller was avoiding.
+    const registered = await worktreeRegistered({ worktreePath, git: run, cwd: root });
+    if (registered === true) {
+      return { ok: false, reason: WORKTREE_LOCKED, error: `worktree still registered after git refused to remove it: ${worktreePath}`, cleanupBlocked: true };
+    }
+    // The empty directory this call itself reserved is the one path that needs no
+    // repository provenance; anything else must belong to this repository.
+    const ownEmptyReservation = reservation && emptyDirectory(worktreePath);
+    const adoptable = ownEmptyReservation || (registered === false && await sameRepository(run, worktreePath, root));
+    if (!adoptable) {
+      return {
+        ok: false,
+        reason: WORKTREE_LOCKED,
+        error: `refusing to delete ${worktreePath}: not a worktree of ${root} (remove it manually if it is disposable)`,
+        cleanupBlocked: true,
+      };
+    }
     try {
-      rmSync(worktreePath, { recursive: true, force: true });
+      // A reservation is empty by construction, so remove it non-recursively: if
+      // something appeared in it, failing is better than deleting that too.
+      if (ownEmptyReservation) rmdirSync(worktreePath);
+      else rmSync(worktreePath, { recursive: true, force: true });
     } catch (err) {
       return { ok: false, reason: WORKTREE_LOCKED, error: `worktree cleanup failed: ${err?.message ?? String(err)}`, cleanupBlocked: true };
     }
-    const registered = root ? await worktreeRegistered({ worktreePath, git: run, cwd: root }) : null;
-    if (registered === false && !existsSync(worktreePath)) {
-      return { ok: true, removed: true, actions: [`cleaned worktree files ${worktreePath}`] };
-    }
-    if (registered === true) {
-      return { ok: false, reason: WORKTREE_LOCKED, error: `worktree still registered after cleanup: ${worktreePath}`, cleanupBlocked: true };
+    if (!existsSync(worktreePath)) {
+      const released = releaseOwnership({ worktreePath });
+      return {
+        ok: true,
+        removed: true,
+        actions: [`cleaned worktree files ${worktreePath}`],
+        ...(released ? {} : { ownershipRecordStale: true }),
+      };
     }
     return { ok: false, reason: WORKTREE_LOCKED, error: `could not verify worktree removal for ${worktreePath}`, cleanupBlocked: true };
   }
@@ -409,36 +775,161 @@ export async function cleanupIsolatedWorkspace({
   return { ok: false, reason: WORKTREE_LOCKED, error: `worktree cleanup failed while ${worktreePath} remains (${root ? 'not a Crew-owned disposable path' : 'main repository root unresolvable'})`, cleanupBlocked: true };
 }
 
-export async function staleWorktrees({ git, allowed = [] } = {}) {
+/**
+ * Split the linked worktrees of this repository into:
+ *
+ * - `stale`: Crew recorded creating it and it is still in the disposable state
+ *   Crew leaves behind, so it may be removed automatically;
+ * - `retained`: Crew recorded creating it, but an operator has since attached a
+ *   branch or checked something out, so it is no longer Crew's to discard;
+ * - `unowned`: Crew cannot show it created it at all.
+ *
+ * Only the first is ever deleted. The other two are reported so a human decides.
+ * Returned paths are canonical: git reports the spelling it resolved when the
+ * worktree was added, which on Windows can expand an 8.3 temp name (`RUNNER~1`)
+ * into its long form, so a caller comparing its own path string against the
+ * answer would miss — and a miss here decides whether a live worktree looks
+ * like a leftover.
+ */
+async function worktreeCandidates({ git, allowed = [] } = {}) {
   const run = git ?? defaultRunner;
-  const set = new Set(allowed.map((p) => resolve(p)));
+  const set = new Set(allowed.map((p) => pathIdentity(p)));
   const stale = [];
+  const retained = [];
+  const unowned = [];
   try {
     const root = await inspectRepository({ cwd: allowed[0] ?? process.cwd(), git: run });
     if (root.ok) {
       const res = await runGit(run, ['worktree', 'list', '--porcelain'], { cwd: root.repoRoot });
       if (res.ok) {
-        for (const block of String(res.stdout).split('\n\n')) {
-          const path = block.split('\n').find((l) => l.startsWith('worktree '))?.slice('worktree '.length)?.trim();
-          if (!path) continue;
-          const abs = resolve(path);
-          if (isCrewWorktreeName(basename(abs)) && !set.has(abs)) stale.push(abs);
+        // `git worktree list` puts the main working tree first. Inspecting from
+        // inside a linked worktree reports that worktree as the top level, so the
+        // repo root cannot be matched by path — the position in the list is what
+        // identifies the main tree.
+        const records = parseWorktrees(res.stdout);
+        const repo = await commonDirOf(run, root.repoRoot);
+        for (let index = 1; index < records.length; index += 1) {
+          const { path: abs, detached, head } = records[index];
+          // A repo whose directory happens to start with a Crew prefix (say, a
+          // checkout named dsh-crew-something) is not a disposable worktree, and
+          // treating it as stale would have the cleanup path fighting over it.
+          if (!isCrewWorktreeName(basename(abs)) || set.has(pathIdentity(abs))) continue;
+          const incarnation = await incarnationOf(run, abs);
+          const owned = readOwnership({ worktreePath: abs, repo, incarnation });
+          if (!owned) {
+            // The name is not proof: `dsh-crew-backup-deadbeef` is a name a user
+            // could plausibly pick. No valid record, no deletion.
+            unowned.push(pathIdentity(abs));
+          } else if (detached && owned.head === head) {
+            // Crew's worktree, untouched since Crew left it there. The incarnation
+            // and HEAD travel with it so the removal can re-check them rather
+            // than trusting that nothing changed since this scan.
+            stale.push({ path: pathIdentity(abs), incarnation, head });
+          } else {
+            // Crew's worktree, but no longer a disposable one. Being on a branch
+            // is only one way an operator takes a worktree over; committing on a
+            // detached HEAD, or checking out something else, moves it just as
+            // far out of Crew's hands.
+            retained.push(pathIdentity(abs));
+          }
         }
       }
     }
   } catch {}
-  return stale;
+  return { stale, retained, unowned };
 }
 
-export async function pruneWorktrees({ git, allowed = [] } = {}) {
+/** Crew-created worktrees that are still disposable and belong to no active job. */
+export async function staleWorktrees({ git, allowed = [] } = {}) {
+  return (await worktreeCandidates({ git, allowed })).stale.map((entry) => entry.path);
+}
+
+/** Linked worktrees that resemble Crew's but carry no usable record of it. */
+export async function unownedWorktrees({ git, allowed = [] } = {}) {
+  return (await worktreeCandidates({ git, allowed })).unowned;
+}
+
+/** Crew-created worktrees an operator has since taken over; never removed. */
+export async function retainedWorktrees({ git, allowed = [] } = {}) {
+  return (await worktreeCandidates({ git, allowed })).retained;
+}
+
+/**
+ * Report what Crew could clean up, and only delete when explicitly asked.
+ *
+ * `remove` defaults to false, and the default is the point. Deleting from a
+ * background scan has been shown insufficient three separate ways: git removes a
+ * worktree whose only content is ignored; it removes one whose tracked file
+ * carries `assume-unchanged` or `skip-worktree`; and between validating a
+ * worktree and deleting it, the worktree can change. Each was measured against
+ * real git rather than reasoned about, and each ends with an operator's work
+ * gone. Nothing in Crew calls this path, so the automatic capability buys nothing
+ * and risks the one thing Crew must not lose.
+ *
+ * A caller that has decided to remove a specific worktree should pass
+ * `remove: true`, or better, use `cleanupIsolatedWorkspace` for a worktree it
+ * directly owns. Unattended deletion would need a lease on the worktree, not
+ * another pre-delete observation.
+ */
+export async function pruneWorktrees({ git, allowed = [], remove = false } = {}) {
   const run = git ?? defaultRunner;
-  const stale = await staleWorktrees({ git: run, allowed });
+  const { stale, retained, unowned } = await worktreeCandidates({ git: run, allowed });
   const actions = [];
-  for (const w of stale) {
-    const r = await cleanupIsolatedWorkspace({ worktreePath: w, git: run });
-    actions.push(...(r.actions ?? [r.error ?? `stale worktree ${w}`]));
+
+  if (!remove) {
+    for (const entry of stale) actions.push(`stale Crew worktree, remove explicitly if it is finished with: ${entry.path}`);
+    for (const w of unowned) actions.push(`not Crew-owned, left in place: ${w}`);
+    for (const w of retained) actions.push(`taken over by an operator, left in place: ${w}`);
+    return {
+      ok: true,
+      reportOnly: true,
+      removed: 0,
+      candidates: stale.map((entry) => entry.path),
+      failed: [],
+      unowned,
+      retained,
+      staleRecords: [],
+      actions,
+    };
   }
-  return { ok: true, removed: stale.length, actions };
+
+  const failed = [];
+  const staleRecords = [];
+  let removed = 0;
+  for (const entry of stale) {
+    // Not forced, and re-checked against what was scanned: background pruning
+    // recognised this worktree from a name and a record, and neither survives the
+    // tree itself being taken over. `--force` would discard whatever an operator
+    // had put there; ownershipDrift would not notice if they had already.
+    const r = await cleanupIsolatedWorkspace({
+      worktreePath: entry.path,
+      git: run,
+      force: false,
+      expect: { incarnation: entry.incarnation, head: entry.head },
+    });
+    // A locked worktree is left on disk, so counting it as removed would tell an
+    // operator the machine is clean when it is not.
+    if (r.ok && r.removed) {
+      removed += 1;
+      actions.push(...(r.actions ?? []));
+      if (r.ownershipRecordStale) staleRecords.push(entry.path);
+    } else {
+      failed.push(entry.path);
+      actions.push(`failed to remove ${entry.path}: ${r.error ?? 'unknown reason'}`);
+    }
+  }
+  for (const w of unowned) actions.push(`not Crew-owned, left in place: ${w}`);
+  for (const w of retained) actions.push(`taken over by an operator, left in place: ${w}`);
+  return {
+    ok: failed.length === 0,
+    removed,
+    failed,
+    unowned,
+    retained,
+    staleRecords,
+    actions,
+    ...(failed.length ? { cleanupBlocked: true } : {}),
+  };
 }
 
 export function clampMaxParallel(raw) {