@polymorphism-tech/morph-spec 7.9.4 → 8.0.0

package/src/commands/project/worktree.js

@@ -1,21 +1,43 @@
 /**
- * MORPH-SPEC Worktree Setup Command
+ * MORPH-SPEC Worktree Command Suite
  *
- * Creates a git worktree at .worktrees/{feature}/ on branch morph/{feature}.
- * Used by SessionStart hook to isolate feature work from the main branch.
+ * 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).
  *
- * Usage:
- *   morph-spec worktree setup <feature>
- *   morph-spec worktree setup <feature> --fresh
+ * `.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).
  *
- * Exit codes:
+ * Subcommands:
+ *   morph-spec worktree setup <feature> [--fresh]   — create + materialize state
+ *   morph-spec worktree link [--target <path>] [--all]  — (re)link shared infra
+ *   morph-spec worktree finish <feature> [--keep] [--force]  — merge-back + cleanup
+ *   morph-spec worktree list [--json]  — list active feature worktrees
+ *
+ * Exit codes (setup):
  *   0  — success (created) or fail-open (not a git repo, git error)
- *   2  — worktree already exists (signals resume scenario to hook caller)
+ *   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)
+ *
+ * Exit codes (finish):
+ *   0  — merged successfully (or fail-open in a non-git dir is not applicable here)
+ *   1  — refused: invalid feature name, no worktree found, the worktree is on a
+ *        different branch, Gate 3 not approved, worktree/root dirty, or merge
+ *        conflict. Every refusal is fail-CLOSED — no merge lands and no worktree
+ *        is removed. The shed runs before the root's clean check, so a refusal
+ *        from that point on has moved this feature's root-side scope to the
+ *        backup it reports; see worktreeFinishCommand.
  */
 
-import { execSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, linkSync, copyFileSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { execSync, execFileSync } from 'child_process';
+import { existsSync, mkdirSync, symlinkSync, readFileSync, lstatSync, unlinkSync, rmdirSync, readdirSync, cpSync } from 'fs';
+import { join, resolve, dirname, relative } from 'path';
+import chalk from 'chalk';
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -24,6 +46,24 @@ import { join, resolve, dirname } from 'path';
  * @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}
