@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/commands/state/finish.js

@@ -11,15 +11,14 @@ import {
   buildBranchName,
   branchExists,
   cwdIsInsideWorktree,
+  classifyIgnoredLeftovers,
 } from '../project/worktree.js';
 import { detectDefaultBranch, hasOriginRemote } from '../../lib/git/default-branch.js';
+import { commitsAhead, resolveBaseRef } from '../../lib/git/branch-classifier.js';
 import { resolveGh } from '../../lib/git/gh.js';
 import { releaseClaim } from '../../../framework/hooks/shared/claim-registry.js';
-import {
-  composeProjectName,
-  resolveComposeFile,
-  tearDownStack,
-} from '../../../framework/hooks/shared/e2e-check.js';
+import { tearDownFeatureStack } from '../../lib/e2e/stack-teardown.js';
+import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 import { runArchive } from './archive.js';
 
 /** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
@@ -88,8 +87,14 @@ export function buildPrTitle(feature, fj) {
  * `resumed: true` in its output — see Validation 0c.
  *
  * @param {string} feature
- * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, force?: boolean,
- *   discardIgnored?: boolean, cwd?: string }} [options]
+ * `--dry-run` desvia para {@link finishPreflight} ANTES de qualquer validação
+ * que saia com exit 1 e ANTES de qualquer mutação: o pré-voo existe para
+ * EXPLICAR, e um pré-voo que recusa pelos mesmos motivos do comando real não
+ * explica nada.
+ *
+ * @param {{ pr?: boolean, merge?: boolean, keep?: boolean, keepVolumes?: boolean,
+ *   push?: boolean, force?: boolean, discardIgnored?: boolean, dryRun?: boolean,
+ *   cwd?: string }} [options]
  */
 export async function finishCommand(feature, options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -101,12 +106,11 @@ export async function finishCommand(feature, options = {}) {
   // is the single point that covers merge/PR/--keep alike. Fail-open: a claim
   // that outlives its feature only expires on its own TTL.
   //
-  // The e2e stack rides along for the same reason: `morph-spec verify` leaves it
-  // UP on purpose (cold-starting a container per task is what makes the loop
-  // unusable), so something has to be the one place that reclaims the
-  // containers and their ports when the feature closes. Best-effort by
-  // contract — a stack that refuses to come down must never fail a finish that
-  // already merged.
+  // The e2e stack is NOT reclaimed here: by the time a success is emitted the
+  // worktree that owns the compose file may already be gone. Each integration
+  // path calls `reclaimStack` immediately BEFORE its worktree teardown (or
+  // before its final emit in the common flow) — see stack-teardown.js.
+  //
   // Set by Validation 0c when this run picks up an already-archived feature.
   // Stamped onto EVERY payload emitted from that point on, success or refusal:
   // a resume merges a branch the user did not archive in this run, and that has
@@ -121,7 +125,6 @@ export async function finishCommand(feature, options = {}) {
         const common = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: root, stdio: 'pipe' }).toString().trim();
         if (common) releaseClaim(feature, { gitCommonDir: resolve(root, common) });
       } catch { /* fail-open */ }
-      tearDownE2eStack(feature, root);
     }
     console.log(JSON.stringify(obj));
   };
@@ -142,6 +145,26 @@ export async function finishCommand(feature, options = {}) {
     process.exit(1);
   }
   const mode = wantPr ? 'pr' : 'merge';
