@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/project/worktree.js

@@ -1,39 +1,3 @@
-/**
- * MORPH-SPEC Worktree Command Suite
- *
- * Isolates feature work into per-feature git worktrees at worktrees/{feature}/
- * on branch morph/{feature}, so each feature can run its own Claude Code
- * instance (v8 multi-instance, parallel-feature-development flow).
- *
- * `.morph/features/{f}/feature.json` is the authoritative, committed state — it
- * travels with the worktree's branch. `.morph/state.json` is a thin, gitignored,
- * derivable index; `worktree setup` MATERIALIZES a local one via loadState()'s
- * self-heal rather than linking to the main copy (a hard link breaks silently on
- * the first atomic write, since tmp+rename creates a new inode).
- *
- * Subcommands:
- *   morph-spec worktree setup <feature> [--fresh]   — create + materialize state
- *   morph-spec worktree provision <name> [--base <ref>]  — task-isolation tree
- *     (branch morph-task/{name}, same infra, NO feature identity) — what the
- *     WorktreeCreate hook calls for `claude -w` / EnterWorktree / Agent isolation
- *   morph-spec worktree link [--target <path>] [--all]  — (re)link shared infra
- *   morph-spec worktree remove [<feature>|--target <path>] [--if-clean]  — safe teardown
- *   morph-spec worktree list [--json]  — list active feature worktrees
- *
- * Closing the lifecycle (integrate + teardown) lives in `morph-spec finish`
- * (src/commands/state/finish.js), which orchestrates archive → merge|PR →
- * teardown for BOTH the worktree and the common flow. This file exports the
- * hardened primitives it uses: `shedRootFeatureScope`, `primaryRootUnexplainedDirt`,
- * and `teardownWorktree` (PROVE-or-DECLINE removal).
- *
- * Exit codes (setup):
- *   0  — success (created) or fail-open (not a git repo, git error)
- *   1  — refused: feature name is not a plain kebab slug
- *   2  — worktree already exists at this exact path (signals resume to caller)
- *   3  — a live worktree for this feature already exists at a DIFFERENT path
- *        (anti-dupe guard — refuses to fork a second live instance)
- */
-
 import { execSync, execFileSync } from 'child_process';
 import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, lstatSync, unlinkSync, rmdirSync, cpSync, copyFileSync, readdirSync } from 'fs';
 import { join, resolve, dirname, basename } from 'path';
@@ -47,16 +11,12 @@ import {
   enforceBackupRetention,
   newBackupStamp,
 } from '../../lib/worktree/finish-backup.js';
-// The reparse scan lives in hooks/shared because the PreToolUse guardrail needs
-// the SAME answer this file does, and hooks can never import from `src/`.
+// Lives in hooks/shared: the PreToolUse guardrail needs the same answer and hooks cannot import `src/`.
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 import { ensureCommonExclude } from '../../../framework/hooks/shared/git-exclude.js';
 import { seedGraphFromRoot } from '../../../framework/hooks/shared/graph-refresh.js';
 import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/hooks/shared/graph-freshness.js';
 
-// The container name lives in lib/worktree/dirs.js (single source, C1
-// rationale documented there); re-exported here so existing importers and the
-// dependency-matrix row keep pointing at this file.
 import { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES } from '../../lib/worktree/dirs.js';
 import { applyEditorSettings } from '../../lib/worktree/vscode-settings.js';
 import { copyWorktreeIncludes } from '../../lib/worktree/worktree-include.js';
@@ -75,27 +35,7 @@ function rootAndEditorReport(root) {
 }
 export { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES };
 
-// ── Pure helpers (exported for tests) ──────────────────────────────────────
-
-/**
- * Check if a directory is inside a git repository.
- * @param {string} cwd
- * @returns {boolean}
- */
-/**
- * Is `name` a plain kebab-case feature name?
- *
- * Mirrors the validation `morph-spec create` applies, and every worktree
- * subcommand enforces it for the same reason plus a sharper one: a feature name
- * flows into `worktrees/{name}`, the branch `morph/{name}`, and from there into
- * git invocations. Characters like `& | ; > ^` are legal in a git refname but
- * are cmd.exe metacharacters — on Windows an unvalidated name turns any
- * string-interpolated git call into command injection, and makes a `finish`
- * merge a DIFFERENT branch than the one it validated and reports.
- *
- * @param {string} name
- * @returns {boolean}
- */
+/** Also guards git calls: `& | ; > ^` are legal in a refname but cmd.exe metacharacters on Windows. */
 export function isValidFeatureName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(name);
 }
@@ -109,12 +49,6 @@ export function isGitRepo(cwd = process.cwd()) {
   }
 }
 
-/**
- * Check if a branch exists locally.
- * @param {string} branch
- * @param {string} cwd
- * @returns {boolean}
- */
 export function branchExists(branch, cwd = process.cwd()) {
   try {
     execSync(`git show-ref --verify --quiet refs/heads/${branch}`, { cwd, stdio: 'pipe' });
@@ -124,23 +58,6 @@ export function branchExists(branch, cwd = process.cwd()) {
   }
 }
 
-/**
- * Check if a worktree path is already registered with git.
- *
- * BUGFIX: the old `normalizedPath.startsWith('/')` absolute-path check only
- * recognized POSIX-style absolute paths. On Windows, `buildWorktreePath`
- * already returns an absolute `C:/...` path, which does NOT start with `/` —
- * so this used to re-prepend `cwd` onto an already-absolute path, producing
- * a bogus double-rooted string that never matched `git worktree list`'s
- * output. That silently broke the Gate 2 "already exists → resume" check on
- * Windows (it always fell through to a failing `git worktree add`, caught by
- * the outer fail-open handler). `path.resolve(cwd, worktreePath)` handles
- * both relative and platform-absolute paths correctly.
- *
- * @param {string} worktreePath  Relative or absolute path
- * @param {string} cwd
- * @returns {boolean}
- */
 export function worktreeExists(worktreePath, cwd = process.cwd()) {
   try {
     const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
@@ -151,13 +68,7 @@ export function worktreeExists(worktreePath, cwd = process.cwd()) {
   }
 }
 
-/**
- * Build the worktree directory path (always forward slashes).
- * @param {string} feature
- * @param {string} cwd
- * @param {{ fresh?: boolean }} options
- * @returns {string}
- */
+/** Always forward slashes. */
 export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
   const suffix = options.fresh ? `-${getDateSuffix()}` : '';
   const normalizedCwd = cwd.replace(/\\/g, '/');
@@ -165,12 +76,6 @@ export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
   return `${container}/${feature}${suffix}`;
 }
 
-/**
- * Build the branch name for a feature worktree.
- * @param {string} feature
- * @param {{ fresh?: boolean }} options
- * @returns {string}
- */
 export function buildBranchName(feature, options = {}) {
   const suffix = options.fresh ? `-${getDateSuffix()}` : '';
   return `morph/${feature}${suffix}`;
@@ -180,24 +85,8 @@ function getDateSuffix() {
   return new Date().toISOString().slice(0, 10).replace(/-/g, '');
 }
 
-// ── Infrastructure linking ───────────────────────────────────────────────────
-
-/**
- * The infra directories morph itself links into a worktree — the ONLY ones
- * `setupInfraLinks`/`worktreeLinkCommand --all`/`unlinkWorktreeInfraLinks` treat
- * as KNOWN, and therefore the only ones `finish` may auto-remove via the
- * already-proven-safe unlink mechanism (never by widening the reparse-point
- * scan — see `findReparsePoints`).
- *
- * Always: `node_modules`, `.claude`. Conditionally: `.morph/framework` (client
- * projects only) and `{project.frontendPath}/node_modules` — a monorepo
- * frontend (e.g. a Next.js app under `apps/catalog-admin`) commonly has its OWN
- * node_modules, a separate `npm install` from the root's, invisible to a static
- * list. Fail-open: a missing/unreadable config.json just means no frontendPath.
- *
- * @param {string} mainCwd - Absolute path to the main project root
- * @returns {string[]} relative paths, root-first
- */
+// The ONLY links `finish` may auto-remove (never widened to any reparse point found), plus
+// `{project.frontendPath}/node_modules`: a monorepo frontend has its own install.
 function resolveInfraLinkDirs(mainCwd) {
   const dirs = ['node_modules', '.claude'];
   if (existsSync(join(mainCwd, '.morph', 'framework'))) {
@@ -210,29 +99,13 @@ function resolveInfraLinkDirs(mainCwd) {
       const frontendPath = config?.project?.frontendPath;
       if (frontendPath) dirs.push(join(frontendPath, 'node_modules'));
     }
-  } catch { /* fail-open — no frontendPath to add */ }
+  } catch {}
   return dirs;
 }
 
 /**
- * Create junctions in the worktree for shared infrastructure directories
- * (node_modules/, .claude/, .morph/framework/).
- *
- * `.morph/state.json` is deliberately NEVER linked here — a hard link breaks
- * silently the moment either side writes atomically (tmp file + rename creates
- * a fresh inode, severing the link), so worktree and main state can silently
- * diverge. The worktree's local state.json is MATERIALIZED instead, see
- * `materializeState()`. `memory/` and `logs/` are also never linked — each
- * worktree instance owns its own debounce/session snapshots.
- *
- * Uses junctions for directories (no admin required on Windows).
- * Fail-open: any error is silently ignored.
- *
- * @param {string} worktreePath - Absolute path to the worktree
- * @param {string} mainCwd - Absolute path to the main project root
- * @param {{ dirs?: string[] }} [opts] - When `dirs` is provided, restricts
- *   which junctions are (re)created to exactly that list. Default: node_modules,
- *   .claude, and .morph/framework (the last only if it exists in the main root).
+ * `.morph/state.json` is never linked: an atomic write (tmp + rename) makes a new inode and silently
+ * severs a hard link, so the worktree materializes its own (`materializeState`).
  */
 export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   const mainAbs = resolve(mainCwd);
@@ -250,14 +123,11 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
       const parent = dirname(linkPath);
       if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
       symlinkSync(target, linkPath, 'junction');
-    } catch { /* fail-open */ }
+    } catch {}
   }
 
