@polymorphism-tech/morph-spec 8.42.0 → 8.44.0

package/src/commands/project/worktree.js

@@ -58,6 +58,21 @@ import { dropLeftoverIgnore, withoutLeftoverIgnore } from '../../../framework/ho
 // 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';
+import { containerDirs, externalContainer, newWorktreesDir } from '../../../framework/hooks/shared/worktree-root.js';
+
+/** Fail-open: the editor file is a convenience, never a reason a worktree is not created. */
+function rootAndEditorReport(root) {
+  const { warning } = externalContainer(root);
+  const worktreeRoot = warning ? { worktreeRootWarning: warning } : {};
+  try {
+    const report = applyEditorSettings(root);
+    return report.status === 'off' ? worktreeRoot : { ...worktreeRoot, editorSettings: report };
+  } catch {
+    return worktreeRoot;
+  }
+}
 export { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES };
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
@@ -146,7 +161,8 @@ export function worktreeExists(worktreePath, cwd = process.cwd()) {
 export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
   const suffix = options.fresh ? `-${getDateSuffix()}` : '';
   const normalizedCwd = cwd.replace(/\\/g, '/');
-  return `${normalizedCwd}/${WORKTREES_DIR}/${feature}${suffix}`;
+  const container = externalContainer(normalizedCwd).dir ?? `${normalizedCwd}/${WORKTREES_DIR}`;
+  return `${container}/${feature}${suffix}`;
 }
 
 /**
@@ -514,7 +530,7 @@ export async function runWorktreeSetup(feature, options = {}) {
     }
 
     // Create worktree directory parent if needed
-    const parentDir = join(cwd, WORKTREES_DIR);
+    const parentDir = newWorktreesDir(cwd);
     if (!existsSync(parentDir)) {
       mkdirSync(parentDir, { recursive: true });
     }
@@ -524,6 +540,7 @@ export async function runWorktreeSetup(feature, options = {}) {
 
     // 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
@@ -573,9 +590,11 @@ export async function runWorktreeSetup(feature, options = {}) {
       branch,
       branchedFrom,
       feature,
+      ...(included.length ? { worktreeInclude: included } : {}),
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       ...(graph.seeded ? { graph: 'seeded' } : {}),
+      ...rootAndEditorReport(resolvePrimaryRoot(cwd)),
       nextStep: `Abra o Claude Code em ${worktreePath} para trabalhar nesta feature`,
     };
   } catch (err) {
@@ -699,13 +718,14 @@ export async function runWorktreeProvision(name, options = {}) {
       }
     }
 
-    const parentDir = join(root, WORKTREES_DIR);
+    const parentDir = newWorktreesDir(root);
     if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
 
     execFileSync('git', ['worktree', 'add', worktreePath, branch], { cwd: root, stdio: 'pipe' });
 
     setupInfraLinks(worktreePath, root);
     const envFiles = copyRootEnvFiles(worktreePath, root);
+    const included = copyWorktreeIncludes(worktreePath, root);
     // A tree born from `morph/<f>` works FOR that feature: MORPH_FEATURE says
     // so, while the port block stays the task's own (`task/<name>`).
     const forFeature = String(options.base || '').match(/^morph\/(.+)$/)?.[1] ?? null;
@@ -724,9 +744,11 @@ export async function runWorktreeProvision(name, options = {}) {
       name,
       ...(forFeature ? { feature: forFeature } : {}),
       ...(envFiles.length ? { envFiles } : {}),
+      ...(included.length ? { worktreeInclude: included } : {}),
       materialized: materialized.materialized,
       ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
       ...(graph.seeded ? { graph: 'seeded' } : {}),
+      ...rootAndEditorReport(root),
     };
   } catch (err) {
     return { ok: true, exitCode: 0, created: false, error: (err.message || 'unknown').slice(0, 200), name };
@@ -860,19 +882,21 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFea
     } catch { morphFeature = null; }
   }
   try {
-    const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
+    const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent, resolvePortAliases } =
       await import('../../lib/worktree/env-allocator.js');
     const common = execSync('git rev-parse --git-common-dir', { cwd: root, stdio: 'pipe' }).toString().trim();
     if (!common) return null;
     const gitCommonDir = resolve(root, common);
     const block = allocateEnvBlock(envKey, { gitCommonDir, ...resolveFleetConfig(root) });
     let stack = '';
+    let aliases = {};
     try {
       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 */ }
     mkdirSync(join(worktreePath, '.morph'), { recursive: true });