+
+  // `--push` publica a DEFAULT depois de um merge local; o fluxo `--pr` não tem
+  // merge local nenhum (a default só recebe a feature quando o PR mergear), e
+  // já publica `morph/{f}` por conta própria. A combinação é um pedido que o
+  // comando não consegue honrar — e aceitar em silêncio o que não se pode
+  // honrar é exatamente o defeito que esta série de fixes existe para tirar do
+  // CLI (o `score` que gravava um zero fabricado, o `approve` que saía 0 sem
+  // aprovar nada). Recusa ALTA, e AQUI: junto do gate de modo, antes do
+  // archive — que é a primeira mutação do finish. Uma recusa depois dele
+  // deixaria a feature meio fechada, pior que o no-op que ela substitui.
+  if (wantPr && options.push) {
+    emit({
+      finished: false,
+      error: 'push-with-pr',
+      hint: `--push não se combina com --pr: o --pr já publica ${buildBranchName(feature)} e abre o PR, enquanto o --push publica a branch default depois de um merge LOCAL — e no fluxo --pr não há merge local. Para publicar a branch e abrir o PR: \`morph-spec finish ${feature} --pr\`. Para integrar na default localmente e publicá-la: \`morph-spec finish ${feature} --merge --push\`.`,
+      feature,
+    });
+    process.exit(1);
+  }
+
   const expectedBranch = buildBranchName(feature);
 
   // ── Resolve the flow ──────────────────────────────────────────────────────