+ */
+export function isValidFeatureName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(name);
+}
+
 export function isGitRepo(cwd = process.cwd()) {
   try {
     execSync('git rev-parse --git-dir', { cwd, stdio: 'pipe' });
@@ -50,6 +90,17 @@ 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}
@@ -57,8 +108,7 @@ export function branchExists(branch, cwd = process.cwd()) {
 export function worktreeExists(worktreePath, cwd = process.cwd()) {
   try {
     const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
-    const normalizedPath = worktreePath.replace(/\\/g, '/');
-    const absPath = normalizedPath.startsWith('/') ? normalizedPath : `${cwd.replace(/\\/g, '/')}/${normalizedPath}`;
+    const absPath = resolve(cwd, worktreePath).replace(/\\/g, '/');
     return output.replace(/\\/g, '/').includes(absPath);
   } catch {
     return false;
@@ -96,26 +146,38 @@ function getDateSuffix() {
 // ── Infrastructure linking ───────────────────────────────────────────────────
 
 /**
- * Create symlinks/junctions in the worktree for shared infrastructure files
- * that are gitignored (state.json, .claude/, .morph/framework/, node_modules/).
+ * 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).
- * File symlinks fall back to copy if symlink fails.
  * 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).
  */
-export function setupInfraLinks(worktreePath, mainCwd) {
+export function setupInfraLinks(worktreePath, mainCwd, opts = {}) {
   const mainAbs = resolve(mainCwd);
   const wtAbs = resolve(worktreePath);
 
-  // Directory junctions — shared across worktrees
-  const dirLinks = ['node_modules', '.claude'];
-
-  // .morph/framework/ — client projects (in framework repo, framework/ is tracked)
-  if (existsSync(join(mainAbs, '.morph', 'framework'))) {
-    dirLinks.push(join('.morph', 'framework'));
+  let dirLinks;
+  if (Array.isArray(opts.dirs) && opts.dirs.length) {
+    dirLinks = opts.dirs;
+  } else {
+    dirLinks = ['node_modules', '.claude'];
+    // .morph/framework/ — client projects (in framework repo, framework/ is tracked)
+    if (existsSync(join(mainAbs, '.morph', 'framework'))) {
+      dirLinks.push(join('.morph', 'framework'));
+    }
   }
 
   for (const rel of dirLinks) {
@@ -128,38 +190,102 @@ export function setupInfraLinks(worktreePath, mainCwd) {
       symlinkSync(target, linkPath, 'junction');
     } catch { /* fail-open */ }
   }
+}
 
-  // state.json — shared state via hard link (works on Windows without admin,
-  // same NTFS volume). Falls back to symlink, then copy.
-  const stateTarget = join(mainAbs, '.morph', 'state.json');
-  const stateLink = join(wtAbs, '.morph', 'state.json');
-  if (existsSync(stateTarget) && !existsSync(stateLink)) {
-    const morphDir = join(wtAbs, '.morph');
-    if (!existsSync(morphDir)) {
-      try { mkdirSync(morphDir, { recursive: true }); } catch { /* */ }
+/**
+ * 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
+ */
+export function resolvePrimaryRoot(cwd = process.cwd()) {
+  try {
+    const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
+    const line = output.split('\n').find((l) => l.startsWith('worktree '));
+    if (line) {
+      return line.slice('worktree '.length).trim().replace(/\\/g, '/');
     }
-    try {
-      linkSync(stateTarget, stateLink); // hard link — no admin, shared data
-    } catch {
-      try { copyFileSync(stateTarget, stateLink); } catch { /* fail-open */ }
+  } catch { /* fall through to fail-open */ }
+  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 }>}
+ */
+export async function materializeState(worktreePath) {
+  const featuresDir = join(worktreePath, '.morph', 'features');
+  if (!existsSync(featuresDir)) {
+    return { materialized: false, reason: 'no-features' };
+  }
+
+  const prevCwd = process.cwd();
+  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.
+    if (existsSync(join(worktreePath, '.morph', 'state.json'))) {
+      return { materialized: true };
     }
+    return { materialized: false, reason: 'no-features-to-hydrate' };
+  } catch (err) {
+    return { materialized: false, reason: (err && err.message) || 'unknown' };
+  } finally {
+    process.chdir(prevCwd);
   }
 }
 
 // ── Command handler ─────────────────────────────────────────────────────────
 
 /**
- * Main command handler for `morph-spec worktree setup <feature>`
+ * 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
+ * @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.
  */
-export async function worktreeSetupCommand(feature, options = {}) {
+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.
+  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)) {
-    console.log(JSON.stringify({ created: false, error: 'not-a-git-repo', feature }));
-    process.exit(0); // Fail-open
+    return { ok: true, exitCode: 0, created: false, error: 'not-a-git-repo', feature };
   }
 
   const branch = buildBranchName(feature, options);
@@ -167,10 +293,29 @@ export async function worktreeSetupCommand(feature, options = {}) {
 
   // Gate 2: If worktree already registered and not --fresh, signal resume
   if (!options.fresh && worktreeExists(worktreePath, cwd)) {
-    console.log(JSON.stringify({ created: false, alreadyExists: true, path: worktreePath, branch, feature }));
-    process.exit(2); // Convention: 2 = already exists
+    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.)
+  try {
+    const featureJsonPath = join(cwd, '.morph', 'features', feature, 'feature.json');
+    if (existsSync(featureJsonPath)) {
+      const fj = JSON.parse(readFileSync(featureJsonPath, 'utf8'));
+      const existingPath = fj?.worktree?.path;
+      if (existingPath) {
+        const normalizedExisting = existingPath.replace(/\\/g, '/');
+        const normalizedNew = worktreePath.replace(/\\/g, '/');
+        if (normalizedExisting !== normalizedNew && existsSync(existingPath)) {
+          return { ok: false, exitCode: 3, created: false, error: 'worktree-exists-elsewhere', existingPath, feature };
+        }
+      }
+    }
+  } catch { /* fail-open — malformed feature.json must never block setup */ }
+
   try {
     // Create branch if needed (based off current HEAD)
     if (!branchExists(branch, cwd)) {
@@ -186,9 +331,13 @@ export async function worktreeSetupCommand(feature, options = {}) {
     // Add worktree
     execSync(`git worktree add "${worktreePath}" ${branch}`, { cwd, stdio: 'pipe' });
 
-    // Set up infrastructure symlinks so the worktree has state.json, .claude/, etc.
+    // Set up infrastructure junctions (node_modules, .claude, .morph/framework).
     setupInfraLinks(worktreePath, cwd);
 
+    // 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 materializeState(worktreePath);
+
     // 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.
@@ -203,10 +352,820 @@ export async function worktreeSetupCommand(feature, options = {}) {
       // Non-blocking
     }
 
-    console.log(JSON.stringify({ created: true, path: worktreePath, branch, feature }));
-    process.exit(0);
+    return {
+      ok: true,
+      exitCode: 0,
+      created: true,
+      path: worktreePath,
+      branch,
+      feature,
+      materialized: materialized.materialized,
+      nextStep: `Abra o Claude Code em ${worktreePath} para trabalhar nesta feature`,
+    };
   } catch (err) {
-    console.log(JSON.stringify({ created: false, error: (err.message || 'unknown').slice(0, 200), feature }));
+    return { ok: true, exitCode: 0, created: false, error: (err.message || 'unknown').slice(0, 200), feature };
+  }
+}
+
+/**
+ * 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);
+}
+
+/**
+ * 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 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);
+  }
+
+  if (!isGitRepo(cwdArg)) {
+    console.log(JSON.stringify({ error: 'not-a-git-repo' }));
     process.exit(0); // Fail-open
   }
+
+  const dirs = options.all
+    ? ['node_modules', '.claude', join('.morph', 'framework')]
+    : ['node_modules'];
+
+  const alreadyPresent = {};
+  for (const rel of dirs) {
+    alreadyPresent[rel] = existsSync(join(target, rel));
+  }
+
+  setupInfraLinks(target, root, { dirs });
+
+  const linked = [];
+  const skipped = [];
+  for (const rel of dirs) {
+    if (alreadyPresent[rel]) {
+      skipped.push(rel); // already there before this call
+    } else if (existsSync(join(target, rel))) {
+      linked.push(rel); // newly created by setupInfraLinks
+    } else {
+      skipped.push(rel); // nothing to link (source missing in root, or link failed)
+    }
+  }
+
+  console.log(JSON.stringify({ linked, skipped, root, target }));
+  process.exit(0);
+}
+
+// ── 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 }>}
+ */
+function parseWorktreeList(cwd) {
+  let output;
+  try {
+    output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
+  } catch {
+    return [];
+  }
+
+  const entries = [];
+  let current = null;
+  for (const line of output.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (current) entries.push(current);
+      current = { path: line.slice('worktree '.length).trim().replace(/\\/g, '/'), branch: null, head: null };
+    } else if (line.startsWith('branch ') && current) {
+      current.branch = line.slice('branch '.length).trim();
+    } else if (line.startsWith('HEAD ') && current) {
+      current.head = line.slice('HEAD '.length).trim();
+    }
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+
+/**
+ * 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}
+ */
+function findWorktreeForFeature(feature, root) {
+  const expectedBranch = buildBranchName(feature);
+  const refName = `refs/heads/${expectedBranch}`;
+  const entries = parseWorktreeList(root);
+
+  let match = entries.find((e) => e.branch === refName);
+  if (!match) {
+    const guess = buildWorktreePath(feature, root).replace(/\\/g, '/');
+    match = entries.find((e) => e.path === guess);
+  }
+  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 };
+}
+
+/** The infra paths `setupInfraLinks` junctions into a worktree. */
+const INFRA_LINK_RELS = ['node_modules', '.claude', join('.morph', 'framework')];
+
+/**
+ * Drop the infra junctions a worktree carries (`node_modules`, `.claude`,
+ * `.morph/framework`) WITHOUT following them.
+ *
+ * CRITICAL — this is what keeps `worktree finish` 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.
+ *
+ * @param {string} worktreePath
+ * @returns {string[]} relative paths actually unlinked
+ */
+export function unlinkWorktreeInfraLinks(worktreePath) {
+  const removed = [];
+  for (const rel of INFRA_LINK_RELS) {
+    const p = join(worktreePath, rel);
+    let st;
+    try {
+      st = lstatSync(p);
+    } catch {
+      continue; // absent — nothing to drop
+    }
+    if (!st.isSymbolicLink() && !st.isDirectory()) continue;
+    try {
+      // symlink → unlink; Windows junction → rmdir. Both act on the link itself.
+      try {
+        unlinkSync(p);
+      } catch {
+        rmdirSync(p);
+      }
+      removed.push(rel);
+    } catch { /* a real, non-empty directory — leave it alone */ }
+  }
+  return removed;
+}
+
+/**
+ * Every reparse point anywhere under `worktreePath`, as relative paths.
+ *
+ * CRITICAL — this is the gate that keeps `worktree finish` from destroying the
+ * project, and it must be exhaustive. BOTH `git worktree remove` and its
+ * `--force` fallback FOLLOW reparse points out of the worktree and delete the
+ * PRIMARY ROOT's real files. The plain removal is not the safe one: it refuses
+ * only when it sees modified/untracked *tracked-scope* content, so a GITIGNORED
+ * junction (`node_modules`, `.claude`) leaves `git status` empty, the removal
+ * proceeds, exits 0 — and the target is gone.
+ *
+ * So the check cannot live in the `catch` of the plain removal (unreachable on
+ * exactly the destructive path), and it cannot be a fixed list of the links
+ * `setup` creates: a nested link inside a real `node_modules` (npm link, npm
+ * workspaces) is invisible to any top-level inventory. We scan the whole tree
+ * and NEVER recurse INTO a reparse point — descending one would walk the target
+ * we are trying to protect (and could not terminate on a cycle).
+ *
+ * An empty result is NOT the same as a safe one: a directory we could not read
+ * or an entry we could not lstat might BE (or contain) a reparse point. Those
+ * answer `unprovable: true`, and the caller must treat that exactly like a found
+ * link — decline. "I saw nothing" and "I proved there is nothing" are different
+ * claims, and only the second one may authorize a removal.
+ *
+ * @param {string} dir
+ * @param {string} [base] - root of the scan, for relative reporting
+ * @param {{points: string[], unprovable: string[]}} [acc]
+ * @returns {{points: string[], unprovable: string[]}} both empty = provably clean
+ */
+function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // Unreadable (ACL, lock, EMFILE): we cannot prove what is in here.
+    acc.unprovable.push((relative(base, dir) || '.').replace(/\\/g, '/'));
+    return acc;
+  }
+  for (const entry of entries) {
+    const p = join(dir, entry.name);
+    let st;
+    try {
+      st = lstatSync(p);
+    } catch {
+      acc.unprovable.push(relative(base, p).replace(/\\/g, '/'));
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      // Forward slashes: every other path this command reports is normalized,
+      // and these end up in JSON the caller may compare or display.
+      acc.points.push(relative(base, p).replace(/\\/g, '/'));
+      continue; // do NOT descend — that is the target, not the worktree
+    }
+    if (st.isDirectory() && entry.name !== '.git') findReparsePoints(p, base, acc);
+  }
+  return acc;
+}
+
+/**
+ * Gitignored paths a morph worktree owns and that are safe to remove — but ONLY
+ * once backed up (see backupWorktreeIgnored). `.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.
+ */
+const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
+
+/**
+ * Split the worktree's GITIGNORED leftovers into what this command may remove
+ * (morph's own, after a backup) and what it must refuse to destroy.
+ *
+ * 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.
+ *
+ * Fail-CLOSED: if the status call fails we cannot enumerate what is at stake, so
+ * everything is reported as blocking.
+ *
+ * @param {string} worktreePath
+ * @param {{ discardIgnored?: boolean }} options
+ * @returns {{ shieldable: string[], blocking: string[] }}
+ */
+function classifyIgnoredLeftovers(worktreePath, 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.
+    out = execFileSync('git', ['status', '--porcelain', '--ignored', '-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>'] };
+  }
+
+  const shieldable = [];
+  const blocking = [];
+  for (const record of out.split('\0')) {
+    if (!record || record.length < 4) continue;
+    if (record.slice(0, 2) !== '!!') continue; // only ignored entries; the rest is the clean-check's job
+    const p = record.slice(3).replace(/\\/g, '/');
+    if (IGNORED_SHIELDABLE_PREFIXES.some((prefix) => p.startsWith(prefix))) shieldable.push(p);
+    else blocking.push(p);
+  }
+  // Explicit consent clears the block — but the list is NOT thrown away. These
+  // are the files that exist nowhere else, and they are the ones about to die;
+  // reporting them is the least this can do. (Backing them up instead is not an
+  // option: this bucket is where `node_modules`/`dist`/`.next` land, so a copy
+  // is unbounded. The user declared them disposable — they still get told.)
+  if (options.discardIgnored) return { shieldable, blocking: [], discarded: blocking };
+  return { shieldable, blocking, discarded: [] };
+}
+
+/**
+ * Back up the worktree's morph-owned gitignored leftovers before the removal
+ * deletes them. Same destination and rationale as backupFeatureScope.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @param {string} feature
+ * @param {string[]} rels - worktree-relative paths
+ * @param {string} stamp
+ * @returns {string|null} backup path, or null if ANY copy failed (caller must
+ *   then decline the removal — a partial backup authorizes nothing)
+ */
+function backupWorktreeIgnored(worktreePath, root, feature, rels, stamp) {
+  const dest = join(root, '.git', 'morph-spec', 'finish-backup', `${feature}-${stamp}-worktree-ignored`);
+  try {
+    for (const rel of rels) {
+      const src = join(worktreePath, rel);
+      if (!existsSync(src)) continue; // a directory entry already covered by its children
+      const target = join(dest, rel);
+      mkdirSync(dirname(target), { recursive: true });
+      cpSync(src, target, { recursive: true });
+    }
+    return existsSync(dest) ? dest : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Copy the feature's root-side scope to a backup OUTSIDE the working tree, so
+ * the shed below can never be the reason something is lost.
+ *
+ * Lives under `.git/` on purpose: it is not a working-tree path, so it can never
+ * dirty `git status` (which the very next validation reads) and is never merged,
+ * committed, or cleaned by `git clean`.
+ *
+ * @param {string} root
+ * @param {string} feature
+ * @param {string} stamp - caller-supplied timestamp (keeps this pure/testable)
+ * @returns {string|null} absolute backup path, or null if the copy failed
+ */
+function backupFeatureScope(root, feature, stamp) {
+  const src = join(root, '.morph', 'features', feature);
+  if (!existsSync(src)) return null;
+  const dest = join(root, '.git', 'morph-spec', 'finish-backup', `${feature}-${stamp}`);
+  try {
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: true });
+    return dest;
+  } catch {
+    return null; // caller MUST treat this as "do not shed"
+  }
+}
+
+// ── finish ───────────────────────────────────────────────────────────────
+
+/**
+ * Command handler for `morph-spec worktree finish <feature> [--keep] [--force]`.
+ *
+ * Deterministic merge-back: merges the feature's `morph/{feature}` branch into
+ * the primary root and (unless `--keep`) removes the worktree + branch. This
+ * is the closing half of the worktree lifecycle that `setup` opens.
+ *
+ * All three preconditions below are fail-CLOSED — no merge is attempted and
+ * nothing is removed. They are NOT no-ops, though: the shed runs before the
+ * last one, so a refusal there (or on a merge conflict) has already moved this
+ * feature's root-side scope to the backup. Recoverable, and every such refusal
+ * reports the path — but "nothing was touched" would be false. Preconditions:
+ *   1. Gate 3 (review) approved on the worktree's own feature.json, unless `--force`.
+ *   2. The worktree itself has no uncommitted changes (work must be committed
+ *      to travel with the merge).
+ *   3. The primary root has no uncommitted changes (so a merge commit lands cleanly).
+ *
+ * NOTE: precondition 3 runs AFTER the shed of this feature's root-side scope, so
+ * a refusal there is not a no-op — but it is RECOVERABLE: the shed copies that
+ * scope to `.git/morph-spec/finish-backup/` first and every refusal after it
+ * reports the path.
+ *
+ * That guarantee covers what the SHED discards (the root-side scope) and, at
+ * cleanup, morph's own gitignored files in the worktree. It does NOT cover
+ * `--discard-ignored`, which destroys the worktree's non-morph gitignored files
+ * outright — that is the flag's stated purpose, the JSON names each file it
+ * destroyed, and no default path reaches it.
+ *
+ * A merge conflict aborts the merge (`git merge --abort`) and refuses —
+ * nothing is left half-merged.
+ *
+ * Success is reported as two INDEPENDENT signals: `finished` is the merge (the
+ * actual value), `worktreeRemoved` is the best-effort cleanup. Cleanup declines
+ * itself whenever it cannot prove it is safe, so `finished: true` +
+ * `worktreeRemoved: false` is a normal, honest outcome — not a failure.
+ *
+ * @param {string} feature
+ * @param {{ keep?: boolean, force?: boolean, discardIgnored?: boolean, cwd?: string }} [options]
+ *   `force` waives the Gate 3 precondition ONLY — never the branch check.
+ *   `discardIgnored` is consent to destroy the worktree's non-morph gitignored
+ *   files (see the NOTE above); it does not waive the reparse-point gate.
+ */
+export async function worktreeFinishCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const root = resolvePrimaryRoot(cwd);
+
+  // Refuse anything that is not a plain kebab feature name. `& | ; > ^` are all
+  // legal in a git refname but are cmd.exe metacharacters, and every git call
+  // below interpolates the name (or the branch built from it). Validating here —
+  // not just around the shed — is what keeps a crafted name from steering the
+  // `merge`/`branch -d` at the bottom onto a DIFFERENT branch than the one this
+  // command validated and reported.
+  if (!isValidFeatureName(feature)) {
+    console.log(JSON.stringify({ finished: false, error: 'invalid-feature-name', feature }));
+    process.exit(1);
+  }
+
+  const found = findWorktreeForFeature(feature, root);
+  if (!found) {
+    console.log(JSON.stringify({ finished: false, error: 'no-worktree', feature }));
+    process.exit(1);
+  }
+  const { path: worktreePath, branch, expectedBranch } = found;
+
+  // Validation 0: the worktree must actually be ON the branch we are about to
+  // merge. The path fallback in findWorktreeForFeature matches by location, so
+  // a worktree the user re-pointed at another branch (or detached) still
+  // matches — and merging the computed `morph/{feature}` then would land a
+  // branch we never validated while destroying a worktree holding unrelated
+  // work. `--force` does NOT waive this: it waives the review gate, not the
+  // question of WHICH branch this command is acting on.
+  if (branch !== expectedBranch) {
+    console.log(JSON.stringify({
+      finished: false,
+      error: 'worktree-branch-mismatch',
+      feature,
+      expectedBranch,
+      actualBranch: branch, // null = detached HEAD
+      path: worktreePath,
+      hint: `o worktree em ${worktreePath} está em ${branch || 'HEAD destacado'}, não em ${expectedBranch} — faça checkout da branch da feature ou finalize essa branch manualmente`,
+    }));
+    process.exit(1);
+  }
+
+  // Validation 1: Gate 3 (review) approved, unless --force.
+  if (!options.force) {
+    let reviewApproved = false;
+    try {
+      const fjPath = join(worktreePath, '.morph', 'features', feature, 'feature.json');
+      if (existsSync(fjPath)) {
+        const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+        const gates = fj?.approvalGates || fj?.approvals || {};
+        reviewApproved = gates?.review?.approved === true;
+      }
+    } catch { /* reviewApproved stays false — refuse below */ }
+
+    if (!reviewApproved) {
+      console.log(JSON.stringify({ finished: false, error: 'review-not-approved', feature }));
+      process.exit(1);
+    }
+  }
+
+  // Validation 2: worktree must be clean (work must be committed to travel with the merge).
+  let worktreeStatus;
+  try {
+    worktreeStatus = execSync('git status --porcelain', { cwd: worktreePath, stdio: 'pipe' }).toString();
+  } catch (err) {
+    console.log(JSON.stringify({ finished: false, error: 'worktree-status-failed', detail: (err.message || '').slice(0, 200), feature }));
+    process.exit(1);
+  }
+  if (worktreeStatus.trim() !== '') {
+    console.log(JSON.stringify({
+      finished: false,
+      error: 'worktree-dirty',
+      hint: 'commit seu trabalho na branch antes do finish',
+      feature,
+    }));
+    process.exit(1);
+  }
+
+  // Shed the feature's OWN transient root-side bookkeeping BEFORE the clean
+  // check. `.morph/features/{feature}/` in the root holds artifacts the merge is
+  // about to replace wholesale: the factory flow (`create --worktree`) scaffolds
+  // it untracked, and `setup` stamps the worktree registration onto a committed
+  // feature.json (a ` M`). Shedding them lets the merge own this feature's state
+  // while the whole-root clean-check keeps guarding UNRELATED work.
+  //
+  // SAFETY — back up FIRST, then shed. An earlier design classified each dirty
+  // path to decide what was safe to discard; every version of that classifier
+  // was wrong in some real flow (an untracked file the branch has at a different
+  // CONTENT; a `??` feature.json that a `M`-gated check never inspected), and a
+  // wrong classifier here destroys unversioned work while reporting success.
+  // Copying the whole scope out of the working tree first makes the shed safe
+  // WITHOUT having to be right about what is in it: if the classification the
+  // merge implies turns out wrong, the bytes are still on disk.
+  const featPathspec = `.morph/features/${feature}`;
+  let shedBackup = null;
+
+  let dirtyInScope = '';
+  try {
+    dirtyInScope = execFileSync('git', ['status', '--porcelain', '-uall', '--', featPathspec], { cwd: root, stdio: 'pipe' }).toString();
+  } catch { /* nothing in scope */ }
+
+  if (dirtyInScope.trim() !== '') {
+    shedBackup = backupFeatureScope(root, feature, new Date().toISOString().replace(/[:.]/g, '-'));
+    // No backup, no shed. Falling through leaves the root dirty, so the
+    // clean-check below refuses — the exact fail-closed behaviour that existed
+    // before any shed did.
+    if (shedBackup) {
+      // Discard the registration stamped onto a committed feature.json by `setup`.
+      try { execFileSync('git', ['checkout', '--', featPathspec], { cwd: root, stdio: 'pipe' }); } catch { /* nothing tracked to restore */ }
+      // Remove the untracked scaffold left in the root by `create --worktree`.
+      // Scoped pathspec + no `-x` keep this away from gitignored `.morph/logs/`.
+      try { execFileSync('git', ['clean', '-fdq', '--', featPathspec], { cwd: root, stdio: 'pipe' }); } catch { /* nothing untracked to clean */ }
+    }
+  }
+
+  // Every refusal from here on must tell the user where the bytes went.
+  // Distinct key from `hint`: callers below carry their own hint and this must
+  // never overwrite it.
+  const backupNote = shedBackup
+    ? {
+      shedBackup,
+      shedBackupNote: `o conteúdo root-side de ${featPathspec} foi copiado para ${shedBackup} antes de ser descartado — nada foi perdido`,
+    }
+    : {};
+
+  // Validation 3: primary root must be clean.
+  let rootStatus;
+  try {
+    rootStatus = execFileSync('git', ['status', '--porcelain'], { cwd: root, stdio: 'pipe' }).toString();
+  } catch (err) {
+    console.log(JSON.stringify({ finished: false, error: 'primary-root-status-failed', detail: (err.message || '').slice(0, 200), feature, ...backupNote }));
+    process.exit(1);
+  }
+  if (rootStatus.trim() !== '') {
+    console.log(JSON.stringify({
+      finished: false,
+      error: 'primary-root-dirty',
+      feature,
+      ...backupNote,
+    }));
+    process.exit(1);
+  }
+
+  // Merge — fail-closed on conflict. Args go through execFile: the branch name
+  // reaches git as one argv entry, never as a cmd.exe string to re-split.
+  try {
+    execFileSync('git', ['merge', '--no-ff', branch, '-m', `morph-spec worktree finish: merge ${branch}`], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    try {
+      execFileSync('git', ['merge', '--abort'], { cwd: root, stdio: 'pipe' });
+    } catch { /* best-effort abort — merge may not have entered a mergeable state */ }
+    const output = (((err.stdout && err.stdout.toString()) || '') + ((err.stderr && err.stderr.toString()) || '')).slice(0, 2000) || (err.message || '').slice(0, 500);
+    console.log(JSON.stringify({
+      finished: false,
+      error: 'merge-conflict',
+      output,
+      hint: 'resolva manualmente ou re-execute a feature sequencialmente',
+      feature,
+      ...backupNote,
+    }));
+    process.exit(1);
+  }
+
+  if (options.keep) {
+    console.log(JSON.stringify({ finished: true, kept: true, feature, merged: branch, path: worktreePath, branch, ...backupNote }));
+    process.exit(0);
+  }
+
+  // ── Cleanup: PROVE it is safe, or decline it ──────────────────────────────
+  //
+  // The merge (the actual value of this command) has landed. Removing the
+  // worktree is convenience, and it is the single most dangerous thing here.
+  // Two independent ways it destroys data, both of which end in a removal that
+  // exits 0 while doing it:
+  //
+  //  1. `git worktree remove` — plain AND `--force` — follows reparse points
+  //     out of the worktree and deletes what they point at in the primary root.
+  //  2. It deletes GITIGNORED files outright. Git considers them disposable;
+  //     a user's `.env` is not. They are invisible to the clean-check above
+  //     (`git status --porcelain` omits them by design), so that gate cannot
+  //     speak for them at all.
+  //
+  // Both gates below therefore PROVE-or-DECLINE. Declining costs a stale
+  // directory the user can delete in one command; being wrong costs data that
+  // exists nowhere else.
+  unlinkWorktreeInfraLinks(worktreePath);
+
+  const scan = findReparsePoints(worktreePath);
+  const ignored = classifyIgnoredLeftovers(worktreePath, options);
+  const blockers = [...scan.points, ...scan.unprovable];
+
+  // Back up ONLY once the removal is otherwise cleared. Two reasons, and the
+  // ordering buys both for free:
+  //   - Nothing is about to be destroyed on a declined path, so copying there
+  //     is pure waste — and worse, it would duplicate the user's content into
+  //     `.git/` for a removal that never happens.
+  //   - `blockers.length === 0` is a PROOF that no reparse point exists anywhere
+  //     under the worktree. cpSync follows junctions on Windows, so running it
+  //     before that proof could copy an out-of-repo tree of unbounded size in
+  //     under an allowlisted `.morph/` path.
+  let ignoredBackup = null;
+  const clearedToRemove = blockers.length === 0 && ignored.blocking.length === 0;
+  if (clearedToRemove && ignored.shieldable.length) {
+    ignoredBackup = backupWorktreeIgnored(worktreePath, root, feature, ignored.shieldable, new Date().toISOString().replace(/[:.]/g, '-'));
+  }
+
+  const canRemove = clearedToRemove
+    && (!ignored.shieldable.length || ignoredBackup !== null);
+
+  let worktreeRemoved = false;
+  if (canRemove) {
+    try {
+      execFileSync('git', ['worktree', 'remove', worktreePath], { cwd: root, stdio: 'pipe' });
+      worktreeRemoved = true;
+    } catch {
+      // Nothing is left to traverse (proven above), so --force can only act
+      // inside the worktree.
+      try {
+        execFileSync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: root, stdio: 'pipe' });
+        worktreeRemoved = true;
+      } catch { /* fail-open — cleanup is best-effort once the merge already landed */ }
+    }
+  }
+
+  // The branch is still checked out by a worktree we did not remove — deleting
+  // it would fail anyway, and `--worktree prune` has nothing to reclaim.
+  if (worktreeRemoved) {
+    try {
+      execFileSync('git', ['branch', '-d', branch], { cwd: root, stdio: 'pipe' });
+    } catch { /* fail-open */ }
+
+    try {
+      execFileSync('git', ['worktree', 'prune'], { cwd: root, stdio: 'pipe' });
+    } catch { /* fail-open */ }
+  }
+
+  // The feature is now merged into the primary root — clear the `worktree`
+  // bookkeeping field from its (root-side) feature.json. Fail-open: this is
+  // metadata cleanup, never a reason to report the finish itself as failed.
+  //
+  // Written DIRECTLY, not via loadState/saveState: saveState re-persists EVERY
+  // feature's feature.json, so clearing one field on THIS feature rewrites the
+  // siblings too. Any sibling whose committed file differs only in formatting (a
+  // trailing newline — what an editor or prettier leaves) gets rewritten into a
+  // ` M`, dirtying the root outside this command's own pathspec, where the
+  // post-merge commit below cannot see it. That stray modification then blocks
+  // the NEXT feature's finish — the exact failure this command exists to avoid,
+  // and it bites hardest in the parallel multi-worktree flow it was built for.
+  // The thin root index carries only {status, updatedAt}, never `worktree`, so
+  // there is nothing else to persist here.
+  // atomicWriteJson (not a plain writeFileSync): this file is the feature's
+  // AUTHORITATIVE, committed state. A torn write from a crash — or an EPERM
+  // from a Windows AV/indexer holding the handle — would corrupt or fail on the
+  // one copy that matters. tmp+rename with the EPERM retry is what the rest of
+  // the state layer uses; bypassing the sweep must not also bypass that.
+  try {
+    const rootFjPath = join(root, '.morph', 'features', feature, 'feature.json');
+    if (existsSync(rootFjPath)) {
+      const fj = JSON.parse(readFileSync(rootFjPath, 'utf8'));
+      if (fj.worktree) {
+        delete fj.worktree;
+        const { atomicWriteJson } = await import('../../core/state/state-manager.js');
+        atomicWriteJson(rootFjPath, fj);
+      }
+    }
+  } catch { /* fail-open */ }
+
+  // Clearing that field can itself dirty the root: when `setup`'s registration
+  // was COMMITTED, it lives in HEAD, so the shed's `git checkout` cannot undo it
+  // and it survives the merge — then the rewrite above leaves a ` M`. Left
+  // behind, that stray modification blocks the NEXT feature's finish (the shed
+  // is scoped to its own feature), which is the very bug this command was fixed
+  // to stop hitting. Committing it is in contract: `finish` already writes a
+  // merge commit. Scoped to this feature's path — never sweeps up other work.
+  try {
+    const dirtyAfter = execFileSync('git', ['status', '--porcelain', '--', featPathspec], { cwd: root, stdio: 'pipe' }).toString();
+    if (dirtyAfter.trim() !== '') {
+      execFileSync('git', ['add', '--', featPathspec], { cwd: root, stdio: 'pipe' });
+      execFileSync('git', ['commit', '-m', `morph-spec worktree finish: clear ${feature} worktree registration`, '--', featPathspec], { cwd: root, stdio: 'pipe' });
+    }
+  } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail a landed merge */ }
+
+  const declineReason = ignored.blocking.length
+    ? `merge OK. O worktree NÃO foi removido: ele contém arquivo(s) gitignored que existem só ali e o \`git worktree remove\` apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`git worktree remove --force "${worktreePath}"\` + \`git branch -d ${branch}\`, ou re-execute o finish com \`--discard-ignored\` para descartá-los deliberadamente`
+    : blockers.length
+      ? `merge OK. O worktree NÃO foi removido: ele ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que o \`git worktree remove\` seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`git worktree remove "${worktreePath}"\` + \`git branch -d ${branch}\``
+      : ignored.shieldable.length && ignoredBackup === null
+        ? `merge OK. O worktree NÃO foi removido: o backup de ${featPathspec} (gitignored do worktree) falhou, e sem ele a remoção seria destrutiva. Rode \`git worktree remove --force "${worktreePath}"\` manualmente se não precisar desse conteúdo`
+        : `merge OK, mas o \`git worktree remove\` falhou. Rode \`git worktree remove "${worktreePath}"\` + \`git branch -d ${branch}\` manualmente`;
+
+  console.log(JSON.stringify({
+    finished: true,
+    feature,
+    merged: branch,
+    worktreeRemoved,
+    ...(shedBackup ? { shedBackup } : {}),
+    ...(ignoredBackup ? { worktreeIgnoredBackup: ignoredBackup } : {}),
+    // Only when the removal actually ran did these die — a decline for any other
+    // reason leaves them on disk. Naming them keeps `--discard-ignored` honest:
+    // `worktreeIgnoredBackup` alone would imply everything was preserved.
+    ...(worktreeRemoved && ignored.discarded.length
+      ? {
+        discardedIgnored: ignored.discarded,
+        discardedNote: `--discard-ignored: os caminhos acima eram gitignored, existiam só no worktree e foram DESTRUÍDOS sem backup (não são copiados por poderem ser arbitrariamente grandes)`,
+      }
+      : {}),
+    ...(worktreeRemoved
+      ? {}
+      : {
+        path: worktreePath,
+        branch,
+        ...(blockers.length ? { reparsePoints: blockers } : {}),
+        ...(ignored.blocking.length ? { ignoredFiles: ignored.blocking } : {}),
+        cleanupHint: declineReason,
+        // The infra junctions were dropped before this decline (that step runs
+        // unconditionally, since it is what makes a removal survivable). A kept
+        // worktree therefore has no node_modules/.claude until they are relinked
+        // — say so, instead of leaving the user to discover a broken worktree.
+        relinkHint: `as junctions de infra (node_modules, .claude, .morph/framework) foram soltas antes desta recusa — se for continuar trabalhando nesse worktree, rode \`morph-spec worktree link --all --target "${worktreePath}"\``,
+      }),
+    nextStep: `morph-spec archive ${feature}`,
+  }));
+  process.exit(0);
+}
+
+// ── 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();
+
+  if (!isGitRepo(cwd)) {
+    printWorktreeList([], options);
+    process.exit(0);
+  }
+
+  const root = resolvePrimaryRoot(cwd);
+  const entries = parseWorktreeList(root);
+
+  const worktrees = [];
+  if (entries.length) {
+    const { derivePhaseForFeature, getPendingGates, getFeature } =
+      await import('../../../framework/hooks/shared/state-reader.js');
+
+    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
+      const feature = m[1];
+
+      let phase = 'proposal';
+      let status = 'unknown';
+      let pendingGates = [];
+      try {
+        const featureObj = getFeature(feature, entry.path);
+        status = featureObj?.status || 'unknown';
+        phase = derivePhaseForFeature(feature, entry.path);
+        pendingGates = getPendingGates(feature, entry.path);
+      } catch { /* leave defaults — a corrupt feature.json must never crash list */ }
+
+      worktrees.push({
+        feature,
+        branch: entry.branch.replace(/^refs\/heads\//, ''),
+        phase,
+        status,
+        pendingGates,
+        path: entry.path,
+      });
+    }
+  }
+
+  printWorktreeList(worktrees, 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 }));
+    return;
+  }
+
+  if (worktrees.length === 0) {
+    console.log(chalk.gray('No active feature worktrees.'));
+    return;
+  }
+
+  const col = (s, w) => String(s).padEnd(w);
+  console.log(chalk.white.bold(col('FEATURE', 22) + col('BRANCH', 26) + col('PHASE', 12) + col('STATUS', 14) + col('PENDING GATES', 24) + 'PATH'));
+  for (const w of worktrees) {
+    const gates = w.pendingGates.length ? w.pendingGates.join(',') : '-';
+    console.log(col(w.feature, 22) + col(w.branch, 26) + col(w.phase, 12) + col(w.status, 14) + col(gates, 24) + w.path);
+  }
 }