-    writeFileSync(envPath, buildEnvFileContent(envKey, block, stack, { morphFeature }), 'utf8');
+    writeFileSync(envPath, buildEnvFileContent(envKey, block, stack, { morphFeature, aliases }), 'utf8');
     excludeWorktreePaths(root, [join('.morph', 'worktree.env')]);
     return block;
   } catch {
@@ -886,7 +910,7 @@ export async function allocateWorktreeEnv(worktreePath, root, envKey, { morphFea
  * 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 }>}
+ * @returns {Array<{ path: string, branch: string|null, head: string|null, locked: boolean }>}
  */
 export function parseWorktreeList(cwd) {
   let output;
@@ -901,7 +925,9 @@ export function parseWorktreeList(cwd) {
   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 };
+      current = { path: line.slice('worktree '.length).trim().replace(/\\/g, '/'), branch: null, head: null, locked: false };
+    } else if (/^locked(\s|$)/.test(line) && current) {
+      current.locked = true;
     } else if (line.startsWith('branch ') && current) {
       current.branch = line.slice('branch '.length).trim();
     } else if (line.startsWith('HEAD ') && current) {
@@ -937,8 +963,8 @@ export function findWorktreeForFeature(feature, 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);
+    const guesses = containerDirs(root).map((dir) => `${dir}/${feature}`);
+    match = entries.find((e) => guesses.includes(e.path));
   }
   if (!match) return null;
 
@@ -1214,10 +1240,17 @@ export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
 }
 
 /**
- * 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.
+ * 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
@@ -1226,9 +1259,12 @@ export function primaryRootUnexplainedDirt(root, feature, opts = {}) {
  *
  * @param {string} root
  * @param {string} feature
+ * @param {{ stamp?: string }} [opts] - the caller's backup stamp, for the shed
+ * @returns {Promise<{ shedBackup: string|null }>}
  */