@@ -155,6 +178,29 @@ export async function finishCommand(feature, options = {}) {
   let worktreePath = null;
   let featureCwd = root; // where the feature's own tree (and Gate 3) lives
 
+  // ── PRÉ-VOO ───────────────────────────────────────────────────────────────
+  // AQUI, e não mais abaixo: as validações seguintes saem com exit 1 (branch
+  // divergente, cwd dentro do worktree, feature ausente), e o pré-voo existe
+  // justamente para ser rodado ANTES de o estado estar bom. Ele reporta o que
+  // encontrar — inclusive o cwd dentro do worktree, como AVISO — e sai 0 sem
+  // ter tocado em nada.
+  if (options.dryRun) {
+    emit(finishPreflight({
+      feature,
+      root,
+      worktreePath: isWorktreeFlow ? found.path : null,
+      cwd,
+      mode,
+      branch: expectedBranch,
+      // `options` INTEIRO, e não um subconjunto escolhido a dedo: `--discard-ignored`
+      // INVERTE a classificação (o exclusivo deixa de ser copiado e passa a ser
+      // destruído), então um pré-voo que não recebe as flags do comando prevê
+      // outro comando. Ver B1 na errata E4.
+      options,
+    }));
+    return;
+  }
+
   if (isWorktreeFlow) {
     // Validation 0: the worktree must actually be ON the branch we will merge.
     if (found.branch !== found.expectedBranch) {
@@ -447,6 +493,166 @@ export async function finishCommand(feature, options = {}) {
   return integratePr({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, prTitle, prBody, arch });
 }
 
+/**
+ * O aviso que acompanha CADA reparse point listado pelo pré-voo.
+ *
+ * Exportado porque é a frase que carrega o fato: uma junction/symlink dentro do
+ * worktree aponta para conteúdo que vive na RAIZ, e `rm -rf` / `git worktree
+ * remove --force` atravessam o link. Já aconteceu: um `worktree remove --force`
+ * atravessou a junction e apagou o `node_modules` da raiz.
+ */
+export const REPARSE_WARNING =
+  'estes são junctions/symlinks: apagá-los fora do morph-spec apaga o conteúdo REAL na raiz';
+
+/**
+ * `morph-spec finish <feature> --pr|--merge --dry-run` — o PRÉ-VOO.
+ *
+ * NÃO MUTA NADA. Nenhum commit, nenhum archive, nenhum worktree removido,
+ * nenhum `gh` que crie coisa alguma, nenhum `git fetch`. Ele responde, ANTES,
+ * as três perguntas que hoje só se respondem depois do estrago:
+ *
+ *   1. O que este `finish` vai COPIAR para o backup e o que vai DESCARTAR?
+ *      (`classifyIgnoredLeftovers` — a MESMA função que o teardown consulta;
+ *      um segundo enumerador aqui faria o pré-voo prometer o que o comando não
+ *      cumpre, e um dry-run que mente é pior que nenhum.)
+ *   2. Que reparse points existem, e o que significa apagá-los por fora?
+ *      (`findReparsePoints`, exaustivo e fail-closed.)
+ *   3. A base andou? — a pergunta INVERSA da de #89. Lá se mede "quantos
+ *      commits EU tenho que o upstream não tem"; aqui, "quantos commits
+ *      `origin/{default}` tem que a MINHA base não tem", que é o que decide se
+ *      este merge vai ser trivial ou uma surpresa. Mesma função
+ *      (`commitsAhead`), argumentos invertidos.
+ *
+ * `cwd` dentro do worktree é AVISO, não recusa: o caminho real continua
+ * recusando antes da primeira mutação (Validation 0b), e recusar aqui negaria
+ * ao usuário justamente a explicação que ele veio buscar — do lugar mais
+ * provável de estar quando a pede.
+ *
+ * SEM `git fetch` implícito: um fetch dentro de um comando que promete não
+ * mexer em nada é efeito colateral de rede. O pré-voo AVISA que o dado pode
+ * estar velho e sugere o fetch.
+ *
+ * @param {{ feature: string, root: string, worktreePath: string|null,
+ *   cwd: string, mode: 'pr'|'merge', branch: string,
+ *   options?: { discardIgnored?: boolean, keep?: boolean } }} args
+ * @returns {object} o payload emitido — nunca lança
+ */
+export function finishPreflight({ feature, root, worktreePath, cwd, mode, branch, options = {} }) {
+  const warnings = [];
+
+  // ── A base andou? (vale COM e SEM worktree — UC-16 A1) ────────────────────
+  const defaultBranch = detectDefaultBranch(root);
+  const baseRef = defaultBranch ? resolveBaseRef(defaultBranch, root) : null;
+  // `commitsAhead(base, branch)` conta `base..branch`. Passando a branch da
+  // feature como BASE e o baseRef como BRANCH, contamos o que a default tem e a
+  // feature não — exatamente a pergunta inversa.
+  const commits = baseRef && branchExists(branch, root)
+    ? commitsAhead(branch, baseRef, root)
+    : null;
+
+  const out = {
+    preflight: true,
+    finished: false,
+    feature,
+    mode,
+    branch,
+    baseAdvanced: { ref: baseRef, commits },
+    // `null` é DESCONHECIDO e nunca é renderizado como 0 (UC-16 P6): "não deu
+    // para perguntar" e "a default não andou" são fatos opostos, e confundi-los
+    // é como um `--dry-run` passa confiança que não tem.
+    baseAdvancedNote: commits === null
+      ? (baseRef === null
+        ? 'sem contraparte remota nem branch default resolvível — a contagem é DESCONHECIDA, não zero'
+        : 'não foi possível comparar as refs — a contagem é DESCONHECIDA, não zero')
+      : `o dado é do último \`git fetch\`; rode \`git fetch ${PUSH_REMOTE}\` para atualizá-lo (o pré-voo não faz fetch: ele promete não mexer em nada)`,
+    warnings,
+    wouldDo: mode === 'merge'
+      ? [
+        `arquivar .morph/features/${feature} em .morph/archive/${feature} (commit na branch ${branch})`,
+        `fazer merge --no-ff de ${branch} em ${defaultBranch || '<default não resolvida>'} LOCALMENTE (sem push)`,
+        ...(worktreePath ? [`derrubar o stack e remover o worktree ${worktreePath.replace(/\\/g, '/')}${options.discardIgnored === true ? ' — SEM copiar os gitignored exclusivos para o backup (--discard-ignored)' : ''}`] : []),
+      ]
+      : [
+        `arquivar .morph/features/${feature} em .morph/archive/${feature} (commit na branch ${branch})`,
+        `publicar ${branch} em ${PUSH_REMOTE} e abrir um PR contra ${defaultBranch || '<default não resolvida>'} (NÃO integra: o merge do PR é que encerra)`,
+        ...(worktreePath ? [`derrubar o stack e remover o worktree ${worktreePath.replace(/\\/g, '/')}${options.discardIgnored === true ? ' — SEM copiar os gitignored exclusivos para o backup (--discard-ignored)' : ''}`] : []),
+      ],
+  };
+
+  if (defaultBranch) out.defaultBranch = defaultBranch;
+
+  // ── Seções de worktree — omitidas quando não há worktree (UC-16 A1) ───────
+  if (worktreePath) {
+    out.worktreePath = worktreePath.replace(/\\/g, '/');
+
+    const inside = cwdIsInsideWorktree(cwd, worktreePath);
+    out.cwdInsideWorktree = inside;
+    if (inside) {
+      warnings.push(
+        `você está DENTRO de ${out.worktreePath}: o finish de verdade recusa aqui, antes de qualquer mutação `
+        + `(o Windows tranca o diretório de trabalho do processo e a remoção falharia no meio). `
+        + `Rode o finish a partir de "${root.replace(/\\/g, '/')}"`,
+      );
+    }
+
+    // AS MESMAS FLAGS do comando real. `--discard-ignored` INVERTE a
+    // classificação — o exclusivo deixa de ser copiado e entra no lote
+    // destruído sem backup — então prever com `options` vazio é prever OUTRO
+    // comando. Medido antes do conserto: o pré-voo prometia salvar caminhos que
+    // o `--discard-ignored` destruía. Normalizado com `=== true` para que
+    // `undefined` e `false` sejam a mesma coisa, como no `worktree remove`.
+    const discardIgnored = options.discardIgnored === true;
+    const ignored = classifyIgnoredLeftovers(worktreePath, root, { discardIgnored });
+    out.discardIgnored = discardIgnored;
+    out.ignored = {
+      // COPIADO para .git/morph-spec/finish-backup antes da remoção: existe só
+      // aqui, ou difere do que está na raiz. Com `--discard-ignored` esta lista
+      // sai VAZIA por construção — a flag significa "pule o backup".
+      shieldable: ignored.shieldable,
+      // Idêntico byte a byte ao da raiz (SHA-256): apagar não perde nada.
+      replicable: ignored.replicable,
+      // Artefato regenerável + os replicáveis (+ o exclusivo, sob a flag):
+      // descartado sem backup.
+      discardable: ignored.discarded,
+    };
+    if (ignored.blocking.length) {
+      out.ignored.blocking = ignored.blocking;
+      warnings.push('não foi possível enumerar os gitignored do worktree — o finish real vai recusar a remoção');
+    }
+
+    if (discardIgnored) {
+      // SEGUNDA leitura, deliberada e só aqui: sob a flag, `shieldable` sai
+      // vazia e a informação mais valiosa do pré-voo — QUAIS destes existem só
+      // aqui — desapareceria justamente no modo destrutivo. Perguntar à MESMA
+      // função, sem a flag, é a única forma de nomeá-los sem recriar a regra
+      // (uma segunda cópia da triagem é o defeito que o export de
+      // `classifyIgnoredLeftovers` existe para evitar).
+      const semFlag = classifyIgnoredLeftovers(worktreePath, root);
+      out.ignored.discardableExclusive = semFlag.shieldable;
+      if (semFlag.shieldable.length) {
+        warnings.push(
+          `--discard-ignored: ${semFlag.shieldable.length} caminho(s) gitignored existem SÓ neste worktree e serão `
+          + `DESTRUÍDOS sem cópia (${semFlag.shieldable.slice(0, 5).join(', ')}). Sem a flag eles iriam para `
+          + '.git/morph-spec/finish-backup e a remoção aconteceria do mesmo jeito.',
+        );
+      }
+    }
+
+    const scan = findReparsePoints(worktreePath);
+    out.reparsePoints = scan.points;
+    if (scan.unprovable.length) out.reparseUnprovable = scan.unprovable;
+    out.reparseWarning = REPARSE_WARNING;
+    if (scan.points.length) {
+      warnings.push(
+        `${scan.points.length} reparse point(s) no worktree — ${REPARSE_WARNING}. `
+        + 'O `morph-spec worktree remove` derruba os links ANTES de apagar; um `git worktree remove --force` cru, não.',
+      );
+    }
+  }
+
+  return out;
+}
+
 // ── merge integration (local, no push) ───────────────────────────────────────
 
 async function integrateMerge({ emit, root, feature, expectedBranch, defaultBranch, isWorktreeFlow, worktreePath, options, arch }) {
@@ -482,23 +688,26 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
       process.exit(1);
     }
 
+    // Uma medição só para as DUAS saídas deste merge (--keep e normal): é o
+    // mesmo merge, então a contagem e a publicação têm de ser as mesmas.
+    const publish = publicationState({ root, defaultBranch, push: options.push });
+
     if (options.keep) {
       dropFromRootIndex(root, feature);
-      // Worktree preserved on purpose: the root's `worktree` registration stays
-      // 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, 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,
+        ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish, worktreePath, shedBackup, kept: true }),
+        ...ucNote,
       });
       process.exit(0);
     }
 