-  // Only the reparse points: a REAL directory at one of these paths was not
-  // created by us, is not a link out of the worktree, and git's normal rules
-  // already speak for it. `lstat` reports a POSIX symlink and a Windows
-  // junction alike as a symbolic link, so the exclude lands identically on
-  // both platforms — as does the bug it prevents (see excludeInfraLinks).
+  // Only reparse points: `lstat` reports a POSIX symlink and a Windows junction alike, so the
+  // exclude lands identically on both platforms.
   excludeWorktreePaths(mainAbs, dirLinks.filter((rel) => {
     try {
       return lstatSync(join(wtAbs, rel)).isSymbolicLink();
@@ -271,47 +141,9 @@ export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
 const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed — see setupInfraLinks)';
 
 /**
- * Teach the repo's git to ignore worktree-carried paths morph itself creates —
- * the infra links from `setupInfraLinks` and the fleet env manifest
- * (`.morph/worktree.env`). Same mechanism, same reasons, for both.
- *
- * CRITICAL — without this, `morph-spec finish` (worktree teardown) is unusable on
- * POSIX and destructive at worst, because git never sees a link as a link: it sees what
- * the OS reports. A Windows junction IS a directory, so a `.morph/framework/`
- * rule (trailing slash = directories only) matches it and git ignores it. A
- * POSIX symlink is a FILE (mode 120000), so the very same rule does NOT match
- * and the link surfaces as untracked (`??`). Both endings are bad:
- *   - `finish` refuses on its clean-worktree gate (`worktree-dirty`) — the
- *     careful user who commits only real work can never finish at all; or
- *   - a `git add -A` COMMITS the links onto the feature branch, and the merge
- *     then replaces the primary root's real `.claude/` and `.morph/framework/`
- *     with symlinks pointing at themselves. The installation is gone, and
- *     `finished: true` is reported.
- *
- * The user's `.gitignore` cannot be the fix: it is a TRACKED file (rewriting it
- * dirties the very tree these gates read), morph deliberately ignores only the
- * morph-OWNED subpaths of `.claude/` so a user's own settings stay trackable,
- * and existing installs would only pick up a new rule on a re-init.
- * `.git/info/exclude` is git's own answer to "ignore this locally": never
- * committed, additive (it does not override the user's global excludes, and an
- * exclude NEVER applies to a tracked file), and — unlike the per-worktree
- * `.git/worktrees/<id>/info/exclude`, which git does not read for a linked
- * worktree — honored from the COMMON git dir by every worktree of the repo.
- *
- * TRADEOFF, deliberate: patterns are matched against each working tree's own
- * top and the file is shared, so `/.claude` also hides an UNTRACKED `.claude/`
- * in the primary root. gitignore cannot express "only when it is a symlink",
- * and no negation can re-include a path under an excluded directory. The cost
- * is narrow — tracked files are untouched, and a team that versions
- * `.claude/settings.json` has it tracked — and it buys the links being
- * invisible to `git add -A`, which is what keeps the merge from eating the
- * installation.
- *
- * Idempotent (never duplicates a pattern) and fail-open: an exclude we could
- * not write costs a refused finish, never a wrong one.
- *
- * @param {string} mainCwd - Absolute path to the main project root
- * @param {string[]} rels - worktree-relative paths to exclude
+ * Git sees a POSIX symlink as a FILE, so a dirs-only rule misses it and `git add -A` commits the links
+ * (the merge then eats the root's installation). The COMMON dir's `info/exclude` is honored by every
+ * worktree; the accepted cost is that it also hides an untracked `.claude/` in the root.
  */
 function excludeWorktreePaths(mainCwd, rels) {
   // Anchored (`/x`): these live at the top of a worktree, and an unanchored
@@ -319,16 +151,7 @@ function excludeWorktreePaths(mainCwd, rels) {
   ensureCommonExclude(mainCwd, rels.map((rel) => `/${rel.replace(/\\/g, '/')}`), EXCLUDE_MARKER);
 }
 
-/**
- * Resolve the absolute path (forward slashes) of the primary/main git worktree,
- * from anywhere inside the repo (including from within a secondary worktree).
- *
- * Fail-open: if `cwd` is not a git repo (or the git call errors), returns
- * `cwd` itself, resolved and normalized.
- *
- * @param {string} cwd
- * @returns {string} Absolute, forward-slash path to the primary worktree
- */
+/** Fail-open: outside a git repo (or on a git error) returns `cwd` itself, normalized. */
 export function resolvePrimaryRoot(cwd = process.cwd()) {
   try {
     const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
@@ -336,39 +159,13 @@ export function resolvePrimaryRoot(cwd = process.cwd()) {
     if (line) {
       return line.slice('worktree '.length).trim().replace(/\\/g, '/');
     }
-  } catch { /* fall through to fail-open */ }
+  } catch {}
   return resolve(cwd).replace(/\\/g, '/');
 }
 
 /**
- * Materialize a LOCAL, real `.morph/state.json` inside a worktree, reconstructed
- * from the committed per-feature `feature.json` files under `.morph/features/`
- * — not linked to the main copy (see `setupInfraLinks` doc for why hard links
- * are unsafe here).
- *
- * Mechanism: temporarily chdir into the worktree and call `loadState(false)`,
- * whose self-heal path (state-manager.js) scaffolds + hydrates + writes a fresh
- * root index when `.morph/state.json` is missing but per-feature files exist.
- * `process.chdir` is process-global, so the original cwd is ALWAYS restored via
- * finally, even on error. Fail-open: never throws.
- *
- * @param {string} worktreePath - Absolute path to the worktree
- * @returns {Promise<{ materialized: boolean, reason?: string }>}
- */
-/**
- * Guarantee the worktree owns a local `.morph/state.json`, hydrated from its
- * committed features when there are any, and an EMPTY index otherwise.
- *
- * Why the empty index matters: every core hook fail-opens on `stateExists()`,
- * which is true only with a `state.json` or a feature dir in the tree. A
- * task-isolation worktree of a project with no committed features (measured
- * in the sandbox e2e) had neither — so the env-inject hook, the removal guard
- * and every other guardrail were silently dark inside it. `state.json` is
- * gitignored and derivable, so an empty one costs nothing and can never dirty
- * the tree the finish gates read.
- *
- * @param {string} worktreePath
- * @returns {Promise<{ materialized: boolean, reason?: string, seeded?: boolean }>}
+ * Writes an EMPTY index when there is nothing to hydrate: every hook fail-opens on `stateExists()`,
+ * and a tree with neither state.json nor features left them all silently dark.
  */
 export async function ensureLocalState(worktreePath) {
   const result = await materializeState(worktreePath);
@@ -402,12 +199,8 @@ export async function materializeState(worktreePath) {
   try {
     process.chdir(resolve(worktreePath));
     const { loadState } = await import('../../core/state/state-manager.js');
-    loadState(false); // self-heal: writes a fresh local .morph/state.json
-    // loadState(false) only writes state.json when it actually found something
-    // to hydrate (a non-empty .morph/features/). A present-but-empty features
-    // dir (e.g. right after `archive` moved the last feature out) makes
-    // loadState return null and write nothing — don't report success in that
-    // case, or callers believe a local state.json exists when it doesn't.
+    loadState(false);
+    // loadState(false) writes nothing for a present-but-empty features dir: don't report success then.
     if (existsSync(join(worktreePath, '.morph', 'state.json'))) {
       return { materialized: true };
     }
@@ -419,20 +212,8 @@ export async function materializeState(worktreePath) {
   }
 }
 
-/**
- * Codebase graph for a new worktree. The tree is born from a root commit, so
- * the root's graph is either this tree's HEAD graph already or one
- * `morph-spec graph refresh` away — and the `reuse` validator reads the graph
- * of the tree `verify` runs in, so a worktree without one skips reuse checking
- * exactly where the new code is written. Nothing is launched in the
- * background: the automatic refresh only ever touches the root (a detached
- * process holding a worktree directory made `finish` fail on win32).
- * Fail-open: no root graph, no copy.
- *
- * @param {string} worktreePath
- * @param {string} root
- * @returns {{seeded: boolean, reason?: string}}
- */
+// Nothing launched in the background: a detached process holding a worktree directory made
+// `finish` fail on win32. Fail-open: no root graph, no copy.
 function seedWorktreeGraph(worktreePath, root) {
   try {
     return seedGraphFromRoot(worktreePath, root);
@@ -441,35 +222,18 @@ function seedWorktreeGraph(worktreePath, root) {
   }
 }
 
-// ── Command handler ─────────────────────────────────────────────────────────
-
 /**
- * Non-exiting core of `worktree setup` — does all the real work (git checks,
- * guards, branch creation, `git worktree add`, infra linking, state
- * materialization, metadata persistence) and returns a result object instead
- * of calling `process.exit`/`console.log`, so callers (e.g. a future
- * `create --worktree` that needs to chain further steps) can reuse it in
- * process. `worktreeSetupCommand` below is a thin CLI wrapper around this.
- *
- * @param {string} feature
- * @param {{ fresh?: boolean, cwd?: string }} [options]
- * @returns {Promise<{ ok: boolean, exitCode: 0|1|2|3, created?: boolean, alreadyExists?: boolean, path?: string, branch?: string, feature: string, materialized?: boolean, nextStep?: string, error?: string, existingPath?: string }>}
- *   exitCode 1 = refused, `error: 'invalid-feature-name'`. This function is the
- *   non-exiting core precisely so callers can reuse it in-process — a caller
- *   trusting a `0|2|3` union would mishandle that refusal.
+ * Non-exiting core of `worktree setup`. exitCode 1 = refused (`invalid-feature-name`),
+ * 2 = already exists here, 3 = a live worktree for the feature exists elsewhere.
  */
 export async function runWorktreeSetup(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
 
-  // Gate 0: the name must be a plain kebab slug before it reaches a path, a
-  // refname, or any git call. See isValidFeatureName — `create` already refuses
-  // these names, so accepting them here would only ever create a worktree no
-  // other morph-spec command can address.
+  // A plain kebab slug before it reaches a path, a refname or any git call (see isValidFeatureName).
   if (!isValidFeatureName(feature)) {
     return { ok: false, exitCode: 1, created: false, error: 'invalid-feature-name', feature };
   }
 
-  // Gate 1: Must be a git repo
   if (!isGitRepo(cwd)) {
     return { ok: true, exitCode: 0, created: false, error: 'not-a-git-repo', feature };
   }
@@ -477,16 +241,11 @@ export async function runWorktreeSetup(feature, options = {}) {
   const branch = buildBranchName(feature, options);
   const worktreePath = buildWorktreePath(feature, cwd, options);
 
-  // Gate 2: If worktree already registered and not --fresh, signal resume
   if (!options.fresh && worktreeExists(worktreePath, cwd)) {
     return { ok: false, exitCode: 2, created: false, alreadyExists: true, path: worktreePath, branch, feature };
   }
 
-  // Guard 3: anti-dupe — refuse to fork a second LIVE worktree for the same
-  // feature. If feature.json already records a worktree path that still exists
-  // on disk and differs from the one this call would create, stop (exit 3).
-  // (A recorded path that's gone from disk — e.g. removed via `git worktree
-  // remove` — does not block: existsSync() is false, so this falls through.)
+  // Anti-dupe: refuse a second LIVE worktree for this feature; a recorded path gone from disk does not block.
   try {
     const featureJsonPath = join(cwd, '.morph', 'features', feature, 'feature.json');
     if (existsSync(featureJsonPath)) {
@@ -510,15 +269,8 @@ export async function runWorktreeSetup(feature, options = {}) {
 
   let branchedFrom = null;
   try {
-    // Create branch if needed — off the DEFAULT branch, never the current HEAD.
-    // Branching from HEAD meant a root parked on some other `morph/{other}`
-    // gave the new feature that feature's commits, and every PR opened from
-    // this worktree carried the sibling's diff (A1). Symmetric with the common
-    // flow in create.js → branchCommonFlow.
-    //
-    // Fail-open, same as create: with no resolvable default (a repo whose
-    // default is neither `main`/`master` nor declared via origin/HEAD) the
-    // branch is still created — off HEAD — and `branchedFrom: null` reports it.
+    // Off the DEFAULT branch, never HEAD: a root parked on another `morph/*` would hand over its commits.
+    // No resolvable default → off HEAD, reported as `branchedFrom: null`.
     if (!branchExists(branch, cwd)) {
       const defaultBranch = detectDefaultBranch(cwd);
       if (defaultBranch) {
@@ -529,48 +281,32 @@ export async function runWorktreeSetup(feature, options = {}) {
       }
     }
 
-    // Create worktree directory parent if needed
     const parentDir = newWorktreesDir(cwd);
     if (!existsSync(parentDir)) {
       mkdirSync(parentDir, { recursive: true });
     }
 
-    // Add worktree
     execSync(`git worktree add "${worktreePath}" ${branch}`, { cwd, stdio: 'pipe' });
 
-    // Set up infrastructure junctions (node_modules, .claude, .morph/framework).
     setupInfraLinks(worktreePath, cwd);
     const included = copyWorktreeIncludes(worktreePath, cwd);
 
-    // Fleet env: allocate this feature's deterministic port block and write the
-    // worktree-local manifest (.morph/worktree.env). Fail-open — a worktree
-    // without ports is degraded, never broken.
+    // Fail-open: a worktree without ports is degraded, never broken.
     const envBlock = await allocateWorktreeEnv(worktreePath, cwd, feature);
 
-    // Materialize a local, real state.json in the worktree (self-heal from the
-    // committed feature.json files) so hooks work from the very first session.
     const materialized = await ensureLocalState(worktreePath);
 
     const graph = seedWorktreeGraph(worktreePath, cwd);
 
-    // Fleet handoff: the fresh instance that opens this worktree reads
-    // handoff.md before anything else (SessionStart hook points at it). The doc
-    // is derived and git-invisible (see handoff-generator). Fail-open — and a
-    // no-op in the create --worktree flow, where the feature dir only lands in
-    // the worktree after create's copy (create regenerates it then).
+    // Fail-open; a no-op under `create --worktree`, which regenerates it after its copy.
     try {
       if (existsSync(join(worktreePath, '.morph', 'features', feature, 'feature.json'))) {
         const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
-        // `worktree` is ROOT-OWNED bookkeeping, absent from this branch-local
-        // copy by contract — pass it explicitly so the doc built FROM INSIDE
-        // the worktree still says "Local: worktree", not "raiz primária".
+        // `worktree` is root-owned and absent from this branch copy: pass it so the doc says "Local: worktree".
         writeHandoff(feature, worktreePath, { worktree: { path: worktreePath, branch } });
       }
-    } catch { /* fail-open */ }
+    } catch {}
 
-    // Persist in state (non-blocking — feature may not be in state yet).
-    // NOTE: imports from core/ (the lib/ path was a latent bug that silently
-    // no-op'd this whole block); loadState/saveState operate on the cwd's state.
     try {
       const { loadState, saveState } = await import('../../core/state/state-manager.js');
       const state = loadState(false);
@@ -579,7 +315,6 @@ export async function runWorktreeSetup(feature, options = {}) {
         saveState(state);
       }
     } catch {
-      // Non-blocking
     }
 
     return {
@@ -602,31 +337,13 @@ export async function runWorktreeSetup(feature, options = {}) {
   }
 }
 
-/**
- * Main command handler for `morph-spec worktree setup <feature>` — thin
- * wrapper around `runWorktreeSetup` that prints its JSON result and exits
- * with its exit code. Preserves the exact JSON shape and exit codes (0/2/3)
- * this command has always used.
- * @param {string} feature
- * @param {{ fresh?: boolean, cwd?: string }} options
- */
 export async function worktreeSetupCommand(feature, options = {}) {
   const { ok, exitCode, ...result } = await runWorktreeSetup(feature, options);
   console.log(JSON.stringify(result));
   process.exit(exitCode);
 }
 
-// ── provision (task isolation — a worktree that is NOT a feature) ──────────
-
-/**
- * Branch name for a task-isolation worktree: `morph-task/<name>`. A separate
- * namespace from `morph/<feature>` on purpose — `worktree list`, `fleet`,
- * `finish` and the SessionStart hook all read `morph/<f>` as "this IS feature
- * f", and a scratch tree named after a feature must never impersonate it.
- *
- * @param {string} name
- * @returns {string}
- */
+/** A separate namespace on purpose: a scratch tree must never impersonate `morph/<feature>`. */
 export function buildTaskBranchName(name) {
   return `morph-task/${name}`;
 }
@@ -634,18 +351,8 @@ export function buildTaskBranchName(name) {
 const ROOT_ENV_FILE_RE = /^\.env(\..+)?$/;
 
 /**
- * Copy the root's `.env` / `.env.*` into a new tree: a sub-agent that builds
- * or runs the app needs the same secrets, and they are never committed. Only
- * a REAL file (never a link — nothing in the tree may reach the root through
- * one), only when the tree lacks it (never overwrite), and only when git
- * IGNORES it there: an untracked-but-visible copy would dirty the tree, and
- * `finish`/`worktree remove --if-clean` refuse a dirty tree. At teardown the
- * copy is byte-identical to the root's, which `triageIgnoredPaths` classifies
- * as REPLICABLE — deleted with nothing lost.
- *
- * @param {string} worktreePath
- * @param {string} root
- * @returns {string[]} names copied
+ * Only a REAL file, never overwriting, and only when git IGNORES it in the tree: a visible copy
+ * would dirty it and `finish` refuses a dirty tree. At teardown the copy is a replica of the root's.
  */
 export function copyRootEnvFiles(worktreePath, root) {
   let names;
@@ -659,32 +366,16 @@ export function copyRootEnvFiles(worktreePath, root) {
     const dst = join(worktreePath, name);
     try {
       if (!lstatSync(join(root, name)).isFile()) continue;
-      try { lstatSync(dst); continue; } catch { /* absent — not even a dangling link */ }
+      try { lstatSync(dst); continue; } catch {}
       execFileSync('git', ['check-ignore', '-q', '--', name], { cwd: worktreePath, stdio: 'pipe' });
       copyFileSync(join(root, name), dst);
       copied.push(name);
-    } catch { /* not ignored, unreadable or unwritable — leave it out */ }
+    } catch {}
   }
   return copied;
 }
 
-/**
- * Non-exiting core of `worktree provision` — the tree `claude -w`,
- * `EnterWorktree` and `Agent isolation:"worktree"` ask for when the name is
- * not a feature. Everything `setup` gives a feature worktree EXCEPT the
- * feature identity: it lands under `<primary root>/worktrees/<name>` (never
- * nested under a secondary worktree, whatever the cwd), on `morph-task/<name>`
- * off the default branch (or `--base`), with the infra junctions, a git-
- * invisible `.morph/worktree.env` keyed `task/<name>`, and a materialized
- * local state.json. No feature registration, no handoff.
- *
- * Exit codes mirror `setup`: 0 created (or fail-open), 1 refused (bad name),
- * 2 already exists at this exact path.
- *
- * @param {string} name
- * @param {{ base?: string, cwd?: string }} [options]
- * @returns {Promise<{ ok: boolean, exitCode: 0|1|2, created: boolean, alreadyExists?: boolean, path?: string, branch?: string, branchedFrom?: string|null, kind?: 'task-isolation', name: string, env?: object, error?: string }>}
- */
+/** Non-exiting core of `worktree provision`: `setup` without the feature identity. Exit codes mirror `setup`. */
 export async function runWorktreeProvision(name, options = {}) {
   const cwd = options.cwd || process.cwd();
 
@@ -695,9 +386,7 @@ export async function runWorktreeProvision(name, options = {}) {
     return { ok: true, exitCode: 0, created: false, error: 'not-a-git-repo', name };
   }
 
-  // Always the PRIMARY root: a provision issued from inside a feature worktree
-  // must not nest a worktree under it — that tree would be invisible to the
-  // fleet and to doctor, which enumerate `<root>/worktrees/`.
+  // Always the PRIMARY root: a tree nested under a feature worktree is invisible to fleet and doctor.
   const root = resolvePrimaryRoot(cwd);
   const branch = buildTaskBranchName(name);
   const worktreePath = buildWorktreePath(name, root);
@@ -755,34 +444,17 @@ export async function runWorktreeProvision(name, options = {}) {
   }
 }
 
-/**
- * `morph-spec worktree provision <name> [--base <ref>]` — thin wrapper around
- * `runWorktreeProvision`, same JSON-and-exit contract as `setup`.
- * @param {string} name
- * @param {{ base?: string, cwd?: string }} [options]
- */
 export async function worktreeProvisionCommand(name, options = {}) {
   const { ok, exitCode, ...result } = await runWorktreeProvision(name, options);
   console.log(JSON.stringify(result));
   process.exit(exitCode);
 }
 
-/**
- * Command handler for `morph-spec worktree link [--target <path>] [--all]`.
- *
- * (Re)links shared infrastructure (node_modules by default; also .claude and
- * .morph/framework with --all) from the primary root into a worktree. Useful
- * to repair/refresh junctions without recreating the whole worktree.
- * Idempotent — already-present junctions are reported as skipped, not re-created.
- *
- * @param {{ target?: string, all?: boolean, cwd?: string }} [options]
- */
 export async function worktreeLinkCommand(options = {}) {
   const cwdArg = options.cwd || process.cwd();
   const root = resolvePrimaryRoot(cwdArg);
   const target = resolve(options.target || options.cwd || process.cwd()).replace(/\\/g, '/');
 
-  // No-op: linking the primary root into itself makes no sense.
   if (target === root) {
     console.log(JSON.stringify({ linked: [], skipped: ['is-primary-root'], root, target }));
     process.exit(0);
@@ -790,7 +462,7 @@ export async function worktreeLinkCommand(options = {}) {
 
   if (!isGitRepo(cwdArg)) {
     console.log(JSON.stringify({ error: 'not-a-git-repo' }));
-    process.exit(0); // Fail-open
+    process.exit(0);
   }
 
   const dirs = options.all
@@ -808,18 +480,15 @@ export async function worktreeLinkCommand(options = {}) {
   const skipped = [];
   for (const rel of dirs) {
     if (alreadyPresent[rel]) {
-      skipped.push(rel); // already there before this call
+      skipped.push(rel);
     } else if (existsSync(join(target, rel))) {
-      linked.push(rel); // newly created by setupInfraLinks
+      linked.push(rel);
     } else {
-      skipped.push(rel); // nothing to link (source missing in root, or link failed)
+      skipped.push(rel);
     }
   }
 
-  // `link --all` is the documented repair for a worktree missing its infra —
-  // that includes a `.morph/worktree.env` written by an older layout. The
-  // allocation is idempotent (same key → same block), so regenerating the
-  // manifest never moves a worktree's ports; it only adds the keys it lacks.
+  // Allocation is idempotent (same key → same block): regenerating never moves a worktree's ports.
   let env = null;
   if (options.all) {
     const key = envKeyForWorktree(target, root);
@@ -831,15 +500,7 @@ export async function worktreeLinkCommand(options = {}) {
   process.exit(0);
 }
 
-/**
- * The env-registry key of a worktree, derived from its branch: `morph/<f>` →
- * `<f>` (feature), `morph-task/<n>` → `task/<n>` (task isolation). `null` for
- * a branch morph does not own — no block is allocated for those.
- *
- * @param {string} worktreePath
- * @param {string} root
- * @returns {string|null}
- */
+/** `morph/<f>` → `<f>`, `morph-task/<n>` → `task/<n>`, `null` for a branch morph does not own. */
 export function envKeyForWorktree(worktreePath, root) {
   const norm = resolve(worktreePath).replace(/\\/g, '/');
   const entry = parseWorktreeList(root).find((e) => e.path === norm);
@@ -852,26 +513,8 @@ export function envKeyForWorktree(worktreePath, root) {
 }
 
 /**
- * Allocate (idempotently) the port block for `envKey` and write the worktree's
- * `.morph/worktree.env`, excluded from git via the same common-dir mechanism as
- * the infra links (it must be invisible to the finish clean-checks). Under
- * `.morph/` on purpose: that prefix is already shieldable at finish (backed up,
- * never a removal blocker). Fail-open: returns `null` when no block could be
- * written — a worktree without ports is degraded, never broken.
- *
- * Shared by `setup` (feature key), `provision` (task key) and `link --all`
- * (regeneration), so the manifest has exactly one writer.
- *
- * `morphFeature` (task trees born from `morph/<f>`) only renames the
- * `MORPH_FEATURE` line. Left undefined — the `link --all` regeneration, which
- * derives the key from the branch and cannot see the base — the value the
- * file already carries is kept, so a repair never forgets the feature.
- *
- * @param {string} worktreePath
- * @param {string} root - primary root
- * @param {string} envKey - `<feature>` or `task/<name>`
- * @param {{ morphFeature?: string|null }} [opts]
- * @returns {Promise<{ index: number, base: number, range: [number, number] }|null>}
+ * The manifest's single writer. Without `morphFeature` (the `link --all` repair) the MORPH_FEATURE
+ * already in the file is kept. `null` when no block could be written.
  */
 export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFeature } = {}) {
   const envPath = join(worktreePath, '.morph', 'worktree.env');
@@ -894,7 +537,7 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFea
       const cfg = JSON.parse(readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
       stack = cfg?.project?.stack || '';
       aliases = resolvePortAliases(cfg).aliases;
-    } catch { /* fail-open — stackless env still carries PORT */ }
+    } catch {}
     mkdirSync(join(worktreePath, '.morph'), { recursive: true });
     writeFileSync(envPath, buildEnvFileContent(envKey, block, stack, { morphFeature, aliases }), 'utf8');
     excludeWorktreePaths(root, [join('.morph', 'worktree.env')]);
@@ -904,14 +547,7 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFea
   }
 }
 
-// ── finish / list shared helpers ────────────────────────────────────────────
-
-/**
- * Parse `git worktree list --porcelain` into structured entries.
- * Fail-open: returns `[]` on any git error (e.g. not a git repo).
- * @param {string} cwd
- * @returns {Array<{ path: string, branch: string|null, head: string|null, locked: boolean }>}
- */
+/** Fail-open: `[]` on any git error. */
 export function parseWorktreeList(cwd) {
   let output;
   try {
@@ -939,22 +575,8 @@ export function parseWorktreeList(cwd) {
 }
 
 /**
- * Locate the registered worktree for a feature's `morph/{feature}` branch.
- * Primary strategy: match the `branch refs/heads/morph/{feature}` entry from
- * `git worktree list --porcelain`. Fallback: the conventional
- * `buildWorktreePath` location, but only if it is itself a registered
- * worktree entry (so a stray directory never gets mistaken for a live one).
- *
- * Returns the branch the worktree is ACTUALLY on, never the computed one. Via
- * the path fallback the two can diverge (the user checked out something else in
- * there), and reporting the computed name would make `finish` merge
- * `morph/{feature}` while removing a worktree holding unrelated work — merging a
- * branch it never validated, which is the whole failure this command guards
- * against. The caller compares the two and refuses on mismatch.
- *
- * @param {string} feature
- * @param {string} root - Primary root path
- * @returns {{ path: string, branch: string, expectedBranch: string }|null}
+ * Returns the branch the worktree is ACTUALLY on, never the computed one: via the path fallback they
+ * can diverge, and the caller refuses on mismatch rather than merge a branch it never validated.
  */
 export function findWorktreeForFeature(feature, root) {
   const expectedBranch = buildBranchName(feature);
@@ -968,41 +590,13 @@ export function findWorktreeForFeature(feature, root) {
   }
   if (!match) return null;
 
-  // A detached HEAD has no branch at all — report it as such rather than
-  // inventing the computed name for it.
   const actual = match.branch ? match.branch.replace(/^refs\/heads\//, '') : null;
   return { path: match.path, branch: actual, expectedBranch };
 }
 
 /**
- * Drop the infra junctions a worktree carries (`node_modules`, `.claude`,
- * `.morph/framework`, and the `project.frontendPath` node_modules if
- * configured) WITHOUT following them.
- *
- * CRITICAL — this is what keeps `morph-spec finish` (worktree teardown) from
- * destroying the project. `git worktree remove` refuses a worktree still holding these ("contains
- * modified or untracked files"), and the `--force` fallback FOLLOWS the
- * junctions and deletes the PRIMARY ROOT's real `.claude/` and
- * `.morph/framework/` — wiping the morph-spec installation (MORPH.md, agents,
- * skills, settings) while still reporting `finished: true`. On a short path the
- * wipe is total and silent; on a long one MAX_PATH aborts it midway, leaving
- * partial damage plus an orphan directory. Removing the reparse points first
- * lets the plain (non-force) removal succeed and leaves `--force` nothing to
- * traverse.
- *
- * Only links are touched: `unlinkSync`/`rmdirSync` act on the LINK, never on the
- * target's contents, and `rmdirSync` fails on a real non-empty directory — the
- * safety that stops this from ever deleting genuine files.
- *
- * This is deliberately narrow to the KNOWN inventory from `resolveInfraLinkDirs`
- * — never widened to auto-remove any reparse point `findReparsePoints` might
- * discover elsewhere. An unknown/nested link (npm link, npm workspaces) must
- * still decline the removal; see the CANARY tests pinning that in worktree.test.js.
- *
- * @param {string} worktreePath
- * @param {string} mainCwd - Absolute path to the main project root, to resolve
- *   `project.frontendPath` from config.json
- * @returns {string[]} relative paths actually unlinked
+ * Must run before `git worktree remove`: its `--force` fallback FOLLOWS junctions and deletes the root's
+ * real `.claude/` and `.morph/framework/`. Only the known inventory, never any reparse point found.
  */
 export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
   const removed = [];
@@ -1012,7 +606,7 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
     try {
       st = lstatSync(p);
     } catch {
-      continue; // absent — nothing to drop
+      continue;
     }
     if (!st.isSymbolicLink() && !st.isDirectory()) continue;
     try {
@@ -1028,36 +622,10 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
   return removed;
 }
 
-/**
- * Gitignored paths a morph worktree owns and that are safe to remove — but ONLY
- * once backed up (see writeWorktreeIgnoredBackup). `.morph/state.json` is provably
- * derivable (loadState self-heals it from the committed feature.json files) and
- * the rest is morph's own diagnostic output, which `setupInfraLinks` documents
- * as worktree-local. They are small, so backing them up costs nothing and buys
- * the guarantee that this list does not have to be RIGHT.
- *
- * `node_modules` is deliberately NOT here: it is regenerable from the lockfile,
- * far too large to copy, and `unlinkWorktreeInfraLinks` already dropped it when
- * it is the junction `setup` creates. A real one left behind blocks removal —
- * safe, and the user can clear it themselves.
- */
+// Safe to remove only once backed up. `node_modules` is not here: regenerable and too large to copy.
 const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
 
-/**
- * Whether a dirty root-side path is EXACTLY a sibling feature's live worktree
- * registration — see the call site (primaryRootUnexplainedDirt, the root-clean
- * gate `morph-spec finish` uses) for why this is safe to exempt from the
- * whole-root clean gate rather than a widened hole.
- *
- * PROVES it rather than assuming: the path must be exactly that sibling's
- * `feature.json`, must parse, and its `worktree.path` must point at a
- * currently-existing directory. A parse failure, a missing registration, or a
- * STALE pointer (worktree already removed) is NOT exempted.
- *
- * @param {string} relPath - forward-slash path relative to `root`
- * @param {string} root - absolute path to the primary root
- * @param {string} feature - the feature THIS finish is acting on (never exempted — its own scope is the shed's job)
- */
+/** PROVES it: exactly the sibling's feature.json, parseable, and `worktree.path` an existing dir. */
 function isLiveSiblingWorktreeRegistration(relPath, root, feature) {
   const m = relPath.match(/^\.morph\/features\/([^/]+)\/feature\.json$/);
   if (!m || m[1] === feature) return false;
@@ -1071,61 +639,14 @@ function isLiveSiblingWorktreeRegistration(relPath, root, feature) {
 }
 
 /**
- * Split the worktree's GITIGNORED leftovers into what this command may delete
- * outright, what it must COPY OUT first, and what it cannot even enumerate.
- *
- * Why this exists: `git worktree remove` deletes gitignored files outright, and
- * the clean-check that gates it uses `git status --porcelain`, which omits them
- * BY DESIGN. So a user's `.env` or a local override is invisible to that gate
- * and dies silently while the command reports success. Git treats gitignored as
- * disposable; morph must not, because "not in git" is exactly the property that
- * makes a file unrecoverable.
- *
- * The buckets, and why refusing is no longer one of them: the earlier version
- * blocked on ANY unrecognised gitignored path, which in practice meant blocking
- * on `.env` files that were byte-identical to the primary root's — nothing was
- * at stake, and the only escape offered (`--discard-ignored`) also destroyed the
- * genuinely unique `keys/` next to them. `triageIgnoredPaths` answers the
- * question that actually decides whether bytes are lost (see ignored-triage.js),
- * so the command can PROCEED in every case, backing up only what exists nowhere
- * else. A refusal survives for exactly one reason now: the backup FAILED.
- *
- *   shieldable — morph's own bookkeeping + anything EXCLUSIVE to this worktree.
- *                Copied to `finish-backup` before the removal; a failed copy is
- *                what declines the removal.
- *   discarded  — build artifacts (regenerable) and REPLICABLE files (the root
- *                holds the same path with the same SHA-256). Deleted without a
- *                backup because neither loses bytes.
- *   blocking   — the fail-CLOSED sentinel only: `git status --ignored` itself
- *                failed, so we cannot enumerate what is at stake.
- *
- * `--discard-ignored` no longer means "destroy the unique ones too, blind"; it
- * means SKIP THE BACKUP — the same removal, without the copy.
- *
- * @param {string} worktreePath
- * @param {string} rootPath - the primary root, for the replica comparison
- * @param {{ discardIgnored?: boolean }} options
- * @returns {{ shieldable: string[], blocking: string[], discarded: string[], replicable: string[] }}
- *
- * EXPORTADA para que o `finish --dry-run` (pré-voo) responda EXATAMENTE a
- * mesma pergunta que o teardown real vai responder. Uma segunda enumeração de
- * `git status --ignored` no finish.js — com a sua própria cópia de
- * IGNORED_SHIELDABLE_PREFIXES — faria o pré-voo prometer uma coisa e o
- * comando fazer outra, que é a única maneira de um dry-run ser pior que
- * nenhum. Consumida read-only: o pré-voo não copia, não apaga, não decide.
+ * `git worktree remove` deletes gitignored files and `git status --porcelain` omits them. shieldable:
+ * backed up first; discarded: build artifacts and replicas of the root; blocking: enumeration failed.
  */
 export function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
   let out;
   try {
-    // `-z` + execFile: NUL-delimited, no shell, no C-style quoting to undo —
-    // paths with spaces or non-ASCII (a pt-BR codebase has both) stay intact.
-    // `=matching` (not the traditional default): an ignored directory whose own
-    // name matches no pattern — e.g. `MyProj/`, ignored only because EVERYTHING
-    // inside it (`bin/`, `obj/`) does — otherwise collapses into one opaque
-    // `MyProj/` entry, hiding the actual disposable-artifact names from
-    // isDisposableBuildArtifact. A directory that IS itself the matched pattern
-    // (`node_modules/`) still reports as one entry either way — verified
-    // empirically, not assumed.
+    // `-z` + execFile: NUL-delimited, no shell quoting. `=matching`: otherwise a dir ignored only through
+    // its children (`MyProj/` via `bin/`, `obj/`) collapses into one entry, hiding the artifact names.
     out = execFileSync('git', ['status', '--porcelain', '--ignored=matching', '-z'], { cwd: worktreePath, stdio: 'pipe' }).toString();
   } catch {
     return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'], discarded: [], replicable: [] };
@@ -1144,45 +665,20 @@ export function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
   const { replicable, disposable, exclusive } = triageIgnoredPaths({ worktreePath, rootPath, paths: rest });
   const shieldable = [...morphOwned, ...exclusive];
 
-  // Explicit consent = SKIP THE BACKUP, not "widen what dies". The same paths
-  // are removed either way; the flag only decides whether a copy is made first.
-  // The list is never thrown away — these are the bytes that exist nowhere
-  // else, and reporting them is the least this can do.
+  // Consent = SKIP THE BACKUP, not widen what dies; the list is still reported.
   if (options.discardIgnored) {
     return { shieldable: [], blocking: [], discarded: [...disposable, ...replicable, ...shieldable], replicable };
   }
   return { shieldable, blocking: [], discarded: [...disposable, ...replicable], replicable };
 }
 
-// ── finish primitives (used by `morph-spec finish`) ───────────────────────
-//
-// The old `worktree finish` command dissolved here: `morph-spec finish` (see
-// src/commands/state/finish.js) now orchestrates archive → integrate (merge OR
-// PR) → teardown for BOTH the worktree and the common flow. These exported
-// primitives keep the load-bearing safety (shed with backup, prove-or-decline
-// worktree removal) in one hardened place, shared by every integration path.
-
-/**
- * Shed the feature's OWN transient root-side bookkeeping so the merge can own
- * this feature's state while the whole-root clean-check keeps guarding UNRELATED
- * work. Backs up FIRST (see writeFeatureScopeBackup), then discards — the shed
- * is safe WITHOUT having to be right about what is in scope: if the
- * classification the merge implies turns out wrong, the bytes are still on
- * disk. Worktree-flow only; the common flow committed the archive on the
- * branch, so there is no untracked root-side scaffold to shed.
- *
- * @param {string} root
- * @param {string} feature
- * @param {{ stamp?: string }} [opts] - the finish's one stamp, shared with the
- *   teardown's backup so the two folders count as one backup
- * @returns {{ shedBackup: string|null }} backup path if anything was shed
- */
+/** Backs up FIRST, then discards: safe without being right about what is in scope. */
 export function shedRootFeatureScope(root, feature, { stamp } = {}) {
   const featPathspec = `.morph/features/${feature}`;
   let dirtyInScope = '';
   try {
     dirtyInScope = execFileSync('git', ['status', '--porcelain', '-uall', '--', featPathspec], { cwd: root, stdio: 'pipe' }).toString();
-  } catch { /* nothing in scope */ }
+  } catch {}
 
   if (dirtyInScope.trim() === '') return { shedBackup: null };
 
@@ -1190,41 +686,21 @@ export function shedRootFeatureScope(root, feature, { stamp } = {}) {
   // No backup, no shed. Falling through leaves the root dirty, so the caller's
   // clean-check refuses — the exact fail-closed behaviour from before any shed.
   if (shedBackup) {
-    try { execFileSync('git', ['checkout', '--', featPathspec], { cwd: root, stdio: 'pipe' }); } catch { /* nothing tracked to restore */ }
-    try { execFileSync('git', ['clean', '-fdq', '--', featPathspec], { cwd: root, stdio: 'pipe' }); } catch { /* nothing untracked to clean */ }
+    try { execFileSync('git', ['checkout', '--', featPathspec], { cwd: root, stdio: 'pipe' }); } catch {}
+    try { execFileSync('git', ['clean', '-fdq', '--', featPathspec], { cwd: root, stdio: 'pipe' }); } catch {}
   }
   return { shedBackup };
 }
 
 /**
- * The primary root's uncommitted paths that are NOT explained — everything
- * except a SIBLING feature's own LIVE worktree registration (see
- * isLiveSiblingWorktreeRegistration, the exemption that keeps one open sibling
- * from blocking every other feature's finish). `ok:false` means the status call
- * itself failed; an empty `dirt` means clean enough to merge into.
- *
- * `exemptOwnScope` additionally forgives everything under
- * `.morph/features/{feature}/` — the EXACT pathspec `shedRootFeatureScope`
- * backs up and discards. It exists so `finish` can ask "is the root clean
- * enough to merge into?" BEFORE archiving anything, where the shed has not run
- * yet and the feature's own scaffold is still on disk. Without it that early
- * question answers "dirty" for a root that the shed would have cleaned, and a
- * finish that works today would start being refused.
- *
- * Callers must keep the post-shed check: this one is an early refusal so the
- * archive never happens, not the authoritative gate.
- *
- * @param {string} root
- * @param {string} feature - the feature THIS finish acts on (its own scope is the shed's job)
- * @param {{ exemptOwnScope?: boolean }} [opts]
- * @returns {{ ok: boolean, dirt: string[] }}
+ * `exemptOwnScope` forgives `.morph/features/{feature}/` so `finish` can ask before the shed runs;
+ * callers must keep the post-shed check, the authoritative gate. `ok:false` = the status call failed.
  */
 export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
   let rootStatusRaw;
   try {
-    // `--untracked-files=all`, not the default: the default collapses an
-    // entirely-untracked directory into one entry, which would never match the
-    // exact `.../feature.json` path isLiveSiblingWorktreeRegistration expects.
+    // `--untracked-files=all`: the default collapses an untracked dir into one entry that never
+    // matches the exact `.../feature.json` path.
     rootStatusRaw = execFileSync('git', ['status', '--porcelain', '--untracked-files=all', '-z'], { cwd: root, stdio: 'pipe' }).toString();
   } catch {
     return { ok: false, dirt: [] };
@@ -1240,27 +716,8 @@ export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
 }
 
 /**
- * Clear the root-side `.worktree` registration for a finished feature. Runs
- * whenever the worktree is REMOVED — including `--pr`, where no merge landed —
- * so a stale registration never trips the anti-dupe guard or the next finish's
- * root-clean.
- *
- * A registration that was committed on the default branch is cleared by a commit
- * scoped to the feature's own pathspec. An untracked scaffold (what
- * `create --worktree` leaves at the root) is never committed: the branch owns
- * the feature, and committing the skeleton would put it on the default next to
- * the archived copy. When the feature is already archived the skeleton is shed,
- * backup first, by the same primitive `finish` uses.
- *
- * Written DIRECTLY (never saveState, which re-persists every sibling's
- * feature.json and can dirty the root outside this command's pathspec). The thin
- * root index carries only {status, updatedAt}, never `worktree`. Fail-open:
- * metadata cleanup is never a reason to fail an integration that already landed.
- *
- * @param {string} root
- * @param {string} feature
- * @param {{ stamp?: string }} [opts] - the caller's backup stamp, for the shed
- * @returns {Promise<{ shedBackup: string|null }>}
+ * Written DIRECTLY, never via saveState (which re-persists every sibling and can dirty the root
+ * outside this pathspec). An untracked scaffold is never committed. Fail-open.
  */
 export async function clearRootWorktreeRegistration(root, feature, { stamp } = {}) {
   const featPathspec = `.morph/features/${feature}`;
@@ -1275,7 +732,7 @@ export async function clearRootWorktreeRegistration(root, feature, { stamp } = {
         atomicWriteJson(rootFjPath, fj);
       }
     }
-  } catch { /* fail-open */ }
+  } catch {}
 
   try {
     const tracked = execFileSync('git', ['ls-files', '--', featPathspec], gitOpts).toString().trim() !== '';
@@ -1292,25 +749,7 @@ export async function clearRootWorktreeRegistration(root, feature, { stamp } = {
   return { shedBackup: null };
 }
 
-/**
- * Clear a feature's `worktree` registration ONLY when it's dangling — the
- * path it names no longer exists on disk (the directory was removed outside
- * `morph-spec finish`/`worktree remove`: by hand, by `git worktree prune`, or
- * by any tool that doesn't know about this pointer).
- *
- * Deliberately narrower than `clearRootWorktreeRegistration`: a registration
- * naming a worktree that's still ALIVE is not a bug to repair — it's the
- * anti-dupe guard's only signal (`runWorktreeSetup` Guard 3) and `verify`'s
- * only signal for which cwd may persist (`decidePersistence`). Clearing a
- * live registration would trade a true pointer for a false negative on both.
- *
- * Reuses `clearRootWorktreeRegistration` for the actual mutation (same
- * atomic-write + scoped-commit contract) once the dangling predicate holds.
- *
- * @param {string} root
- * @param {string} feature
- * @returns {Promise<{ cleared: boolean }>}
- */
+/** Only when the named path is gone: a LIVE registration is the anti-dupe guard's and `verify`'s only signal. */
 export async function clearDanglingWorktreeRegistration(root, feature) {
   try {
     const rootFjPath = join(root, '.morph', 'features', feature, 'feature.json');
@@ -1321,24 +760,11 @@ export async function clearDanglingWorktreeRegistration(root, feature) {
     await clearRootWorktreeRegistration(root, feature);
     return { cleared: true };
   } catch {
-    return { cleared: false }; // fail-open — malformed feature.json must never throw
+    return { cleared: false };
   }
 }
 
-/**
- * Why `git worktree remove` failed, from its stderr.
- *
- * The distinction that matters is `in-use` — on Windows a process whose cwd is
- * inside the worktree (another Claude Code instance, VS Code, a dev server, a
- * stray terminal) pins the directory and the removal cannot proceed. That is a
- * human-actionable cause with a specific fix ("close it"), and printing it is
- * the difference between a message the user can act on and one that just says
- * "failed" — which is what made a raw `git worktree remove --force` look like
- * the only way forward.
- *
- * @param {string} stderr
- * @returns {{ kind: 'in-use'|'unknown', detail: string }}
- */
+/** `in-use` (a process holding the dir on Windows) needs a human, so it is named apart. */
 function classifyRemovalError(stderr) {
   const text = String(stderr || '').trim();
   const inUse = /permission denied|EPERM|EBUSY|being used by another process|resource busy|access is denied|is locked/i.test(text);
@@ -1349,19 +775,8 @@ function classifyRemovalError(stderr) {
 }
 
 /**
- * Run the removal, with one retry round after a short pause.
- *
- * The retry exists for the transient Windows handle (antivirus/indexer touching
- * a file mid-removal) — the same class the repo already retries in
- * `atomicWriteJson`. It deliberately does NOT help the `in-use` case: a held
- * directory stays held, and that one needs the human, not another attempt.
- *
- * `--force` is safe HERE and only here: the caller proved `blockers.length ===
- * 0` before calling, so there is nothing left for it to traverse out of.
- *
- * @param {string} worktreePath
- * @param {string} root
- * @returns {Promise<{ removed: boolean, failure: {kind: string, detail: string}|null }>}
+ * One retry for transient Windows handles (antivirus/indexer); it does not help `in-use`.
+ * `--force` is safe only here: the caller proved there are no blockers.
  */
 async function attemptWorktreeRemoval(worktreePath, root) {
   const stderrs = [];
@@ -1379,19 +794,7 @@ async function attemptWorktreeRemoval(worktreePath, root) {
   return { removed: false, failure: pickRemovalFailure(stderrs) };
 }
 
-/**
- * Which of the attempts' errors the user should read.
- *
- * The LAST one used to win, and it was the worst choice: when the first
- * `git worktree remove` deletes the content and de-registers the tree but the
- * directory itself is held (a session with its cwd there), every later attempt
- * answers only `'…' is not a working tree` — an echo that hid the real cause
- * (the lock) and made the hint send the user to a command that can no longer
- * reach the tree. A lock anywhere wins; otherwise the first REAL error wins.
- *
- * @param {string[]} stderrs - one entry per failed attempt, in order
- * @returns {{ kind: string, detail: string, alreadyDeregistered: boolean }}
- */
+/** A lock anywhere wins, else the first REAL error: later attempts only echo "is not a working tree". */
 export function pickRemovalFailure(stderrs) {
   const list = (stderrs || []).map((s) => String(s || '')).filter((s) => s.trim());
   const notAWorktree = (s) => /is not a working tree/i.test(s);
@@ -1407,58 +810,20 @@ export function pickRemovalFailure(stderrs) {
 }
 
 /**
- * Remove a feature's worktree after its branch is integrated — PROVE-or-DECLINE.
- * The single most dangerous step in the lifecycle, so it declines whenever it
- * cannot prove removal is safe. Two independent ways `git worktree remove`
- * (plain AND `--force`) destroys data, both ending in an exit-0 removal:
- *   1. it FOLLOWS reparse points out of the worktree and deletes what they point
- *      at in the primary root (the real `.claude/`, `.morph/framework/`);
- *   2. it deletes GITIGNORED files outright — a user's `.env` is not disposable,
- *      and the clean-check cannot see them.
- *
- * A non-removal comes in two flavours the caller must not conflate — see the
- * rollback comment below. `refused` (we proved it unsafe) restores the infra
- * junctions; a FAILURE (git errored) deliberately leaves them down, reported in
- * `infraLeftUnlinked`.
- *
- * `deleteBranch` decouples `git branch -d` from removal: true for `--merge` (the
- * branch is integrated), false for `--pr` (the open PR still needs the branch).
- *
- * `stamp` names the backup; `finish` passes the one it gave the shed, so both
- * folders of that finish count as one backup under the retention.
- *
- * `relinkOnFailure` (the agent reaper) also restores the junctions when git
- * FAILED, not only when we refused: the reaper removes trees on a schedule, and
- * a lock that leaves a possibly-live agent without `.claude` kills its hooks.
- * Off by default — a person retrying a failed removal by hand is what the
- * unlinked state protects. A tree git already de-registered has nothing to link.
- *
- * @param {string} worktreePath
- * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean, stamp?: string }} ctx
- * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
- *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null,
- *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
- *   removalFailure: {kind: string, detail: string}|null, rootShedBackup: string|null }>}
+ * PROVE-or-DECLINE. `refused` (proved unsafe) restores the junctions; a git FAILURE leaves them down
+ * (`infraLeftUnlinked`) unless `relinkOnFailure` (the reaper, whose agent may still be live).
  */
 export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, relinkOnFailure = false, stamp }) {
-  // Drop the infra junctions FIRST, without following them — this is what makes
-  // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
-  //
-  // The ORDER IS LOAD-BEARING and must not be flipped: `git worktree remove`
-  // (and its --force fallback) follows reparse points OUT of the worktree and
-  // deletes the primary root's real `.claude/` and `.morph/framework/`.
-  // Whatever this unlink costs on a declined path is repaired by the rollback
-  // below — the reverse ordering has no repair, it destroys the installation.
+  // ORDER IS LOAD-BEARING: unlink the junctions BEFORE git touches the dir. `git worktree remove`
+  // follows them and deletes the root's installation; a declined path is repaired by the rollback below.
   const unlinked = unlinkWorktreeInfraLinks(worktreePath, root);
 
   const scan = findReparsePoints(worktreePath);
   const ignored = classifyIgnoredLeftovers(worktreePath, root, options);
   const blockers = [...scan.points, ...scan.unprovable];
 
-  // Back up ONLY once the removal is otherwise cleared: nothing is destroyed on
-  // a declined path (copying there is waste), and `blockers.length === 0` proves
-  // no reparse point exists — cpSync follows junctions, so backing up before
-  // that proof could copy an out-of-repo tree of unbounded size.
+  // Back up only once removal is cleared: `blockers.length === 0` proves no reparse point, and
+  // cpSync follows junctions (it could copy an unbounded out-of-repo tree).
   let ignoredBackup = null;
   const clearedToRemove = blockers.length === 0 && ignored.blocking.length === 0;
   if (clearedToRemove && ignored.shieldable.length) {
@@ -1472,41 +837,25 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   if (canRemove) {
     const attempt = await attemptWorktreeRemoval(worktreePath, root);
     worktreeRemoved = attempt.removed;
-    removalFailure = attempt.failure; // null once removed
+    removalFailure = attempt.failure;
   }
 
   if (worktreeRemoved) {
-    // Three independent axes: remove-worktree (done), delete-branch (mode), and
-    // release-env (worktree existed and is gone). `--pr` removes the worktree
-    // but keeps the branch the open PR needs.
+    // `--pr` removes the worktree but keeps the branch the open PR needs.
     if (deleteBranch) {
-      try { execFileSync('git', ['branch', '-d', branch], { cwd: root, stdio: 'pipe' }); } catch { /* fail-open */ }
+      try { execFileSync('git', ['branch', '-d', branch], { cwd: root, stdio: 'pipe' }); } catch {}
     }
-    try { execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' }); } catch { /* fail-open */ }
-    // Fleet env: the worktree is gone, so no server can be running on its block.
+    try { execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' }); } catch {}
     try {
       const { releaseEnvBlock } = await import('../../lib/worktree/env-allocator.js');
       const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
       if (common) releaseEnvBlock(feature, { gitCommonDir: resolve(root, common) });
-    } catch { /* fail-open */ }
+    } catch {}
     ({ shedBackup: rootShedBackup } = await clearRootWorktreeRegistration(root, feature, { stamp }));
   }
 
-  // Rollback (A4) — ONLY on a REFUSAL, never on a FAILURE. The two look alike
-  // (worktree still there, junctions dropped) and must be treated as opposites:
-  //
-  //   REFUSED (`!canRemove`): we proved removal unsafe, so the user keeps
-  //     working in this worktree. Leaving the junctions down is "um estado pior
-  //     que não ter tentado" — put them back.
-  //   FAILED (`canRemove` but git errored): removal WAS the user's intent and
-  //     the only obstacle is a lock. Re-linking here would restore the exact
-  //     hazard that destroyed installations — the retry (ours, theirs, or a raw
-  //     `git worktree remove --force` pasted from an old transcript) would then
-  //     follow the junctions out. Leaving them down makes EVERY subsequent
-  //     attempt safe, because there is nothing left to traverse.
-  //
-  // Fail-open on the refusal path: a failed re-link reports `relinked: false`
-  // and the caller falls back to telling the user to run `worktree link --all`.
+  // Relink ONLY on a REFUSAL: on a FAILURE removal was intended and only a lock remains; relinking
+  // would make the next retry (or a raw `--force`) follow the junctions out.
   const refused = !canRemove;
   let relinked = false;
   const relinkAfterFailure = relinkOnFailure && !refused && !worktreeRemoved && !removalFailure?.alreadyDeregistered;
@@ -1516,21 +865,10 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
       relinked = true;
     } catch { relinked = false; }
   }
-  // What the caller must tell the user about on the FAILURE path: the worktree
-  // survived without its shared infra, on purpose.
   const infraLeftUnlinked = (!worktreeRemoved && !refused && !relinked) ? unlinked : [];
 
-  // Every branch names `morph-spec worktree remove` and NEVER `git worktree
-  // remove`. The raw command follows the junctions this function manages, and a
-  // decline is exactly the moment a frustrated reader copies whatever command
-  // the tool just printed — that copy is what emptied a primary root's
-  // `.claude/` and `.morph/framework/`. `worktree remove` re-runs this same
-  // PROVE-or-DECLINE path and accepts the same `--discard-ignored` consent, so
-  // there is no decline left where the raw command would be the right answer.
-  // A worktree with no feature identity (the ones `isolation: "worktree"`
-  // creates) can only be re-addressed by path — naming a feature that does not
-  // resolve would hand the reader a command that FAILS, and a failing safe
-  // command is exactly how people end up back at the raw one.
+  // Every hint names `morph-spec worktree remove`, NEVER `git worktree remove`: a frustrated reader
+  // copies what was printed. A tree with no feature identity is addressed by `--target` path.
   const removeCmd = (addressByTarget || !isValidFeatureName(feature))
     ? `morph-spec worktree remove --target "${worktreePath}"`
     : `morph-spec worktree remove ${feature}`;
@@ -1543,10 +881,6 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
       : blockers.length
         ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que a remoção seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`${removeCmd}\``
         : ignored.shieldable.length && ignoredBackup === null
-          // The ONLY gitignored refusal left. The old hint was circular — it
-          // said "salve o que importa e rode <the command that just failed>".
-          // This one names WHAT is exclusive, what was replicable (so the
-          // reader stops worrying about those), and WHERE the copy was going.
           ? `worktree NÃO removido: o backup falhou. Estes arquivos existem só neste worktree e a remoção os apagaria: ${sample(ignored.shieldable)}. `
             + (ignored.replicable.length ? `(${sample(ignored.replicable)} são idênticos aos da raiz — esses não são o problema.) ` : '')
             + `O backup iria para \`${backupDir}\`; libere espaço/permissão ali e rode \`${removeCmd}\`, ou copie os arquivos você mesmo e rode \`${removeCmd} --discard-ignored\` para pular o backup`
@@ -1569,12 +903,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     ignoredBackup,
     discarded: ignored.discarded,
     replicable: ignored.replicable,
-    // The infra reparse points this teardown dropped BEFORE letting git near
-    // the directory. Reported because it is the load-bearing safety step of the
-    // whole operation and was previously invisible: the user had no way to see
-    // that `.claude` was a junction into the primary root, nor that it was
-    // unlinked rather than followed. On a removal it is the proof the root's
-    // real `.claude/` was never at risk.
+    // Reported: the proof the root's real `.claude/` was unlinked, never followed.
     unlinked,
     blockers,
     ignoredBlocking: ignored.blocking,
@@ -1588,19 +917,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   };
 }
 
-/**
- * Is `cwd` the worktree we are about to remove, or inside it?
- *
- * Hoisted out of `finish` so BOTH callers share one answer. Windows holds a
- * lock on a process's working directory, so a removal issued from inside the
- * target fails — and in `finish`'s case it fails AFTER the archive is committed
- * and the branch merged, leaving an orphan directory and a de-registered
- * worktree. Refusing up front costs one `cd`.
- *
- * @param {string} cwd
- * @param {string} worktreePath
- * @returns {boolean}
- */
+/** Windows locks a process's cwd: removing from inside fails after the merge, so refuse up front. */
 export function cwdIsInsideWorktree(cwd, worktreePath) {
   const cwdNorm = resolve(cwd).replace(/\\/g, '/');
   const wtNorm = resolve(worktreePath).replace(/\\/g, '/');
@@ -1608,56 +925,15 @@ export function cwdIsInsideWorktree(cwd, worktreePath) {
 }
 
 /**
- * Is the Claude Code SESSION that ran this command anchored in the worktree?
- *
- * Not the same question as `cwdIsInsideWorktree`. That one sees the PROCESS
- * cwd, and `cd <root> && morph-spec finish` answers it "no" — while the session
- * stays anchored in the worktree: its CLAUDE_PROJECT_DIR is the worktree, and
- * every project hook runs `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/…"`.
- * Tearing that worktree down unlinks the junction those hooks resolve through,
- * and the directory stays held by the session — so the removal fails half-way
- * and every hook of every later tool call dies with MODULE_NOT_FOUND.
- *
- * The anchor arrives as MORPH_SESSION_PROJECT_DIR, exported by the
- * `worktree-env-inject` PreToolUse hook (the Bash tool does not export
- * CLAUDE_PROJECT_DIR itself); CLAUDE_PROJECT_DIR is honoured when present.
- *
- * @param {string} worktreePath
- * @param {NodeJS.ProcessEnv} [env]
- * @returns {boolean}
+ * The SESSION anchor, not the process cwd: tearing down the session's worktree kills every later hook
+ * (MODULE_NOT_FOUND). Read from MORPH_SESSION_PROJECT_DIR (set by worktree-env-inject) or CLAUDE_PROJECT_DIR.
  */
 export function sessionAnchoredInWorktree(worktreePath, env = process.env) {
   const anchor = env.MORPH_SESSION_PROJECT_DIR || env.CLAUDE_PROJECT_DIR || '';
   return anchor ? cwdIsInsideWorktree(anchor, worktreePath) : false;
 }
 
-// ── remove ───────────────────────────────────────────────────────────────
-
-/**
- * Non-exiting core of `morph-spec worktree remove <feature>` /
- * `morph-spec worktree remove --target <path>` — returns `{ out, code }` instead
- * of printing and exiting, so the agent reaper can call it in a loop.
- *
- * WHY THIS EXISTS: `teardownWorktree` — the only removal that drops the infra
- * junctions before letting git near the directory — used to be reachable ONLY
- * through `morph-spec finish`. So every message that had to tell a user how to
- * remove a worktree pointed at raw `git worktree remove`, which follows those
- * junctions out and empties the primary root's `.claude/` and
- * `.morph/framework/`. This command is the safe answer those messages now give.
- *
- * Two ways to address the target, because there are two kinds of worktree:
- *   <feature>       — a morph worktree, resolved through `findWorktreeForFeature`
- *   --target <path> — any registered worktree, including the ones the Agent
- *                     tool's `isolation: "worktree"` creates, which have no
- *                     feature registration for the lookup to find.
- *
- * It removes ONLY. No archive, no merge, and the branch survives by default —
- * closing a feature is still `morph-spec finish`.
- *
- * @param {string|undefined} featureArg
- * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, relinkOnFailure?: boolean, cwd?: string }} [options]
- * @returns {Promise<{ out: object, code: 0|1 }>}
- */
+/** Non-exiting core of `worktree remove`: removes ONLY, the branch survives by default. */
 export async function runWorktreeRemove(featureArg, options = {}) {
   const cwdArg = options.cwd || process.cwd();
   const outcome = (out, code) => ({ out, code });
@@ -1668,15 +944,11 @@ export async function runWorktreeRemove(featureArg, options = {}) {
   let worktreePath = null;
   let feature = featureArg || null;
   let branch = null;
-  // Can a re-run be addressed as `remove <feature>`? Only when the feature name
-  // is what resolved the worktree in the first place.
   let featureAddressable = !options.target;
 
   if (options.target) {
     worktreePath = resolve(options.target).replace(/\\/g, '/');
-    // The target MUST be a registered worktree. Without this the command would
-    // hand an arbitrary path to `git worktree remove` — and `--target ../..`
-    // is the same path-traversal class already fixed in delete/archive.
+    // Must be a registered worktree: `--target ../..` is a path traversal otherwise.
     const entry = parseWorktreeList(root).find((e) => e.path === worktreePath);
     if (!entry) {
       return outcome({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
@@ -1687,9 +959,6 @@ export async function runWorktreeRemove(featureArg, options = {}) {
         hint: 'a raiz primária nunca é removível por este comando' }, 1);
     }
     branch = entry.branch ? entry.branch.replace(/^refs\/heads\//, '') : null;
-    // Best-effort feature identity — used for the backup/env-release bookkeeping
-    // inside the teardown. A `morph/{f}` branch means `remove <feature>` would
-    // resolve too, so re-run advice may name it; anything else stays --target.
     if (!feature && branch?.startsWith('morph/')) {
       feature = branch.slice('morph/'.length);
       featureAddressable = isValidFeatureName(feature);
@@ -1708,30 +977,20 @@ export async function runWorktreeRemove(featureArg, options = {}) {
     branch = found.branch;
   }
 
-  // Same guard finish applies, for the same Windows reason — and this command
-  // is MORE likely to hit it: the natural moment to run it is right after
-  // working inside the worktree.
   if (cwdIsInsideWorktree(cwdArg, worktreePath)) {
     return outcome({ removed: false, error: 'cwd-inside-worktree', path: worktreePath, root,
       hint: `saia do worktree antes de removê-lo — o processo trava o próprio diretório de trabalho. Rode de novo a partir de "${root}"` }, 1);
   }
 
-  // The SESSION's anchor, not the process cwd (see sessionAnchoredInWorktree):
-  // refusing here, before the junctions are touched, leaves the session's hooks
-  // intact. Unlike finish there is nothing else to do in this command, so the
-  // refusal IS the deferral.
+  // The SESSION's anchor: refusing before the junctions are touched leaves its hooks intact.
   if (sessionAnchoredInWorktree(worktreePath)) {
     const again = featureAddressable && feature ? `morph-spec worktree remove ${feature}` : `morph-spec worktree remove --target "${worktreePath}"`;
     return outcome({ removed: false, error: 'session-anchored-in-worktree', path: worktreePath, root,
       hint: `a sessão do Claude Code que rodou este comando está ancorada neste worktree — os hooks dela resolvem \`.morph/framework\` por ele, e desmontá-lo quebraria todo tool call seguinte (e o diretório seguiria travado pela sessão). Feche esta sessão e rode \`${again}\` de uma sessão aberta em "${root}"` }, 1);
   }
 
-  // `--if-clean` — the WorktreeRemove hook's contract: Claude Code fires it
-  // when it believes the tree is disposable, but "disposable" is the user's
-  // call, not the harness's. Any uncommitted or untracked file refuses the
-  // removal BEFORE the junctions are touched, so a refusal leaves the tree
-  // exactly as it was (no rollback needed, nothing to relink). The infra
-  // links and the env manifest are excluded from git, so they never count.
+  // `--if-clean` (WorktreeRemove hook): any uncommitted file refuses BEFORE the junctions are touched.
+  // Infra links and the env manifest are excluded from git, so they never count.
   if (options.ifClean) {
     let status;
     try {
@@ -1747,27 +1006,18 @@ export async function runWorktreeRemove(featureArg, options = {}) {
     }
   }
 
-  // A leftover temporary .graphifyignore (a `graph refresh` killed mid-run) is a
-  // copy of the root's rules: not a file to back up. Deleted only now, after
-  // every refusal, so a refused removal leaves the tree as it was.
+  // Leftover temp .graphifyignore: deleted only after every refusal, so a refused removal leaves the tree as it was.
   dropLeftoverIgnore(worktreePath);
 
-  // The env-registry key this tree allocated under: `<f>` for morph/<f>,
-  // `task/<n>` for morph-task/<n>. Read BEFORE the teardown (the entry is gone
-  // from `git worktree list` afterwards). The old `'worktree'` placeholder
-  // meant every --target removal released a slot nobody held and leaked the
-  // one the tree actually used.
+  // Read BEFORE the teardown: the entry is gone from `git worktree list` afterwards.
   const envKey = envKeyForWorktree(worktreePath, root);
 
-  // The tree's compose stack goes down BEFORE the tree: a running bind-mounted
-  // container holds the directory (Windows) and turns a clean removal into a
-  // removalFailure. Volumes survive — removing a worktree is not closing the
-  // feature, and a re-`setup` should find its seeded database intact.
+  // Compose stack down BEFORE the tree: a bind-mounted container holds the dir on Windows. Volumes survive.
   let e2e = null;
   try {
     const { tearDownFeatureStack } = await import('../../lib/e2e/stack-teardown.js');
     e2e = tearDownFeatureStack(envKey || feature || basename(worktreePath), { root, worktreePath, volumes: false });
-  } catch { e2e = null; /* fail-open */ }
+  } catch { e2e = null; }
 
   // The stamp this removal's backup is written under — protected from the
   // retention that runs after it.
@@ -1778,8 +1028,7 @@ export async function runWorktreeRemove(featureArg, options = {}) {
     stamp,
     branch,
     options: { discardIgnored: options.discardIgnored === true },
-    // Removing a worktree is not closing a feature: the branch is the work, and
-    // deleting it here would discard unintegrated commits. Opt-in only.
+    // The branch is the work: deleting it would discard unintegrated commits. Opt-in only.
     deleteBranch: options.deleteBranch === true,
     relinkOnFailure: options.relinkOnFailure === true,
     // Re-run advice must address the worktree the way it was addressable here:
@@ -1793,16 +1042,10 @@ export async function runWorktreeRemove(featureArg, options = {}) {
     ...(branch ? { branch } : {}),
     ...(feature ? { feature } : {}),
   };
-  // Reported on BOTH paths: on a removal it is the proof the primary root's
-  // real `.claude/`/`.morph/framework/` were unlinked rather than followed; on
-  // a refusal it is what `relinked` did or did not put back.
   if (teardown.unlinked.length) out.unlinked = teardown.unlinked;
   if (e2e?.attempted) out.e2e = { status: e2e.status, cwd: e2e.cwd, volumes: false };
   if (teardown.worktreeRemoved) {
     if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
-    // Broken out of `discardedIgnored` on purpose: "deleted" and "deleted
-    // because the identical bytes are still in the root" are not the same
-    // report, and the second is the one that needs no follow-up from the user.
     if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
     if (teardown.shieldable.length) out.backedUp = teardown.shieldable;
@@ -1824,28 +1067,12 @@ export async function runWorktreeRemove(featureArg, options = {}) {
   return outcome(out, teardown.worktreeRemoved ? 0 : 1);
 }
 
-/**
- * `morph-spec worktree remove` — prints the JSON verdict and exits with its code.
- * @param {string|undefined} featureArg
- * @param {object} [options] - see `runWorktreeRemove`
- */
 export async function worktreeRemoveCommand(featureArg, options = {}) {
   const { out, code } = await runWorktreeRemove(featureArg, options);
   console.log(JSON.stringify(out));
   process.exit(code);
 }
 
-// ── list ─────────────────────────────────────────────────────────────────
-
-/**
- * Command handler for `morph-spec worktree list [--json]`.
- *
- * Lists active `morph/{feature}` worktrees with their derived phase, status,
- * and any pending approval gates — visibility across multi-instance sessions.
- * Fail-open: outside a git repo (or on any git error), reports an empty list.
- *
- * @param {{ json?: boolean, cwd?: string }} [options]
- */
 export async function worktreeListCommand(options = {}) {
   const cwd = options.cwd || process.cwd();
 
@@ -1864,7 +1091,7 @@ export async function worktreeListCommand(options = {}) {
 
     for (const entry of entries) {
       const m = entry.branch && entry.branch.match(/^refs\/heads\/morph\/(.+)$/);
-      if (!m) continue; // skip the primary root entry and any non-morph worktree
+      if (!m) continue;
       const feature = m[1];
 
       let phase = 'plan';
@@ -1892,7 +1119,6 @@ export async function worktreeListCommand(options = {}) {
   process.exit(0);
 }
 
-/** Render `worktree list` output — JSON or a human table (chalk). */
 function printWorktreeList(worktrees, options) {
   if (options.json) {
     console.log(JSON.stringify({ worktrees }));