@polymorphism-tech/morph-spec 8.31.0 → 8.33.0

package/src/commands/project/doctor.js

@@ -1,11 +1,14 @@
 import { join, relative } from 'path';
 import { execSync } from 'child_process';
+import { existsSync } from 'fs';
 import { platform, homedir } from 'os';
 import fs from 'fs-extra';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
 import { pathExists, readJson } from '../../utils/file-copier.js';
 import { checkClaudeMdImport } from '../../utils/claude-md-injector.js';
+import { buildPrIndex } from '../../lib/git/pr-index.js';
+import { pendingPrFeatures, MORPH_BRANCH_RE } from '../../lib/git/pending-prs.js';
 import {
   checkCLIOutdated,
   checkProjectOutdated,
@@ -556,10 +559,12 @@ async function doctorMcpCommand(targetPath) {
  * Orphan worktrees used to accumulate invisibly: `fleet` only reports worktrees
  * on a `morph/*` branch, so anything else never showed up anywhere.
  *
- * `--prune` runs the one safe repair (`git worktree prune`: admin records for
- * directories that are already gone). Deleting a directory that still exists is
- * reported with the exact command, never performed — same PROVE-or-DECLINE
- * discipline as the finish teardown.
+ * `--prune` runs the safe repairs: `git worktree prune` (admin records for
+ * directories that are already gone) and the removal of EMPTY unregistered
+ * residue directories, which by definition hold nothing that can be lost.
+ * Deleting a directory that still HOLDS something is reported with the exact
+ * command, never performed — same PROVE-or-DECLINE discipline as the finish
+ * teardown.
  */
 export async function doctorWorktreesCommand(targetPath, options = {}) {
   const { auditWorktrees, pruneWorktrees } = await import('../../lib/worktree/worktree-audit.js');
@@ -568,19 +573,28 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     const beforeIssues = auditWorktrees(targetPath);
     const beforeMissing = beforeIssues.filter((i) => i.type === 'registered-missing').length;
     const beforeDangling = beforeIssues.filter((i) => i.type === 'dangling-registration').length;
+    const beforeEmptyDirs = beforeIssues.filter((i) => i.type === 'unregistered-dir' && i.empty).length;
     const result = await pruneWorktrees(targetPath);
     if (result.pruned) logger.success(`git worktree prune: ${beforeMissing} registro(s) órfão(s) removido(s).`);
     else logger.warn(`prune falhou: ${result.error}`);
+    if (result.removedEmptyDirs.length) {
+      logger.success(`${result.removedEmptyDirs.length}/${beforeEmptyDirs} diretório(s) vazio(s) removido(s): ${result.removedEmptyDirs.join(', ')}`);
+    }
     if (result.clearedRegistrations.length) {
       logger.success(`registro de worktree limpo em ${result.clearedRegistrations.length}/${beforeDangling} feature(s): ${result.clearedRegistrations.map((r) => r.feature).join(', ')}`);
     }
   }
 
   const issues = auditWorktrees(targetPath);
+  // `severity: 'info'` entries (a worktree carrying unintegrated work) are
+  // REPORTED but are not failures — a `doctor --worktrees || ...` in CI must not
+  // go red because somebody has an open PR. The human path below splits the same
+  // way; both surfaces must agree on what counts as broken.
+  const isProblem = (i) => i.severity !== 'info';
 
   if (options.json) {
     console.log(JSON.stringify({ issues }, null, 2));
-    return issues.length === 0;
+    return !issues.some(isProblem);
   }
 
   logger.header('MORPH-SPEC Worktrees');
@@ -589,18 +603,90 @@ export async function doctorWorktreesCommand(targetPath, options = {}) {
     return true;
   }
 
-  logger.warn(`${issues.length} inconsistência(s):`);
-  for (const i of issues) {
+  // `unintegrated-work` is NOT an inconsistency — it is a worktree doing its
+  // job, reported so the reader knows why no cleanup is offered for it. Counting
+  // it as a problem is how a diagnostic starts nagging people into destroying
+  // things to make the warning go away.
+  const informational = issues.filter((i) => !isProblem(i));
+  const problems = issues.filter(isProblem);
+
+  if (problems.length) logger.warn(`${problems.length} inconsistência(s):`);
+  for (const i of problems) {
     console.log(`  ⚠ ${i.type}`);
     console.log(`     ${i.detail}`);
     console.log(`     → ${i.fix}`);
   }
-  if (issues.some((i) => i.type === 'registered-missing' || i.type === 'dangling-registration') && !options.prune) {
-    logger.dim('\n  Rode `morph-spec doctor --worktrees --prune` para limpar os registros órfãos.');
+  for (const i of informational) {
+    console.log(`  ℹ ${i.type}`);
+    console.log(`     ${i.detail}`);
+    console.log(`     → ${i.fix}`);
+  }
+  // An EMPTY unregistered directory is prunable too — it holds nothing that can
+  // be lost — so the hint must mention it, or the one issue `--prune` now fixes
+  // automatically would still read as a manual chore.
+  const prunable = (i) => i.type === 'registered-missing'
+    || i.type === 'dangling-registration'
+    || (i.type === 'unregistered-dir' && i.empty);
+  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 (!problems.length) {
+    logger.success('Nenhuma inconsistência — os itens acima são informativos.');
+    return true;
   }
   return false;
 }
 
+/** Dias a partir dos quais um PR aberto vira aviso. */
+const PR_STALE_DAYS = 7;
+
+/**
+ * As inconsistências de PR desta árvore.
+ *
+ *   pr-awaiting-merge   — PR aberto há muito, sem cópia local: trabalho em
+ *                         revisão que nenhuma superfície local reivindica.
+ *   pr-merged-not-landed — o PR mergeou mas `archive/{f}` não está aqui. O
+ *                         archive viaja no diff do PR, então ou falta um
+ *                         `git pull`, ou ele não estava no diff.
+ *
+ * Offline-safe: índice `null` devolve `null`, NUNCA lista vazia — lista vazia
+ * afirmaria "perguntei e não achei nada", que é diferente de "não pude
+ * perguntar". Achado #3: um `[]` disfarçado de "sem problema" é o que fazia
+ * `doctor` imprimir `✓ pull requests` mesmo sem conseguir consultar o `gh`.
+ *
+ * @returns {Array<{feature:string,type:string,detail:string}>|null}
+ *   null = DESCONHECIDO (índice não pôde ser construído); nunca "sem PRs".
+ */
+function auditPullRequests(root) {
+  const index = buildPrIndex(root);
+  if (!index) return null;
+  const issues = [];
+
+  for (const p of pendingPrFeatures(root, { index }) || []) {
+    if (p.ageDays != null && p.ageDays >= PR_STALE_DAYS) {
+      issues.push({
+        feature: p.feature,
+        type: 'pr-awaiting-merge',
+        detail: `PR #${p.number} aberto há ${p.ageDays}d e sem cópia local — mergeie ou feche`,
+      });
+    }
+  }
+
+  for (const [branch, pr] of index) {
+    const m = branch.match(MORPH_BRANCH_RE);
+    if (!m || pr.state !== 'MERGED') continue;
+    const feature = m[1];
+    if (existsSync(join(root, '.morph', 'archive', feature))) continue;
+    issues.push({
+      feature,
+      type: 'pr-merged-not-landed',
+      detail: `PR #${pr.number} foi mergeado mas .morph/archive/${feature} não está aqui — falta \`git pull\`?`,
+    });
+  }
+
+  return issues;
+}
+
 export async function doctorCommand(options = {}) {
   // `--json` and `--prune` only mean something under `--worktrees`. Falling
   // through to the human health check would hand a script a banner and a table
@@ -1075,6 +1161,32 @@ export async function doctorCommand(options = {}) {
     hasWarnings = true;
   }
 
+  // Pull requests — o pendurado (aberto há dias sem cópia local) e o mergeado
+  // que não pousou (archive não chegou nesta árvore). Offline-safe: sem `gh`,
+  // sem origin no GitHub, ou qualquer falha, `auditPullRequests` nunca lança
+  // (achado #7 — mesma guarda fail-open que `fleet-scanner.js` já usa para a
+  // síntese idêntica) e devolve `null` — achado #3: um índice desconhecido
+  // renderiza como "não verificado", nunca como `✓ ok`, porque `[]` e
+  // "não pude perguntar" não são a mesma coisa.
+  let prIssues;
+  try {
+    prIssues = auditPullRequests(targetPath);
+  } catch {
+    prIssues = null; // fail-open — um doctor não pode ficar mais ruidoso porque o gh sumiu
+  }
+  if (prIssues === null) {
+    checks.push({ name: 'pull requests', status: 'skip', msg: 'gh indisponível — não verificado' });
+  } else if (prIssues.length === 0) {
+    checks.push({ name: 'pull requests', status: 'ok' });
+  } else {
+    checks.push({
+      name: 'pull requests',
+      status: 'warn',
+      msg: `${prIssues.length} pendência${prIssues.length === 1 ? '' : 's'} (veja abaixo)`,
+    });
+    hasWarnings = true;
+  }
+
   // Codebase graph — opcional (ADR-002). Nunca 'missing': um projeto que não
   // usa o grafo tem de continuar com o doctor verde.
   const graphAudit = auditGraph(targetPath);
@@ -1130,6 +1242,11 @@ export async function doctorCommand(options = {}) {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(' (missing)'));
     } else if (check.status === 'error') {
       console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    } else if (check.status === 'skip') {
+      // "Não verificado" — nem ok nem falha. Nunca soma em hasWarnings/hasErrors:
+      // um `gh` indisponível não pode deixar o doctor mais barulhento nem mudar
+      // o exit code (achado #3).
+      console.log(chalk.gray(`  ○ ${check.name}`) + chalk.gray(check.msg ? ` (${check.msg})` : ''));
     }
   }
 
@@ -1144,6 +1261,17 @@ export async function doctorCommand(options = {}) {
     console.log(chalk.gray("    Fix: 'morph-spec approve' (order), '--description' on create, or 'morph-spec delete' for dead scaffolds."));
   }
 
+  // Per-feature detail for the PR inconsistencies (item: pendurado ou merge
+  // que não pousou).
+  if (prIssues?.length) {
+    logger.blank();
+    console.log(chalk.yellow('  Pull requests pendentes:'));
+    for (const issue of prIssues) {
+      console.log(chalk.gray(`    • ${issue.feature} [${issue.type}] — ${issue.detail}`));
+    }
+    console.log(chalk.gray('    `finish --pr` abre o PR; quem encerra a feature é o merge.'));
+  }
+
   logger.blank();
 
   if (hasErrors) {

package/src/commands/project/fleet.js

@@ -55,14 +55,21 @@ export function fleetCommand(options = {}) {
   };
 
   console.log(chalk.white.bold(
-    col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 11) + col('TASKS', 8)
+    // PHASE at 18: `aguardando-merge` (the pr-pending synthesized phase, see
+    // fleet-scanner.js) is 16 chars — 1 wider than the col width `list.js`
+    // already uses (17) for the identical string. A narrower column here
+    // would misalign every column after it just for that one row.
+    col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 18) + col('TASKS', 8)
     + col('GATES PEND.', 20) + col('WHERE', 24) + col('REMOTO', 16) + col('CLAIM', 16)
     + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
   ));
   for (const e of fleet.entries) {
     const tasks = e.tasks ? `${e.tasks.done}/${e.tasks.total}` : '-';
     const gates = e.pendingGates.length ? e.pendingGates.join(',') : '-';
-    const where = e.location === 'worktree' ? e.branch : 'raiz';
+    // pr-pending has no worktree and isn't root-resident either — its branch
+    // is the only place it exists, so show that instead of the misleading
+    // 'raiz' a location-blind check would print.
+    const where = (e.location === 'worktree' || e.location === 'pr-pending') ? e.branch : 'raiz';
     const ports = e.env ? `${e.env.range[0]}-${e.env.range[1]}` : '-';
     const handoff = e.handoff?.exists ? 'sim' : '-';
     const activity = [
@@ -73,7 +80,7 @@ export function fleetCommand(options = {}) {
     // length and append the padding by hand.
     const claimPlain = e.claim ? `${e.claim.live ? 'sessão' : 'morta'} (${claimAge(e.claim)})` : '-';
     console.log(
-      col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 11) + col(tasks, 8)
+      col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 18) + col(tasks, 8)
       + col(gates, 20) + col(where, 24) + col(remoteCell(e.remote), 16)
       + claimCell(e.claim) + ' '.repeat(Math.max(1, 16 - claimPlain.length))
       + col(ports, 12) + col(handoff, 9) + activity,

package/src/commands/project/worktree.js

@@ -35,6 +35,7 @@ import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, append
 import { join, resolve, dirname } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
+import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
 // The reparse scan lives in hooks/shared because the PreToolUse guardrail needs
 // the SAME answer this file does, and hooks can never import from `src/`.
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
@@ -767,23 +768,6 @@ export function unlinkWorktreeInfraLinks(worktreePath, mainCwd) {
  */
 const IGNORED_SHIELDABLE_PREFIXES = ['.morph/'];
 
-/**
- * Well-known, regenerable build artifacts — `bin/`, `obj/` (dotnet), a real
- * `node_modules` left behind outside the setup-created junction, and
- * `*.tsbuildinfo` (tsc incremental cache). These are the everyday leftovers of
- * running a build/test cycle inside a worktree, not user data: they are fully
- * reproducible from source, and requiring `--discard-ignored` for every finish
- * that ever ran a build turns the flag from "explicit consent for a real risk"
- * into a rubber stamp nobody reads anymore. Auto-discarding them (like any
- * `discarded` entry, WITHOUT a backup — see the note below) is safe precisely
- * because "regenerable" is a stronger guarantee than "backed up".
- *
- * Deliberately narrow — do NOT add speculative patterns (`dist/`, `.next/`)
- * beyond what's proven to be pure noise; anything else stays in `blocking` by
- * default, requiring the explicit `--discard-ignored` consent.
- *
- * @param {string} p - forward-slash relative path from `git status --ignored`
- */
 /**
  * Whether a dirty root-side path is EXACTLY a sibling feature's live worktree
  * registration — see the call site (primaryRootUnexplainedDirt, the root-clean
@@ -811,16 +795,9 @@ function isLiveSiblingWorktreeRegistration(relPath, root, feature) {
   }
 }
 
-function isDisposableBuildArtifact(p) {
-  if (/\.tsbuildinfo$/.test(p)) return true;
-  const segments = p.split('/').filter(Boolean);
-  return segments.some((s) => s === 'bin' || s === 'obj' || s === 'node_modules');
-}
-
 /**
- * Split the worktree's GITIGNORED leftovers into what this command may remove
- * (morph's own, after a backup, or a known disposable build artifact, without
- * one) and what it must refuse to destroy.
+ * Split the worktree's GITIGNORED leftovers into what this command may delete
+ * outright, what it must COPY OUT first, and what it cannot even enumerate.
  *
  * Why this exists: `git worktree remove` deletes gitignored files outright, and
  * the clean-check that gates it uses `git status --porcelain`, which omits them
@@ -829,14 +806,33 @@ function isDisposableBuildArtifact(p) {
  * disposable; morph must not, because "not in git" is exactly the property that
  * makes a file unrecoverable.
  *
- * Fail-CLOSED: if the status call fails we cannot enumerate what is at stake, so
- * everything is reported as blocking.
+ * The buckets, and why refusing is no longer one of them: the earlier version
+ * blocked on ANY unrecognised gitignored path, which in practice meant blocking
+ * on `.env` files that were byte-identical to the primary root's — nothing was
+ * at stake, and the only escape offered (`--discard-ignored`) also destroyed the
+ * genuinely unique `keys/` next to them. `triageIgnoredPaths` answers the
+ * question that actually decides whether bytes are lost (see ignored-triage.js),
+ * so the command can PROCEED in every case, backing up only what exists nowhere
+ * else. A refusal survives for exactly one reason now: the backup FAILED.
+ *
+ *   shieldable — morph's own bookkeeping + anything EXCLUSIVE to this worktree.
+ *                Copied to `finish-backup` before the removal; a failed copy is
+ *                what declines the removal.
+ *   discarded  — build artifacts (regenerable) and REPLICABLE files (the root
+ *                holds the same path with the same SHA-256). Deleted without a
+ *                backup because neither loses bytes.
+ *   blocking   — the fail-CLOSED sentinel only: `git status --ignored` itself
+ *                failed, so we cannot enumerate what is at stake.
+ *
+ * `--discard-ignored` no longer means "destroy the unique ones too, blind"; it
+ * means SKIP THE BACKUP — the same removal, without the copy.
  *
  * @param {string} worktreePath
+ * @param {string} rootPath - the primary root, for the replica comparison
  * @param {{ discardIgnored?: boolean }} options
- * @returns {{ shieldable: string[], blocking: string[], discarded: string[] }}
+ * @returns {{ shieldable: string[], blocking: string[], discarded: string[], replicable: string[] }}
  */
-function classifyIgnoredLeftovers(worktreePath, options = {}) {
+function classifyIgnoredLeftovers(worktreePath, rootPath, options = {}) {
   let out;
   try {
     // `-z` + execFile: NUL-delimited, no shell, no C-style quoting to undo —
@@ -850,30 +846,30 @@ function classifyIgnoredLeftovers(worktreePath, options = {}) {
     // empirically, not assumed.
     out = execFileSync('git', ['status', '--porcelain', '--ignored=matching', '-z'], { cwd: worktreePath, stdio: 'pipe' }).toString();
   } catch {
-    return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'], discarded: [] };
+    return { shieldable: [], blocking: ['<git status --ignored falhou — não foi possível enumerar o que seria destruído>'], discarded: [], replicable: [] };
   }
 
-  const shieldable = [];
-  const blockingRest = [];
-  const disposable = [];
+  const morphOwned = [];
+  const rest = [];
   for (const record of out.split('\0')) {
     if (!record || record.length < 4) continue;
     if (record.slice(0, 2) !== '!!') continue; // only ignored entries; the rest is the clean-check's job
     const p = record.slice(3).replace(/\\/g, '/');
-    if (IGNORED_SHIELDABLE_PREFIXES.some((prefix) => p.startsWith(prefix))) shieldable.push(p);
-    else if (isDisposableBuildArtifact(p)) disposable.push(p);
-    else blockingRest.push(p);
+    if (IGNORED_SHIELDABLE_PREFIXES.some((prefix) => p.startsWith(prefix))) morphOwned.push(p);
+    else rest.push(p);
+  }
+
+  const { replicable, disposable, exclusive } = triageIgnoredPaths({ worktreePath, rootPath, paths: rest });
+  const shieldable = [...morphOwned, ...exclusive];
+
+  // Explicit consent = SKIP THE BACKUP, not "widen what dies". The same paths
+  // are removed either way; the flag only decides whether a copy is made first.
+  // The list is never thrown away — these are the bytes that exist nowhere
+  // else, and reporting them is the least this can do.
+  if (options.discardIgnored) {
+    return { shieldable: [], blocking: [], discarded: [...disposable, ...replicable, ...shieldable], replicable };
   }
-  // Explicit consent clears the rest of the block too — but the list is NOT
-  // thrown away. These are the files that exist nowhere else, and they are the
-  // ones about to die; reporting them is the least this can do. (Backing them
-  // up instead is not an option: this bucket is where arbitrarily large
-  // leftovers land, so a copy is unbounded. The user declared them
-  // disposable — they still get told.)
-  if (options.discardIgnored) return { shieldable, blocking: [], discarded: [...disposable, ...blockingRest] };
-  // Known build artifacts are discarded by default, no flag required — they
-  // are reproducible from source, unlike anything else in `blockingRest`.
-  return { shieldable, blocking: blockingRest, discarded: disposable };
+  return { shieldable, blocking: [], discarded: [...disposable, ...replicable], replicable };
 }
 
 /**
@@ -1177,7 +1173,7 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const unlinked = unlinkWorktreeInfraLinks(worktreePath, root);
 
   const scan = findReparsePoints(worktreePath);
-  const ignored = classifyIgnoredLeftovers(worktreePath, options);
+  const ignored = classifyIgnoredLeftovers(worktreePath, root, options);
   const blockers = [...scan.points, ...scan.unprovable];
 
   // Back up ONLY once the removal is otherwise cleared: nothing is destroyed on
@@ -1257,14 +1253,22 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
   const removeCmd = (addressByTarget || !isValidFeatureName(feature))
     ? `morph-spec worktree remove --target "${worktreePath}"`
     : `morph-spec worktree remove ${feature}`;
+  const backupDir = join(root, '.git', 'morph-spec', 'finish-backup');
+  const sample = (list) => `${list.slice(0, 5).join(', ')}${list.length > 5 ? `, +${list.length - 5}` : ''}`;
   const declineReason = worktreeRemoved
     ? null
     : ignored.blocking.length
-      ? `worktree NÃO removido: contém arquivo(s) gitignored que existem só ali e a remoção apagaria (${ignored.blocking.slice(0, 5).join(', ')}${ignored.blocking.length > 5 ? `, +${ignored.blocking.length - 5}` : ''}). Salve o que importa e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` para descartá-los deliberadamente`
+      ? `worktree NÃO removido: não foi possível enumerar os arquivos gitignored (${sample(ignored.blocking)}), então não dá para provar que a remoção não destrói nada. Rode \`git status --ignored\` dentro do worktree para ver o que está travando e tente de novo com \`${removeCmd}\``
       : blockers.length
         ? `worktree NÃO removido: ainda contém link(s)/caminho(s) não verificáveis (${blockers.join(', ')}) que a remoção seguiria para fora, apagando o alvo na raiz. Remova-os e rode \`${removeCmd}\``
         : ignored.shieldable.length && ignoredBackup === null
-          ? `worktree NÃO removido: o backup do gitignored do worktree falhou, e sem ele a remoção seria destrutiva. Libere espaço/permissão em \`.git/morph-spec/\` e rode \`${removeCmd}\`, ou \`${removeCmd} --discard-ignored\` se não precisar desse conteúdo`
+          // The ONLY gitignored refusal left. The old hint was circular — it
+          // said "salve o que importa e rode <the command that just failed>".
+          // This one names WHAT is exclusive, what was replicable (so the
+          // reader stops worrying about those), and WHERE the copy was going.
+          ? `worktree NÃO removido: o backup falhou. Estes arquivos existem só neste worktree e a remoção os apagaria: ${sample(ignored.shieldable)}. `
+            + (ignored.replicable.length ? `(${sample(ignored.replicable)} são idênticos aos da raiz — esses não são o problema.) ` : '')
+            + `O backup iria para \`${backupDir}\`; libere espaço/permissão ali e rode \`${removeCmd}\`, ou copie os arquivos você mesmo e rode \`${removeCmd} --discard-ignored\` para pular o backup`
           : 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`;
@@ -1273,6 +1277,14 @@ export async function teardownWorktree(worktreePath, { root, feature, branch, op
     worktreeRemoved,
     ignoredBackup,
     discarded: ignored.discarded,
+    replicable: ignored.replicable,
+    // The infra reparse points this teardown dropped BEFORE letting git near
+    // the directory. Reported because it is the load-bearing safety step of the
+    // whole operation and was previously invisible: the user had no way to see
+    // that `.claude` was a junction into the primary root, nor that it was
+    // unlinked rather than followed. On a removal it is the proof the root's
+    // real `.claude/` was never at risk.
+    unlinked,
     blockers,
     ignoredBlocking: ignored.blocking,
     shieldable: ignored.shieldable,
@@ -1405,13 +1417,24 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
     ...(branch ? { branch } : {}),
     ...(feature ? { feature } : {}),
   };
+  // Reported on BOTH paths: on a removal it is the proof the primary root's
+  // real `.claude/`/`.morph/framework/` were unlinked rather than followed; on
+  // a refusal it is what `relinked` did or did not put back.
+  if (teardown.unlinked.length) out.unlinked = teardown.unlinked;
   if (teardown.worktreeRemoved) {
     if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+    // Broken out of `discardedIgnored` on purpose: "deleted" and "deleted
+    // because the identical bytes are still in the root" are not the same
+    // report, and the second is the one that needs no follow-up from the user.
+    if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.ignoredBackup) out.ignoredBackup = teardown.ignoredBackup;
+    if (teardown.shieldable.length) out.backedUp = teardown.shieldable;
   } else {
     out.refused = teardown.refused;
     if (teardown.blockers.length) out.reparsePoints = teardown.blockers;
     if (teardown.ignoredBlocking.length) out.ignoredFiles = teardown.ignoredBlocking;
+    if (teardown.shieldable.length) out.exclusiveIgnored = teardown.shieldable;
+    if (teardown.replicable.length) out.replicatedInRoot = teardown.replicable;
     if (teardown.infraLeftUnlinked.length) out.infraLeftUnlinked = teardown.infraLeftUnlinked;
     out.hint = teardown.declineReason;
   }

package/src/commands/state/finish.js

@@ -13,6 +13,7 @@ import {
   cwdIsInsideWorktree,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { resolveGh } from '../../lib/git/gh.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
 import {
   composeProjectName,
@@ -326,7 +327,7 @@ export async function finishCommand(feature, options = {}) {
           branch: expectedBranch,
           base: target,
           archived: archivePath.replace(/\\/g, '/'),
-          ...(typeof openPr === 'string' ? { pr: openPr } : {}),
+          ...(typeof openPr === 'string' ? { pr: { number: prNumberFromUrl(openPr), url: openPr } } : {}),
           hint: `'${feature}' já foi arquivada e ${expectedBranch} já tem PR aberto — o finish anterior concluiu. Falta apenas mergear o PR.`,
         });
         process.exit(1);
@@ -487,7 +488,7 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
       // VALID (it still names a live directory), so nothing to clean up here —
       // only report where it lives and how to close it later.
       emit({
-        finished: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false,
+        finished: true, integrated: true, mode: 'merge', feature, merged: expectedBranch, kept: true, worktreeRemoved: false,
         worktree: { path: worktreePath, branch: expectedBranch },
         hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
         ...backupNote, ...ucNote,
@@ -526,10 +527,26 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
   }
   tryGit(['branch', '-d', expectedBranch], root);
   // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ finished: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote });
+  emit({ finished: true, integrated: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote });
   process.exit(0);
 }
 
+/**
+ * O número do PR a partir da url que o `gh pr create` imprime.
+ *
+ * Existe porque o número é o que um humano usa para falar do PR ("mergeia o
+ * #51"), e a url é a única coisa que o `gh` devolve. Um formato inesperado
+ * devolve `null` em vez de um palpite: o payload prefere admitir que não sabe
+ * o número a afirmar um errado.
+ *
+ * @param {string|null} url
+ * @returns {number|null}
+ */
+export function prNumberFromUrl(url) {
+  const m = typeof url === 'string' ? url.match(/\/pull\/(\d+)(?:[/?#]|$)/) : null;
+  return m ? Number(m[1]) : null;
+}
+
 // ── PR integration (push + gh, no local merge) ───────────────────────────────
 
 async function integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch }) {
@@ -571,13 +588,23 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     dropFromRootIndex(root, feature);
   }
 
+  const prNumber = prNumberFromUrl(prUrl);
+  const prLabel = prNumber ? `#${prNumber}` : 'o PR';
+
   const out = {
     finished: true,
+    // O comando terminou; a INTEGRAÇÃO não aconteceu. Eram a mesma coisa no
+    // payload antigo, e é dessa colisão que sai o "shipped" para uma feature
+    // cujo PR seguia aberto: quem lê `finished: true` sem mais nada conclui
+    // que acabou. A default só recebe archive/{f} quando o PR mergear.
+    integrated: false,
+    awaiting: 'merge',
     mode: 'pr',
     feature,
     pushed: expectedBranch,
     base: defaultBranch,
-    pr: prUrl,
+    pr: { number: prNumber, url: prUrl },
+    nextStep: `mergeie ${prLabel} — a feature só estará encerrada quando ${defaultBranch} receber o archive pelo merge`,
     ...promotedNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
     ...(teardown
@@ -626,6 +653,7 @@ const MERGE_NEXT_STEP = 'integração LOCAL — nada foi publicado. Rode `git pu
 function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
   return {
     finished: true,
+    integrated: true,
     mode: 'merge',
     feature,
     merged: branch,
@@ -641,6 +669,15 @@ function teardownExtras(teardown, worktreePath, branch, deleteBranch) {
   const out = {};
   if (teardown.ignoredBackup) out.worktreeIgnoredBackup = teardown.ignoredBackup;
   if (teardown.worktreeRemoved && teardown.discarded.length) out.discardedIgnored = teardown.discarded;
+  // WHAT was copied out, and what needed no copy because the primary root holds
+  // the identical bytes. Reported on both paths: after a removal these two lists
+  // are the whole answer to "did I just lose something?", and the user should
+  // not have to open the backup directory to find out.
+  if (teardown.shieldable?.length) out.worktreeIgnoredBackedUp = teardown.shieldable;
+  if (teardown.replicable?.length) out.replicatedInRoot = teardown.replicable;
+  // The infra reparse points dropped BEFORE git touched the directory — the
+  // proof the primary root's real `.claude/` was unlinked, never followed.
+  if (teardown.unlinked?.length) out.unlinked = teardown.unlinked;
   if (!teardown.worktreeRemoved) {
     out.path = worktreePath;
     out.branch = branch;
@@ -688,28 +725,6 @@ function gitStatusPorcelain(cwd) {
   }
 }
 
-/**
- * Resolve the `gh` invocation. Defaults to the `gh` binary on PATH. Overridable
- * via MORPH_GH_BIN: a plain string names a different binary (a corporate wrapper,
- * `hub`, …); a JSON array is a full argv prefix — e.g.
- * `["/path/to/node","/path/to/gh-shim.js"]` — which is how the tests inject a
- * cross-platform stub that execFileSync can actually spawn (Node ≥20 refuses to
- * run `.cmd`/`.bat` shims without `shell:true`, and shell:true would reopen the
- * arg-injection hole the whole file avoids).
- *
- * @returns {{ bin: string, prefix: string[] }}
- */
-function resolveGh() {
-  const raw = process.env.MORPH_GH_BIN;
-  if (raw && raw.trim().startsWith('[')) {
-    try {
-      const arr = JSON.parse(raw);
-      if (Array.isArray(arr) && arr.length) return { bin: String(arr[0]), prefix: arr.slice(1).map(String) };
-    } catch { /* not JSON — treat as a plain binary name below */ }
-  }
-  return { bin: raw && raw.trim() ? raw.trim() : 'gh', prefix: [] };
-}
-
 function ghAuthOk() {
   const { bin, prefix } = resolveGh();
   try {