@polymorphism-tech/morph-spec 8.3.0 → 8.5.0

package/src/commands/project/worktree.js

@@ -14,24 +14,20 @@
  * 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
  *
+ * 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)
- *
- * 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, execFileSync } from 'child_process';
@@ -238,8 +234,8 @@ const EXCLUDE_MARKER = '# morph-spec: infra links inside worktrees (managed —
  * the infra links from `setupInfraLinks` and the fleet env manifest
  * (`.morph/worktree.env`). Same mechanism, same reasons, for both.
  *
- * CRITICAL — without this, `worktree finish` is unusable on POSIX and
- * destructive at worst, because git never sees a link as a link: it sees what
+ * 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
@@ -631,7 +627,7 @@ export function parseWorktreeList(cwd) {
  * @param {string} root - Primary root path
  * @returns {{ path: string, branch: string, expectedBranch: string }|null}
  */
-function findWorktreeForFeature(feature, root) {
+export function findWorktreeForFeature(feature, root) {
   const expectedBranch = buildBranchName(feature);
   const refName = `refs/heads/${expectedBranch}`;
   const entries = parseWorktreeList(root);
@@ -654,8 +650,8 @@ function findWorktreeForFeature(feature, root) {
  * `.morph/framework`, and the `project.frontendPath` node_modules if
  * configured) WITHOUT following them.
  *
- * CRITICAL — this is what keeps `worktree finish` from destroying the project.
- * `git worktree remove` refuses a worktree still holding these ("contains
+ * 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,
@@ -706,8 +702,8 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
 /**
  * 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
+ * CRITICAL — this is the gate that keeps `morph-spec finish` (worktree teardown)
+ * 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
@@ -795,9 +791,9 @@ const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
  */
 /**
  * Whether a dirty root-side path is EXACTLY a sibling feature's live worktree
- * registration — see the call site (Validation 3 in worktreeFinishCommand)
- * for why this is safe to exempt from the whole-root clean gate rather than a
- * widened hole.
+ * 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
@@ -939,277 +935,152 @@ function backupFeatureScope(root, feature, stamp) {
   }
 }
 
-// ── finish ───────────────────────────────────────────────────────────────
+// ── 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.
 
 /**
- * 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.
+ * 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 backupFeatureScope), 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 {{ 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.
+ * @returns {{ shedBackup: string|null }} backup path if anything was shed
  */
-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.
+export function shedRootFeatureScope(root, feature) {
   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 */ }
-    }
+  if (dirtyInScope.trim() === '') return { shedBackup: null };
+
+  const shedBackup = backupFeatureScope(root, feature, new Date().toISOString().replace(/[:.]/g, '-'));
+  // 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 */ }
   }
+  return { shedBackup };
+}
 
-  // 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 — except a SIBLING feature's own
-  // LIVE worktree registration (see isLiveSiblingWorktreeRegistration). That
-  // artifact is how `runWorktreeSetup`/`create --worktree` are DESIGNED to
-  // leave the root for that sibling's entire life (decidePersistence in
-  // verify.js and the anti-dupe guard above both read the root's copy for
-  // `.worktree.path`), so refusing THIS feature's finish over it would block
-  // every OTHER feature for as long as any sibling stays open in its own
-  // worktree — the exact "orphaned scaffold collides with finish" friction
-  // from real multi-feature use. Anything else is still unexplained dirt and
-  // still blocks, fail-closed, exactly as before.
+/**
+ * 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.
+ *
+ * @param {string} root
+ * @param {string} feature - the feature THIS finish acts on (its own scope is the shed's job)
+ * @returns {{ ok: boolean, dirt: string[] }}
+ */
+export function primaryRootUnexplainedDirt(root, feature) {
   let rootStatusRaw;
   try {
-    // `--untracked-files=all`, not the default `normal`: the default collapses
-    // an entirely-untracked directory into one entry (e.g. `.morph/features/
-    // sibling-feat/`, verified empirically) — which would never match the
-    // exact `.../feature.json` path isLiveSiblingWorktreeRegistration expects,
-    // silently defeating the exemption for the very shape it exists to allow.
+    // `--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.
     rootStatusRaw = execFileSync('git', ['status', '--porcelain', '--untracked-files=all', '-z'], { 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);
+  } catch {
+    return { ok: false, dirt: [] };
   }
-  const unexplainedDirt = rootStatusRaw.split('\0').filter((record) => {
+  const dirt = rootStatusRaw.split('\0').filter((record) => {
     if (!record || record.length < 4) return false;
     const p = record.slice(3).replace(/\\/g, '/');
     return !isLiveSiblingWorktreeRegistration(p, root, feature);
   });
-  if (unexplainedDirt.length) {
-    console.log(JSON.stringify({
-      finished: false,
-      error: 'primary-root-dirty',
-      feature,
-      ...backupNote,
-    }));
-    process.exit(1);
-  }
+  return { ok: true, dirt };
+}
 
-  // 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.
+/**
+ * Clear the root-side `.worktree` registration for a finished feature and commit
+ * that cleanup scoped to its own pathspec. 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.
+ *
+ * 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
+ */
+async function clearRootWorktreeRegistration(root, feature) {
+  const featPathspec = `.morph/features/${feature}`;
   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);
-  }
+    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 */ }
 
-  if (options.keep) {
-    console.log(JSON.stringify({ finished: true, kept: true, feature, merged: branch, path: worktreePath, branch, ...backupNote }));
-    process.exit(0);
-  }
+  // Clearing that field can itself dirty the root (a committed registration
+  // survives the shed's checkout and the merge). Committing is in contract —
+  // finish already writes commits — and scoped to this feature's path only.
+  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 finish: clear ${feature} worktree registration`, '--', featPathspec], { cwd: root, stdio: 'pipe' });
+    }
+  } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail */ }
+}
 
-  // ── 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.
+/**
+ * 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.
+ *
+ * `deleteBranch` decouples `git branch -d` from removal: true for `--merge` (the
+ * branch is integrated), false for `--pr` (the open PR still needs the branch).
+ *
+ * @param {string} worktreePath
+ * @param {{ root: string, feature: string, branch: string, options?: object, deleteBranch?: boolean }} ctx
+ * @returns {Promise<{ worktreeRemoved: boolean, ignoredBackup: string|null, discarded: string[],
+ *   blockers: string[], ignoredBlocking: string[], shieldable: string[], declineReason: string|null }>}
+ */
+export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true }) {
+  // Drop the infra junctions FIRST, without following them — this is what makes
+  // a removal survivable (see unlinkWorktreeInfraLinks). Runs unconditionally.
   unlinkWorktreeInfraLinks(worktreePath, root);
 
   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.
+  // 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.
   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);
+  const canRemove = clearedToRemove && (!ignored.shieldable.length || ignoredBackup !== null);
 
   let worktreeRemoved = false;
   if (canRemove) {
@@ -1222,120 +1093,46 @@ export async function worktreeFinishCommand(feature, options = {}) {
       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 */ }
+      } catch { /* fail-open — cleanup is best-effort once integration 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 */ }
-
-    // Fleet env: the worktree is gone, so no server can be running on its
-    // block — release it for the next feature. ONLY here: a kept/declined
-    // worktree may still be serving on those ports. Fail-open metadata cleanup.
+    // 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.
+    if (deleteBranch) {
+      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 */ }
+    // Fleet env: the worktree is gone, so no server can be running on its block.
     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 */ }
+    await clearRootWorktreeRegistration(root, feature);
   }
 
-  // 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,
+  const declineReason = worktreeRemoved
+    ? null
+    : ignored.blocking.length
+      ? `worktree NÃO removido: 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}"\`${deleteBranch ? ` + \`git branch -d ${branch}\`` : ''}, ou re-execute o finish com \`--discard-ignored\` para descartá-los deliberadamente`
+      : blockers.length
+        ? `worktree NÃO removido: 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}"\`${deleteBranch ? ` + \`git branch -d ${branch}\`` : ''}`
+        : ignored.shieldable.length && ignoredBackup === null
+          ? `worktree NÃO removido: o backup do 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`
+          : `o \`git worktree remove\` falhou. Rode \`git worktree remove "${worktreePath}"\` manualmente`;
+
+  return {
     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: options.discardIgnored
-          ? `--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)`
-          : `artefatos de build reconhecidos (bin/, obj/, node_modules/, *.tsbuildinfo) — descartados por padrão, sem backup (regeneráveis a partir do source)`,
-      }
-      : {}),
-    ...(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);
+    ignoredBackup,
+    discarded: ignored.discarded,
+    blockers,
+    ignoredBlocking: ignored.blocking,
+    shieldable: ignored.shieldable,
+    declineReason,
+  };
 }
 
 // ── list ─────────────────────────────────────────────────────────────────