+    // The stack comes down BEFORE the worktree: the compose file, the bind
+    // mount and the port block all belong to that tree, and once it is gone
+    // there is nothing left to address the containers by.
+    const e2e = reclaimStack(feature, { root, worktreePath, options });
     const teardown = await teardownWorktree(worktreePath, { root, feature, branch: expectedBranch, options, deleteBranch: true });
     dropFromRootIndex(root, feature);
-    emit({ ...mergeOutput({ feature, branch: expectedBranch, worktreePath, teardown, shedBackup }), ...ucNote });
+    emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish, worktreePath, teardown, shedBackup }), ...ucNote, e2e });
     process.exit(0);
   }
 
@@ -526,8 +735,10 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
     process.exit(1);
   }
   tryGit(['branch', '-d', expectedBranch], root);
+  const publish = publicationState({ root, defaultBranch, push: options.push });
+  const e2e = reclaimStack(feature, { root, worktreePath: null, options });
   // The root index (gitignored) was already updated by the archive (same cwd).
-  emit({ finished: true, integrated: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote });
+  emit({ ...mergeOutput({ feature, branch: expectedBranch, defaultBranch, publish }), ...ucNote, e2e });
   process.exit(0);
 }
 
@@ -571,6 +782,11 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
   // feature yet — honest until the PR merges).
   let teardown = null;
   let shedBackup = null;
