@polymorphism-tech/morph-spec 8.42.0 → 8.43.0

package/src/commands/project/doctor.js

@@ -725,7 +725,24 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
       }
     }
 
+    const { reapAgentWorktrees } = await import('../../lib/worktree/agent-reaper.js');
+    const reap = await reapAgentWorktrees(targetPath);
+    if (reap.ok) {
+      const gone = reap.reaped.map((r) => r.path ?? r.branch);
+      prune.agentReap = { reaped: gone, branchesDeleted: reap.branchesDeleted, preserved: reap.preserved, ...(reap.busy ? { busy: true } : {}) };
+      if (!options.json && gone.length) logger.success(`sobras de sub-agent removidas: ${gone.join(', ')}`);
+      if (!options.json && reap.busy) logger.warn('reaper de sub-agent já em execução em outro processo; nada foi feito nesta rodada');
+    }
+
     const { resolvePrimaryRoot } = await import('./worktree.js');
+    const { applyEditorSettings } = await import('../../lib/worktree/vscode-settings.js');
+    const editor = applyEditorSettings(resolvePrimaryRoot(targetPath));
+    if (editor.status !== 'off') {
+      prune.editorSettings = editor;
+      if (!options.json && editor.status === 'write') logger.success(`.vscode/settings.json: ${editor.added.length} exclusão(ões) de worktree adicionada(s)`);
+      if (!options.json && editor.status === 'suggest') logger.warn(`.vscode/settings.json não foi alterado (${editor.reason}); cole isto nele:\n${editor.snippet}`);
+    }
+
     const { applyBackupRetention, summarizeRetention } = await import('../../lib/worktree/finish-backup.js');
     // The explicit prune is the one that reaches the backups written before the
     // retention existed (no manifest): the automatic one never touches them.
@@ -788,6 +805,9 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
   if (problems.some(prunable) && !options.prune) {
     logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos e os diretórios vazios.');
   }