-export async function clearRootWorktreeRegistration(root, feature) {
+export async function clearRootWorktreeRegistration(root, feature, { stamp } = {}) {
   const featPathspec = `.morph/features/${feature}`;
+  const gitOpts = { cwd: root, stdio: 'pipe' };
   try {
     const rootFjPath = join(root, '.morph', 'features', feature, 'feature.json');
     if (existsSync(rootFjPath)) {
@@ -1241,16 +1277,19 @@ export async function clearRootWorktreeRegistration(root, feature) {
     }
   } catch { /* fail-open */ }
 
-  // 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' });
+    const tracked = execFileSync('git', ['ls-files', '--', featPathspec], gitOpts).toString().trim() !== '';
+    if (!tracked) {
+      if (!existsSync(join(root, '.morph', 'archive', feature))) return { shedBackup: null };
+      return shedRootFeatureScope(root, feature, { stamp });
+    }
+    let unchanged = true;
+    try { execFileSync('git', ['diff', '--quiet', 'HEAD', '--', featPathspec], gitOpts); } catch { unchanged = false; }
+    if (!unchanged) {
+      execFileSync('git', ['commit', '-m', `morph-spec finish: clear ${feature} worktree registration`, '--', featPathspec], gitOpts);
     }
   } catch { /* fail-open — a dirty root is a nuisance, not a reason to fail */ }
+  return { shedBackup: null };
 }
 
 /**
@@ -1388,14 +1427,20 @@ export function pickRemovalFailure(stderrs) {
  * `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 }>}
+ *   removalFailure: {kind: string, detail: string}|null, rootShedBackup: string|null }>}
  */
-export async function teardownWorktree(worktreePath, { root, feature, branch, options = {}, deleteBranch = true, addressByTarget = false, stamp }) {
+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.
   //
@@ -1423,6 +1468,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
 
   let worktreeRemoved = false;
   let removalFailure = null;
+  let rootShedBackup = null;
   if (canRemove) {
     const attempt = await attemptWorktreeRemoval(worktreePath, root);
     worktreeRemoved = attempt.removed;
@@ -1443,7 +1489,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
       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);
+    ({ shedBackup: rootShedBackup } = await clearRootWorktreeRegistration(root, feature, { stamp }));
   }
 
   // Rollback (A4) — ONLY on a REFUSAL, never on a FAILURE. The two look alike
@@ -1463,7 +1509,8 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   // and the caller falls back to telling the user to run `worktree link --all`.
   const refused = !canRemove;
   let relinked = false;
-  if (refused && unlinked.length && existsSync(worktreePath)) {
+  const relinkAfterFailure = relinkOnFailure && !refused && !worktreeRemoved && !removalFailure?.alreadyDeregistered;
+  if ((refused || relinkAfterFailure) && unlinked.length && existsSync(worktreePath)) {
     try {
       setupInfraLinks(worktreePath, root);
       relinked = true;
@@ -1471,7 +1518,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   }
   // 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) ? unlinked : [];
+  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
@@ -1508,8 +1555,14 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
               + (removalFailure.kind === 'in-use' ? ' — EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd nele)' : '')
               + `${removalFailure.detail ? ` (${removalFailure.detail})` : ''}. \`${removeCmd}\` não o alcança mais — o git não o conhece. Feche o que o usa, confira que está vazio e sem junction, e apague só o diretório (sem recursão)`
           : removalFailure?.kind === 'in-use'
-            ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``
-            : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`;
+            ? `worktree NÃO removido: o diretório está EM USO por outro processo (instância do Claude Code, VS Code, dev server ou terminal com cwd em "${worktreePath}"). `
+              + (relinked
+                ? `A infra compartilhada foi RESTAURADA — o worktree segue utilizável. Feche o que está usando o diretório e rode \`${removeCmd}\``
+                : `A infra compartilhada ficou DESMONTADA de propósito — feche o que está usando o diretório e rode \`${removeCmd}\`. Se preferir continuar trabalhando nele, restaure a infra com \`morph-spec worktree link --all\``)
+            : `worktree NÃO removido: a remoção falhou${removalFailure?.detail ? ` (${removalFailure.detail})` : ''}. `
+              + (relinked
+                ? `A infra compartilhada foi RESTAURADA — o worktree segue utilizável. Rode \`${removeCmd}\` para tentar de novo`
+                : `A infra compartilhada ficou DESMONTADA de propósito — rode \`${removeCmd}\` para tentar de novo, ou \`morph-spec worktree link --all\` para voltar a trabalhar nele`);
 
   return {
     worktreeRemoved,
@@ -1531,6 +1584,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     refused,
     infraLeftUnlinked,
     removalFailure,
+    rootShedBackup,
   };
 }
 
@@ -1580,8 +1634,9 @@ export function sessionAnchoredInWorktree(worktreePath, env = process.env) {
 // ── remove ───────────────────────────────────────────────────────────────
 
 /**
- * Command handler for `morph-spec worktree remove <feature>` /
- * `morph-spec worktree remove --target <path>`.
+ * 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
@@ -1600,13 +1655,14 @@ export function sessionAnchoredInWorktree(worktreePath, env = process.env) {
  * closing a feature is still `morph-spec finish`.
  *
  * @param {string|undefined} featureArg
- * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, cwd?: string }} [options]
+ * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, relinkOnFailure?: boolean, cwd?: string }} [options]
+ * @returns {Promise<{ out: object, code: 0|1 }>}
  */
-export async function worktreeRemoveCommand(featureArg, options = {}) {
+export async function runWorktreeRemove(featureArg, options = {}) {
   const cwdArg = options.cwd || process.cwd();
-  const emit = (obj, code) => { console.log(JSON.stringify(obj)); process.exit(code); };
+  const outcome = (out, code) => ({ out, code });
 
-  if (!isGitRepo(cwdArg)) emit({ removed: false, error: 'not-a-git-repo' }, 1);
+  if (!isGitRepo(cwdArg)) return outcome({ removed: false, error: 'not-a-git-repo' }, 1);
   const root = resolvePrimaryRoot(cwdArg);
 
   let worktreePath = null;
@@ -1623,11 +1679,11 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     // is the same path-traversal class already fixed in delete/archive.
     const entry = parseWorktreeList(root).find((e) => e.path === worktreePath);
     if (!entry) {
-      emit({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
+      return outcome({ removed: false, error: 'not-a-registered-worktree', target: worktreePath, root,
         hint: 'o path precisa ser um worktree registrado neste repo — confira `morph-spec worktree list`' }, 1);
     }
     if (worktreePath === root) {
-      emit({ removed: false, error: 'refuses-primary-root', path: worktreePath,
+      return outcome({ removed: false, error: 'refuses-primary-root', path: worktreePath,
         hint: 'a raiz primária nunca é removível por este comando' }, 1);
     }
     branch = entry.branch ? entry.branch.replace(/^refs\/heads\//, '') : null;
@@ -1640,12 +1696,12 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     }
   } else {
     if (!isValidFeatureName(feature)) {
-      emit({ removed: false, error: 'invalid-feature-name', feature: feature ?? null,
+      return outcome({ removed: false, error: 'invalid-feature-name', feature: feature ?? null,
         hint: 'informe <feature> (kebab-case) ou use --target <path>' }, 1);
     }
     const found = findWorktreeForFeature(feature, root);
     if (!found || found.path.replace(/\\/g, '/') === root) {
-      emit({ removed: false, error: 'no-worktree-for-feature', feature, root,
+      return outcome({ removed: false, error: 'no-worktree-for-feature', feature, root,
         hint: `nenhum worktree separado para "${feature}" — confira \`morph-spec worktree list\`` }, 1);
     }
     worktreePath = found.path;
@@ -1656,7 +1712,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
   // is MORE likely to hit it: the natural moment to run it is right after
   // working inside the worktree.
   if (cwdIsInsideWorktree(cwdArg, worktreePath)) {
-    emit({ removed: false, error: 'cwd-inside-worktree', path: worktreePath, root,
+    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);
   }
 
@@ -1666,7 +1722,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
   // refusal IS the deferral.
   if (sessionAnchoredInWorktree(worktreePath)) {
     const again = featureAddressable && feature ? `morph-spec worktree remove ${feature}` : `morph-spec worktree remove --target "${worktreePath}"`;
-    emit({ removed: false, error: 'session-anchored-in-worktree', path: worktreePath, root,
+    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);
   }
 
@@ -1681,12 +1737,12 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     try {
       status = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: worktreePath, stdio: 'pipe' }).toString();
     } catch {
-      emit({ removed: false, error: 'status-failed', path: worktreePath, root,
+      return outcome({ removed: false, error: 'status-failed', path: worktreePath, root,
         hint: 'não foi possível provar que o worktree está limpo — nada foi removido' }, 1);
     }
     const dirt = withoutLeftoverIgnore(worktreePath, status.split(/\r?\n/).filter((l) => l.trim()));
     if (dirt.length) {
-      emit({ removed: false, error: 'worktree-dirty', path: worktreePath, root, dirt: dirt.slice(0, 20),
+      return outcome({ removed: false, error: 'worktree-dirty', path: worktreePath, root, dirt: dirt.slice(0, 20),
         hint: `o worktree tem trabalho não commitado — commit ou descarte antes, ou rode \`morph-spec worktree remove --target "${worktreePath}"\` sem --if-clean para remover com backup` }, 1);
     }
   }
@@ -1725,6 +1781,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     // Removing a worktree is not closing a feature: the branch is the work, and
     // deleting it here 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:
     // a `--target` worktree has no feature name that would resolve.
     addressByTarget: !featureAddressable,
@@ -1749,6 +1806,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
     if (teardown.shieldable.length) out.backedUp = teardown.shieldable;
+    if (teardown.rootShedBackup) out.shedBackup = teardown.rootShedBackup;
   } else {
     out.refused = teardown.refused;
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
@@ -1763,7 +1821,18 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     const retention = enforceBackupRetention(root, { protectStamps: [stamp] });
     if (retention) out.backupRetention = retention;
   }
-  emit(out, teardown.worktreeRemoved ? 0 : 1);
+  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 ─────────────────────────────────────────────────────────────────

package/src/commands/state/approve.js

@@ -8,6 +8,7 @@ import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { evaluatorReportState, COMPOSITE_SCORE_TOKEN } from '../../lib/evaluator-report.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 import { uiuxAutoApprovalBlock } from '../../lib/specs/screen-checklist.js';
+import { treeMovedSince } from '../../lib/git/evidence-staleness.js';
 
 /**
  * The literal token `review-report.md` carries to declare which tree it
@@ -57,7 +58,7 @@ function reviewStaleness(featureName) {
     // of staleness — say "unstamped" rather than block on a guess.
     return { status: 'unstamped', head };
   }
-  if (reviewed === head) return { status: 'ok', reviewed, head };
+  if (!treeMovedSince(cwd, reviewed, head)) return { status: 'ok', reviewed, head };
 
   let ahead = 0;
   try {

package/src/commands/state/finish.js

@@ -65,6 +65,8 @@ export function buildPrTitle(feature, fj) {
   return prefix + (raw.length <= room ? raw : `${raw.slice(0, room - 1)}…`);
 }
 
+const MEMORY_NOTE = 'o fechamento desta feature já está registrado no repositório (commit de archive, `decisions.md`, use cases promovidos, `git log`) — memória de sessão só para o que NENHUM deles guarda: decisão do usuário, pendência a observar em produção, custo medido.';
+
 /**
  * `morph-spec finish <feature> --pr|--merge` — the single, symmetric close of a
  * feature's lifecycle, for BOTH the worktree flow and the common flow.
@@ -132,6 +134,8 @@ export async function finishCommand(feature, options = {}) {
   const emit = (obj) => {
     if (resumed) obj = { ...obj, resumed: true };
     if (obj?.finished === true) {
+      // The one path every finished:true takes; the --pr payload is built by hand, outside mergeOutput.
+      obj = { ...obj, memoryNote: MEMORY_NOTE };
       try {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
         if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });

package/src/commands/state/gate-check.js

@@ -8,6 +8,7 @@ import { collectScreenChecklist } from '../../lib/specs/screen-checklist.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { minimatch } from 'minimatch';
 import { detectDefaultBranch, getHeadSha, getDiffStat, changedPathsAgainst } from '../../lib/git/default-branch.js';
+import { treeMovedSince } from '../../lib/git/evidence-staleness.js';
 import { readMorphConfig } from '../../lib/tasks/test-runner.js';
 import { oversizedTasks } from '../../lib/tasks/tasks-json-parser.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
@@ -283,7 +284,7 @@ function collectSignals(featureName, feature, cwd, gateName) {
   // stamp com sha null (checkout sem git) ou stamp ausente lê como NOT stale.
   signals.verification = verification;
   if (verification?.status) signals.verificationStatus = verification.status;
-  signals.verificationStale = Boolean(verification?.sha && sha && verification.sha !== sha);
+  signals.verificationStale = treeMovedSince(cwd, verification?.sha, sha);
 
   // O nó e2e, separado do rollup de propósito: um `skip` NÃO reprova
   // `verification.status`, então sem estas duas chaves o gate lê 'pass' tanto