+  // Reclaimed from the owning tree, before that tree goes away; skipped on
+  // --keep, where the worktree (and its stack) stays alive on purpose.
+  const e2e = isWorktreeFlow
+    ? (options.keep ? null : reclaimStack(feature, { root, worktreePath, options }))
+    : reclaimStack(feature, { root, worktreePath: null, options });
   if (isWorktreeFlow && !options.keep) {
     // Shed the transient root-side scaffold BEFORE teardown — exactly as --merge
     // does. The real `create --worktree` leaves the root's .morph/features/{f}
@@ -607,6 +823,7 @@ async function integratePr({ emit, root, feature, expectedBranch, defaultBranch,
     nextStep: `mergeie ${prLabel} — a feature só estará encerrada quando ${defaultBranch} receber o archive pelo merge`,
     ...promotedNote(arch),
     ...(shedBackup ? { shedBackup } : {}),
+    ...(e2e ? { e2e } : {}),
     ...(teardown
       ? { worktreeRemoved: teardown.worktreeRemoved, ...teardownExtras(teardown, worktreePath, expectedBranch, false) }
       : {
@@ -642,25 +859,125 @@ function promotedNote(arch) {
 }
 
 /**
- * O comando se chama `finish`, e no modo `--merge` ele NÃO publica nada: o
- * merge é local, o remoto continua sem a feature. Quem lê "finished: true"
- * conclui o contrário — foi pegadinha repetida em sessões diferentes. O modo
- * `--pr` empurra e abre o PR; o `--merge` deixa o push para o humano, e é isso
- * que esta linha diz em voz alta.
+ * O único remoto com que o `finish` conversa — o mesmo que `hasOriginRemote` e
+ * o `resolveBaseRef` do branch-classifier assumem. Um nome só, aqui, para que o
+ * comando que a saída IMPRIME e o push que o `--push` EXECUTA jamais possam
+ * nomear remotos diferentes.
+ */
+const PUSH_REMOTE = 'origin';
+
+/**
+ * O que sobrou por publicar depois que o merge local aterrissou — e, com
+ * `--push`, o resultado da publicação.
+ *
+ * A contagem REUSA `resolveBaseRef` + `commitsAhead` (branch-classifier), em vez
+ * de uma terceira cópia de `rev-list --count`. Detalhe que decide o P4:
+ * `resolveBaseRef` degrada para a branch LOCAL quando não existe ref de
+ * rastreamento remoto — comparar a branch consigo mesma devolveria um `0` de
+ * aparência honesta para um repo que nunca deu push. Por isso a comparação só
+ * vale quando o ref resolvido é diferente do nome da branch; caso contrário
+ * `ahead` fica `null` ("incomparável"), nunca zero.
+ *
+ * Fail-open por desenho: o merge JÁ aconteceu quando esta função roda, então
+ * nenhum resultado daqui — nem um push que falhou — pode transformar um sucesso
+ * em exit 1. A falha vira `pushError` no payload.
+ *
+ * @param {{ root: string, defaultBranch: string, push?: boolean }} ctx
+ * @returns {{ remote: string, branch: string, ahead: number|null, pushed: boolean,
+ *   published?: number|null, pushError?: string }}
+ */
+function publicationState({ root, defaultBranch, push }) {
+  const baseRef = resolveBaseRef(defaultBranch, root);
+  const tracked = !!baseRef && baseRef !== defaultBranch;
+  const ahead = tracked ? commitsAhead(baseRef, defaultBranch, root) : null;
+  const state = { remote: PUSH_REMOTE, branch: defaultBranch, ahead, pushed: false };
+
+  if (!push) return state;
+
+  if (!hasOriginRemote(root)) {
+    return { ...state, pushError: 'no-origin-remote' };
+  }
+  try {
+    execFileSync('git', ['push', PUSH_REMOTE, defaultBranch], { cwd: root, stdio: 'pipe' });
+  } catch (err) {
+    return { ...state, pushError: gitErr(err) };
+  }
+  // Re-medir DEPOIS do push: o que ficou para trás é a única prova de que a
+  // publicação foi completa, e um `ahead` congelado do antes seria mentira.
+  const after = resolveBaseRef(defaultBranch, root);
+  const remaining = after && after !== defaultBranch ? commitsAhead(after, defaultBranch, root) : null;
+  return { ...state, published: ahead, ahead: remaining, pushed: true };
+}
+
+/**
+ * A frase do próximo passo — PRODUTOR ÚNICO.
+ *
+ * O comando se chama `finish`, e no modo `--merge` ele NÃO publica nada por
+ * conta própria: o merge é local, o remoto continua sem a feature. Quem lê
+ * "finished: true" conclui o contrário — foi pegadinha repetida em sessões
+ * diferentes. Três saídas de `--merge` montavam esse aviso por conta própria, e
+ * uma delas (o `--keep`) simplesmente esquecia dele; um produtor único é o que
+ * impede a divergência de voltar.
+ *
+ * @param {ReturnType<typeof publicationState>} publish
+ * @returns {string}
  */
-const MERGE_NEXT_STEP = 'integração LOCAL — nada foi publicado. Rode `git push` para levar ao remoto.';
+function mergeNextStep(publish) {
+  const { remote, branch, ahead, pushed, published, pushError } = publish;
+  const pushCmd = `\`git push ${remote} ${branch}\``;
+
+  if (pushed) {
+    const n = typeof published === 'number' ? `${published} commit(s)` : 'a integração';
+    return `PUBLICADO — ${n} de ${branch} enviado(s) para ${remote}/${branch} pelo --push.`;
+  }
+  if (pushError === 'no-origin-remote') {
+    return `integração LOCAL — nada foi publicado: --push foi pedido mas não há remoto \`${remote}\` configurado.`;
+  }
+  if (pushError) {
+    return `integração LOCAL — o push pedido por --push FALHOU e nada foi publicado. Rode ${pushCmd} manualmente.`;
+  }
+  // Sem contraparte remota não se inventa contagem (P4): fica a frase estática.
+  if (ahead === null) {
+    return 'integração LOCAL — nada foi publicado. Rode `git push` para levar ao remoto.';
+  }
+  return `integração LOCAL — nada foi publicado: ${branch} está ${ahead} commit(s) à frente de ${remote}/${branch}. Rode ${pushCmd} para levar ao remoto (ou re-execute o finish com --push).`;
+}
 
-function mergeOutput({ feature, branch, worktreePath, teardown, shedBackup }) {
+/**
+ * CONSTRUTOR ÚNICO da saída de sucesso do `--merge`. As três emissões (worktree
+ * normal, worktree `--keep` e fluxo comum) passam por aqui — era a terceira
+ * cópia, montada à mão no `--keep`, que saía sem `nextStep` nenhum.
+ *
+ * `teardown === null` cobre os dois casos sem desmonte: o `--keep` (worktree
+ * vivo de propósito) e o fluxo comum (não há worktree algum).
+ *
+ * @param {{ feature: string, branch: string, defaultBranch: string,
+ *   publish: ReturnType<typeof publicationState>, worktreePath?: string|null,
+ *   teardown?: object|null, shedBackup?: string|null, kept?: boolean }} args
+ */
+function mergeOutput({ feature, branch, defaultBranch, publish, worktreePath = null, teardown = null, shedBackup = null, kept = false }) {
   return {
     finished: true,
     integrated: true,
     mode: 'merge',
     feature,
     merged: branch,
-    worktreeRemoved: teardown.worktreeRemoved,
-    nextStep: MERGE_NEXT_STEP,
+    into: defaultBranch,
+    ...(kept ? { kept: true } : {}),
+    worktreeRemoved: teardown ? teardown.worktreeRemoved : false,
+    nextStep: mergeNextStep(publish),
+    publish,
     ...(shedBackup ? { shedBackup } : {}),
-    ...teardownExtras(teardown, worktreePath, branch, true),
+    ...(kept
+      ? {
+        // Worktree preserved on purpose: the root's `worktree` registration stays
+        // VALID (it still names a live directory), so nothing to clean up here —
+        // only report where it lives and how to close it later.
+        worktree: { path: worktreePath, branch },
+        hint: `worktree preservado em ${worktreePath} — feche depois com \`morph-spec worktree remove ${feature}\`.`,
+      }
+      : {}),
+    ...(teardown ? teardownExtras(teardown, worktreePath, branch, true) : {}),
   };
 }
 
@@ -856,28 +1173,18 @@ function openPrFor(branch, cwd) {
 }
 
 /**
- * Reclaim the feature's verification stack, if the project has one.
- *
- * Runs from the ROOT rather than the worktree: by the time a finish emits
- * success the worktree may already be gone, and the compose file is versioned
- * so the root's copy is equivalent. Entirely fail-open — no compose, no docker,
- * or a stubborn container are all non-events here.
+ * Reclaim the feature's verification stack (containers, ports, named volumes,
+ * freshness stamp) from the tree that owns it. `--keep-volumes` keeps the
+ * named volumes (e.g. a seeded database) for the next feature. Best-effort by
+ * contract — a stack that refuses to come down must never fail a finish that
+ * already merged, so this never throws.
  */
-function tearDownE2eStack(feature, root) {
+function reclaimStack(feature, { root, worktreePath, options }) {
   try {
-    const config = JSON.parse(
-      readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, '')
-    );
-    const composeFile = resolveComposeFile(root, config);
-    if (!composeFile) return;
-
-    const projectName = composeProjectName(feature);
-    tearDownStack(root, {
-      composeFile,
-      projectName,
-      env: { COMPOSE_PROJECT_NAME: projectName },
-    });
-  } catch { /* fail-open — teardown must never fail a completed finish */ }
+    return tearDownFeatureStack(feature, { root, worktreePath, volumes: !options.keepVolumes });
+  } catch {
+    return { attempted: false, cwd: worktreePath || root, status: 'fail', stampDeleted: false };
+  }
 }
 
 /** Drop a feature from the thin, gitignored root index (never via saveState). */