+  if (issues.some((i) => i.type === 'agent-worktree-leftover' && i.reapable) && !options.prune) {
+    logger.dim('\n  Rode `morph-spec worktree reap` (ou `doctor --worktrees --prune`) para remover as sobras de sub-agent que já pararam.');
+  }
   if (!problems.length) {
     logger.success('Nenhuma inconsistência — os itens acima são informativos.');
     return true;
@@ -932,25 +952,38 @@ export async function doctorAiCommand(targetPath, options = {}) {
 }
 
 export async function doctorCommand(options = {}) {
-  // `--json` and `--prune` only mean something under `--worktrees`. Falling
+  // `--json` and `--prune` only mean something under `--worktrees` or `--procs`. Falling
   // through to the human health check would hand a script a banner and a table
   // where it asked for JSON — a caller has no way to notice a flag that was
   // dropped in silence, so refuse instead of pretending.
   const scoped = ['json', 'prune'].filter((f) => options[f]);
-  if (scoped.length && !options.worktrees) {
+  if (scoped.length && !options.worktrees && !options.procs) {
     const flags = scoped.map((f) => `--${f}`).join(' e ');
-    logger.error(`${flags} só se aplica${scoped.length > 1 ? 'm' : ''} a \`morph-spec doctor --worktrees\`.`);
+    logger.error(`${flags} só se aplica${scoped.length > 1 ? 'm' : ''} a \`morph-spec doctor --worktrees\` ou \`morph-spec doctor --procs\`.`);
     logger.dim(`  Rode: morph-spec doctor --worktrees ${scoped.map((f) => `--${f}`).join(' ')}`);
     process.exitCode = 1;
     return false;
   }
 
+  // `--prune` é uma flag só e poda coisas diferentes em cada modo; juntar os dois
+  // modos faria as duas podas destrutivas rodarem sob um único pedido.
+  if (options.procs) {
+    const conflicts = ['full', 'mcp', 'worktrees', 'reset'].filter((f) => options[f]);
+    if (conflicts.length) {
+      const flags = conflicts.map((f) => `--${f}`).join(' e ');
+      logger.error(`--procs não se combina com ${flags} — cada superfície tem o seu relatório, o seu código de saída e a sua poda.`);
+      logger.dim('  Rode: morph-spec doctor --procs');
+      process.exitCode = 1;
+      return false;
+    }
+  }
+
   // `--ai` é superfície própria (D1). Combiná-la com outra superfície pediria
   // dois relatórios com dois códigos de saída no mesmo processo — o segundo
   // apagaria o primeiro em silêncio. Mesmo molde da guarda acima: recusa em
   // vez de fingir.
   if (options.ai) {
-    const conflicts = ['full', 'mcp', 'worktrees'].filter((f) => options[f]);
+    const conflicts = ['full', 'mcp', 'worktrees', 'procs'].filter((f) => options[f]);
     if (conflicts.length) {
       const flags = conflicts.map((f) => `--${f}`).join(' e ');
       logger.error(`--ai não se combina com ${flags} — cada superfície tem o seu relatório e o seu código de saída.`);
@@ -1011,6 +1044,11 @@ export async function doctorCommand(options = {}) {
     return clean;
   }
 
+  if (options.procs) {
+    const { doctorProcsCommand } = await import('./doctor-procs.js');
+    return doctorProcsCommand(process.cwd(), options);
+  }
+
   const targetPath = process.cwd();
 
   logger.header('MORPH-SPEC Health Check');

package/src/commands/project/heavy.js

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
+import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
+import { describeHolder, heavyDir, heavyStatus } from '../../../framework/hooks/shared/heavy-slots.js';
+
+const EXIT_BUSY = 3;
+const NEEDS_CMD_SHIM = /^(npm|npx|pnpm|yarn)$/;
+
+export function heavyStatusCommand(options = {}) {
+  const config = readHeavyConfig(process.cwd());
+  const status = heavyStatus({ dir: heavyDir(), maxHoldMs: config.maxHoldMinutes * 60_000 });
+  const report = {
+    enabled: config.enabled,
+    slots: config.slots,
+    minFreeMemGb: config.minFreeMemGb,
+    dir: status.dir,
+    freeGb: Number(status.freeGb.toFixed(2)),
+    holders: status.holders.map(({ pid, label, feature, node, cwd, since, leaseId }) => ({ pid, label, feature, node, cwd, since, ...(leaseId ? { leaseId } : {}) })),
+    exclusive: status.exclusive ? { pid: status.exclusive.pid, label: status.exclusive.label, since: status.exclusive.since } : null,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  logger.header('Slots de nós pesados (build, testes, e2e)');
+  if (!config.enabled) console.log(chalk.yellow('  ⚠ semáforo desligado (heavy.enabled: false ou MORPH_HEAVY=off)'));
+  console.log(chalk.gray(`  diretório: ${report.dir}`));
+  const memMark = report.freeGb < config.minFreeMemGb ? chalk.yellow('⚠') : chalk.green('✓');
+  console.log(`  ${memMark} RAM livre: ${report.freeGb.toFixed(1)} GB (mínimo ${config.minFreeMemGb} GB)`);
+  console.log(`  slots em uso: ${status.holders.length}/${config.slots}`);
+  for (const h of status.holders) console.log(chalk.gray(`    • ${describeHolder(h)}${h.cwd ? ` — ${h.cwd}` : ''}`));
+  if (status.exclusive) console.log(chalk.yellow(`  ⚠ limpeza do servidor de build em curso (${describeHolder(status.exclusive)})`));
+  logger.blank();
+  return report;
+}
+
+export function heavyRunCommand(command, options = {}) {
+  const [file, ...args] = command;
+  const gate = createHeavyGate({ projectPath: process.cwd(), label: options.label ?? 'run' });
+  try {
+    gate.enter(file);
+  } catch (err) {
+    if (!(err instanceof HeavyBusyError)) throw err;
+    console.error(chalk.yellow(`\n⏳ ${file} não rodou: ${err.message}. Tente de novo quando liberar (\`morph-spec heavy status\`).\n`));
+    process.exit(EXIT_BUSY);
+  }
+
+  const exe = process.platform === 'win32' && NEEDS_CMD_SHIM.test(file) ? `${file}.cmd` : file;
+  const res = spawnSync(exe, args, { stdio: 'inherit', shell: exe.endsWith('.cmd') });
+  gate.release();
+
+  if (res.error) {
+    console.error(chalk.red(`\n❌ não consegui executar ${file}: ${res.error.message}\n`));
+    process.exit(127);
+  }
+  process.exit(res.status ?? 1);
+}

package/src/commands/project/init.js

@@ -288,7 +288,7 @@ export async function initCommand(options) {
         spinner.stop();
         const existingMcps = claudeConfigDetected?.mcpServers || [];
         const orchestration = orchestrateMcpSetup(targetPath, detectedStack, existingMcps,
-          { integrations: config.project?.integrations ?? [] });
+          { integrations: config.project?.integrations ?? [], enabledPlugins: claudeConfigDetected?.enabledPlugins ?? [] });
 
         const autoNames = Object.keys(orchestration.autoInstallable);
         const manualNames = Object.keys(orchestration.needsManualSetup);

package/src/commands/project/update.js

@@ -33,6 +33,7 @@ import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
 import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
 import { createEffects } from '../../lib/installers/effects.js';
+import { applyEditorSettings } from '../../lib/worktree/vscode-settings.js';
 import { registerProject } from '../../lib/projects/registry.js';
 import {
   writeGraphifyignore, describeOutdatedIgnore, graphifyignoreTracked,
@@ -729,6 +730,9 @@ export async function updateCommand(options = {}) {
     await updateGitignore(targetPath, fx);
     await ensureGitattributes(targetPath, fx);
 
+    updateSpinner.text = 'Editor excludes for worktrees (.vscode/settings.json)...';
+    try { applyEditorSettings(targetPath, { fx }); } catch { /* fail-open */ }
+
     // Migration: a .graphifyignore the previous version generated and nobody
     // edited is swapped for the current one when its RULES change (test doubles
     // and fixtures back in the graph — a header-only difference is left alone);

package/src/commands/project/worktree-reap.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import { reapAgentWorktrees } from '../../lib/worktree/agent-reaper.js';
+
+const label = (item) => item.path ?? item.branch ?? item.hex;
+
+function printReport(out) {
+  const mode = out.dryRun ? ' (simulação)' : '';
+  console.log(chalk.bold(`\nWorktrees de sub-agent${mode} — graça de ${out.graceMinutes} min\n`));
+  if (out.busy) console.log(chalk.yellow('  ⏳ outro reaper está em execução; nada foi feito\n'));
+
+  for (const item of out.wouldReap ?? []) console.log(chalk.cyan(`  → removeria: ${label(item)}`));
+  for (const item of out.reaped) console.log(chalk.green(`  ✓ removido: ${label(item)}${item.backup ? chalk.gray(` (backup: ${item.backup})`) : ''}`));
+  for (const item of out.preserved) {
+    console.log(chalk.yellow(`  ⚠ preservado: ${label(item)} — ${item.reason}${item.detail ? `: ${item.detail}` : ''}`));
+  }
+  if (out.active) console.log(chalk.gray(`  ${out.active} agente(s) ainda ativo(s), intocado(s)`));
+  const nothing = !out.reaped.length && !out.preserved.length && !out.active && !(out.wouldReap ?? []).length;
+  if (nothing && !out.busy) console.log(chalk.green('  ✓ nenhuma worktree de sub-agent sobrando'));
+  console.log();
+}
+
+export async function worktreeReapCommand(options = {}) {
+  const grace = options.grace === undefined ? undefined : Number(options.grace);
+  if (grace !== undefined && !(Number.isFinite(grace) && grace >= 0)) {
+    console.error(chalk.red(`--grace precisa ser um número de minutos >= 0 (recebi "${options.grace}")`));
+    process.exit(2);
+  }
+
+  const out = await reapAgentWorktrees(options.cwd || process.cwd(), { dryRun: options.dryRun === true, graceMinutes: grace });
+  if (options.json) console.log(JSON.stringify(out));
+  else if (out.ok) printReport(out);
+  else console.log(chalk.gray(`  fora de um repositório git — nada a fazer (${out.error})`));
+  return out;
+}

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 };
@@ -886,7 +908,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 +923,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 +961,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;
 
@@ -1388,6 +1412,12 @@ 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[],
@@ -1395,7 +1425,7 @@ export function pickRemovalFailure(stderrs) {
  *   relinked: boolean, refused: boolean, infraLeftUnlinked: string[],
  *   removalFailure: {kind: string, detail: 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.
   //
@@ -1463,7 +1493,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 +1502,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 +1539,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,
@@ -1580,8 +1617,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 +1638,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 +1662,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 +1679,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 +1695,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 +1705,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 +1720,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 +1764,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,
@@ -1763,7 +1803,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 ─────────────────────────────────────────────────────────────────