@polymorphism-tech/morph-spec 8.33.0 → 8.34.2

package/src/commands/project/worktree.js

@@ -13,7 +13,11 @@
  *
  * Subcommands:
  *   morph-spec worktree setup <feature> [--fresh]   — create + materialize state
+ *   morph-spec worktree provision <name> [--base <ref>]  — task-isolation tree
+ *     (branch morph-task/{name}, same infra, NO feature identity) — what the
+ *     WorktreeCreate hook calls for `claude -w` / EnterWorktree / Agent isolation
  *   morph-spec worktree link [--target <path>] [--all]  — (re)link shared infra
+ *   morph-spec worktree remove [<feature>|--target <path>] [--if-clean]  — safe teardown
  *   morph-spec worktree list [--json]  — list active feature worktrees
  *
  * Closing the lifecycle (integrate + teardown) lives in `morph-spec finish`
@@ -32,7 +36,7 @@
 
 import { execSync, execFileSync } from 'child_process';
 import { existsSync, mkdirSync, symlinkSync, readFileSync, writeFileSync, appendFileSync, lstatSync, unlinkSync, rmdirSync, cpSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { join, resolve, dirname, basename } from 'path';
 import chalk from 'chalk';
 import { detectDefaultBranch } from '../../lib/git/default-branch.js';
 import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
@@ -40,29 +44,11 @@ import { triageIgnoredPaths } from '../../lib/worktree/ignored-triage.js';
 // the SAME answer this file does, and hooks can never import from `src/`.
 import { findReparsePoints } from '../../../framework/hooks/shared/reparse-scan.js';
 
-/**
- * The directory new worktrees are created under, relative to the primary root.
- *
- * NO leading dot, deliberately (C1). Jest escapes the `.` when it interpolates
- * an absolute `rootDir` into the `testMatch` glob, so `<root>/.worktrees/...`
- * stops matching and an entire frontend suite reports **0 tests without an
- * error** — the suite "passes" having tested nothing. The dot bought nothing:
- * the directory is gitignored either way.
- */
-export const WORKTREES_DIR = 'worktrees';
-
-/**
- * The pre-C1 directory name. New worktrees never land here, but every reader
- * that resolves worktrees BY CONVENTION must still accept it, so a machine
- * that already had `.worktrees/{f}` keeps working with no manual migration.
- *
- * Readers that go through `git worktree list` (fleet, finish, worktree list)
- * were never affected — git records absolute paths, not this convention.
- */
-export const LEGACY_WORKTREES_DIR = '.worktrees';
-
-/** Both names, new first — the read order for convention-based lookups. */
-export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];
+// The container name lives in lib/worktree/dirs.js (single source, C1
+// 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';
+export { WORKTREES_DIR, LEGACY_WORKTREES_DIR, WORKTREE_DIR_NAMES };
 
 // ── Pure helpers (exported for tests) ──────────────────────────────────────
 
@@ -362,6 +348,43 @@ export function resolvePrimaryRoot(cwd = process.cwd()) {
  * @param {string} worktreePath - Absolute path to the worktree
  * @returns {Promise<{ materialized: boolean, reason?: string }>}
  */
+/**
+ * Guarantee the worktree owns a local `.morph/state.json`, hydrated from its
+ * committed features when there are any, and an EMPTY index otherwise.
+ *
+ * Why the empty index matters: every core hook fail-opens on `stateExists()`,
+ * which is true only with a `state.json` or a feature dir in the tree. A
+ * task-isolation worktree of a project with no committed features (measured
+ * in the sandbox e2e) had neither — so the env-inject hook, the removal guard
+ * and every other guardrail were silently dark inside it. `state.json` is
+ * gitignored and derivable, so an empty one costs nothing and can never dirty
+ * the tree the finish gates read.
+ *
+ * @param {string} worktreePath
+ * @returns {Promise<{ materialized: boolean, reason?: string, seeded?: boolean }>}
+ */
+export async function ensureLocalState(worktreePath) {
+  const result = await materializeState(worktreePath);
+  if (result.materialized) return result;
+  const statePath = join(worktreePath, '.morph', 'state.json');
+  if (existsSync(statePath)) return { ...result, materialized: true };
+  try {
+    const { atomicWriteJson } = await import('../../core/state/state-manager.js');
+    const now = new Date().toISOString();
+    mkdirSync(join(worktreePath, '.morph'), { recursive: true });
+    atomicWriteJson(statePath, {
+      version: '5.0.0',
+      project: { name: basename(worktreePath), type: 'unknown', createdAt: now, updatedAt: now },
+      features: {},
+      threads: {},
+      metadata: { totalFeatures: 0, completedFeatures: 0, totalTimeSpent: 0, lastUpdated: now },
+    });
+    return { materialized: true, seeded: true, reason: result.reason };
+  } catch (err) {
+    return { materialized: false, reason: (err && err.message) || result.reason };
+  }
+}
+
 export async function materializeState(worktreePath) {
   const featuresDir = join(worktreePath, '.morph', 'features');
   if (!existsSync(featuresDir)) {
@@ -490,33 +513,13 @@ export async function runWorktreeSetup(feature, options = {}) {
     setupInfraLinks(worktreePath, cwd);
 
     // Fleet env: allocate this feature's deterministic port block and write the
-    // worktree-local manifest (.morph/worktree.env), excluded from git via the
-    // same common-dir mechanism as the infra links (it must be invisible to the
-    // finish clean-checks). Under `.morph/` on purpose: that prefix is already
-    // shieldable at finish (backed up, never a removal blocker). Fail-open — a
-    // worktree without ports is degraded, never broken.
-    let envBlock = null;
-    try {
-      const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
-        await import('../../lib/worktree/env-allocator.js');
-      const common = execSync('git rev-parse --git-common-dir', { cwd, stdio: 'pipe' }).toString().trim();
-      if (common) {
-        const gitCommonDir = resolve(cwd, common);
-        envBlock = allocateEnvBlock(feature, { gitCommonDir, ...resolveFleetConfig(cwd) });
-        let stack = '';
-        try {
-          const cfg = JSON.parse(readFileSync(join(cwd, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
-          stack = cfg?.project?.stack || '';
-        } catch { /* fail-open — stackless env still carries PORT */ }
-        mkdirSync(join(worktreePath, '.morph'), { recursive: true });
-        writeFileSync(join(worktreePath, '.morph', 'worktree.env'), buildEnvFileContent(feature, envBlock, stack), 'utf8');
-        excludeWorktreePaths(cwd, [join('.morph', 'worktree.env')]);
-      }
-    } catch { envBlock = null; /* fail-open */ }
+    // worktree-local manifest (.morph/worktree.env). Fail-open — a worktree
+    // without ports is degraded, never broken.
+    const envBlock = await allocateWorktreeEnv(worktreePath, cwd, feature);
 
     // Materialize a local, real state.json in the worktree (self-heal from the
     // committed feature.json files) so hooks work from the very first session.
-    const materialized = await materializeState(worktreePath);
+    const materialized = await ensureLocalState(worktreePath);
 
     // Fleet handoff: the fresh instance that opens this worktree reads
     // handoff.md before anything else (SessionStart hook points at it). The doc
@@ -578,6 +581,109 @@ export async function worktreeSetupCommand(feature, options = {}) {
   process.exit(exitCode);
 }
 
+// ── provision (task isolation — a worktree that is NOT a feature) ──────────
+
+/**
+ * Branch name for a task-isolation worktree: `morph-task/<name>`. A separate
+ * namespace from `morph/<feature>` on purpose — `worktree list`, `fleet`,
+ * `finish` and the SessionStart hook all read `morph/<f>` as "this IS feature
+ * f", and a scratch tree named after a feature must never impersonate it.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function buildTaskBranchName(name) {
+  return `morph-task/${name}`;
+}
+
+/**
+ * Non-exiting core of `worktree provision` — the tree `claude -w`,
+ * `EnterWorktree` and `Agent isolation:"worktree"` ask for when the name is
+ * not a feature. Everything `setup` gives a feature worktree EXCEPT the
+ * feature identity: it lands under `<primary root>/worktrees/<name>` (never
+ * nested under a secondary worktree, whatever the cwd), on `morph-task/<name>`
+ * off the default branch (or `--base`), with the infra junctions, a git-
+ * invisible `.morph/worktree.env` keyed `task/<name>`, and a materialized
+ * local state.json. No feature registration, no handoff.
+ *
+ * Exit codes mirror `setup`: 0 created (or fail-open), 1 refused (bad name),
+ * 2 already exists at this exact path.
+ *
+ * @param {string} name
+ * @param {{ base?: string, cwd?: string }} [options]
+ * @returns {Promise<{ ok: boolean, exitCode: 0|1|2, created: boolean, alreadyExists?: boolean, path?: string, branch?: string, branchedFrom?: string|null, kind?: 'task-isolation', name: string, env?: object, error?: string }>}
+ */
+export async function runWorktreeProvision(name, options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  if (!isValidFeatureName(name)) {
+    return { ok: false, exitCode: 1, created: false, error: 'invalid-name', name };
+  }
+  if (!isGitRepo(cwd)) {
+    return { ok: true, exitCode: 0, created: false, error: 'not-a-git-repo', name };
+  }
+
+  // Always the PRIMARY root: a provision issued from inside a feature worktree
+  // must not nest a worktree under it — that tree would be invisible to the
+  // fleet and to doctor, which enumerate `<root>/worktrees/`.
+  const root = resolvePrimaryRoot(cwd);
+  const branch = buildTaskBranchName(name);
+  const worktreePath = buildWorktreePath(name, root);
+
+  if (worktreeExists(worktreePath, root)) {
+    return { ok: true, exitCode: 2, created: false, alreadyExists: true, path: worktreePath, branch, kind: 'task-isolation', name };
+  }
+
+  let branchedFrom = null;
+  try {
+    if (!branchExists(branch, root)) {
+      const base = options.base || detectDefaultBranch(root);
+      if (base) {
+        execFileSync('git', ['branch', branch, base], { cwd: root, stdio: 'pipe' });
+        branchedFrom = base;
+      } else {
+        execFileSync('git', ['branch', branch], { cwd: root, stdio: 'pipe' });
+      }
+    }
+
+    const parentDir = join(root, WORKTREES_DIR);
+    if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+
+    execFileSync('git', ['worktree', 'add', worktreePath, branch], { cwd: root, stdio: 'pipe' });
+
+    setupInfraLinks(worktreePath, root);
+    const envBlock = await allocateWorktreeEnv(worktreePath, root, `task/${name}`);
+    const materialized = await ensureLocalState(worktreePath);
+
+    return {
+      ok: true,
+      exitCode: 0,
+      created: true,
+      path: worktreePath,
+      branch,
+      branchedFrom,
+      kind: 'task-isolation',
+      name,
+      materialized: materialized.materialized,
+      ...(envBlock ? { env: { base: envBlock.base, range: envBlock.range } } : {}),
+    };
+  } catch (err) {
+    return { ok: true, exitCode: 0, created: false, error: (err.message || 'unknown').slice(0, 200), name };
+  }
+}
+
+/**
+ * `morph-spec worktree provision <name> [--base <ref>]` — thin wrapper around
+ * `runWorktreeProvision`, same JSON-and-exit contract as `setup`.
+ * @param {string} name
+ * @param {{ base?: string, cwd?: string }} [options]
+ */
+export async function worktreeProvisionCommand(name, options = {}) {
+  const { ok, exitCode, ...result } = await runWorktreeProvision(name, options);
+  console.log(JSON.stringify(result));
+  process.exit(exitCode);
+}
+
 /**
  * Command handler for `morph-spec worktree link [--target <path>] [--all]`.
  *
@@ -588,7 +694,7 @@ export async function worktreeSetupCommand(feature, options = {}) {
  *
  * @param {{ target?: string, all?: boolean, cwd?: string }} [options]
  */
-export function worktreeLinkCommand(options = {}) {
+export async function worktreeLinkCommand(options = {}) {
   const cwdArg = options.cwd || process.cwd();
   const root = resolvePrimaryRoot(cwdArg);
   const target = resolve(options.target || options.cwd || process.cwd()).replace(/\\/g, '/');
@@ -627,10 +733,79 @@ export function worktreeLinkCommand(options = {}) {
     }
   }
 
-  console.log(JSON.stringify({ linked, skipped, root, target }));
+  // `link --all` is the documented repair for a worktree missing its infra —
+  // that includes a `.morph/worktree.env` written by an older layout. The
+  // allocation is idempotent (same key → same block), so regenerating the
+  // manifest never moves a worktree's ports; it only adds the keys it lacks.
+  let env = null;
+  if (options.all) {
+    const key = envKeyForWorktree(target, root);
+    const block = key ? await allocateWorktreeEnv(target, root, key) : null;
+    if (block) env = { key, base: block.base, range: block.range };
+  }
+
+  console.log(JSON.stringify({ linked, skipped, root, target, ...(env ? { env } : {}) }));
   process.exit(0);
 }
 
+/**
+ * The env-registry key of a worktree, derived from its branch: `morph/<f>` →
+ * `<f>` (feature), `morph-task/<n>` → `task/<n>` (task isolation). `null` for
+ * a branch morph does not own — no block is allocated for those.
+ *
+ * @param {string} worktreePath
+ * @param {string} root
+ * @returns {string|null}
+ */
+export function envKeyForWorktree(worktreePath, root) {
+  const norm = resolve(worktreePath).replace(/\\/g, '/');
+  const entry = parseWorktreeList(root).find((e) => e.path === norm);
+  const branch = entry?.branch?.replace(/^refs\/heads\//, '') ?? null;
+  if (!branch) return null;
+  const feature = branch.match(/^morph\/(.+)$/)?.[1];
+  if (feature) return feature;
+  const task = branch.match(/^morph-task\/(.+)$/)?.[1];
+  return task ? `task/${task}` : null;
+}
+
+/**
+ * Allocate (idempotently) the port block for `envKey` and write the worktree's
+ * `.morph/worktree.env`, excluded from git via the same common-dir mechanism as
+ * the infra links (it must be invisible to the finish clean-checks). Under
+ * `.morph/` on purpose: that prefix is already shieldable at finish (backed up,
+ * never a removal blocker). Fail-open: returns `null` when no block could be
+ * written — a worktree without ports is degraded, never broken.
+ *
+ * Shared by `setup` (feature key), `provision` (task key) and `link --all`
+ * (regeneration), so the manifest has exactly one writer.
+ *
+ * @param {string} worktreePath
+ * @param {string} root - primary root
+ * @param {string} envKey - `<feature>` or `task/<name>`
+ * @returns {Promise<{ index: number, base: number, range: [number, number] }|null>}
+ */
+export async function allocateWorktreeEnv(worktreePath, root, envKey) {
+  try {
+    const { allocateEnvBlock, resolveFleetConfig, buildEnvFileContent } =
+      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 = '';
+    try {
+      const cfg = JSON.parse(readFileSync(join(root, '.morph', 'config', 'config.json'), 'utf8').replace(/^/, ''));
+      stack = cfg?.project?.stack || '';
+    } catch { /* fail-open — stackless env still carries PORT */ }
+    mkdirSync(join(worktreePath, '.morph'), { recursive: true });
+    writeFileSync(join(worktreePath, '.morph', 'worktree.env'), buildEnvFileContent(envKey, block, stack), 'utf8');
+    excludeWorktreePaths(root, [join('.morph', 'worktree.env')]);
+    return block;
+  } catch {
+    return null;
+  }
+}
+
 // ── finish / list shared helpers ────────────────────────────────────────────
 
 /**
@@ -1338,7 +1513,7 @@ export function cwdIsInsideWorktree(cwd, worktreePath) {
  * closing a feature is still `morph-spec finish`.
  *
  * @param {string|undefined} featureArg
- * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, cwd?: string }} [options]
+ * @param {{ target?: string, discardIgnored?: boolean, deleteBranch?: boolean, ifClean?: boolean, cwd?: string }} [options]
  */
 export async function worktreeRemoveCommand(featureArg, options = {}) {
   const cwdArg = options.cwd || process.cwd();
@@ -1398,9 +1573,47 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
       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);
   }
 
+  // `--if-clean` — the WorktreeRemove hook's contract: Claude Code fires it
+  // when it believes the tree is disposable, but "disposable" is the user's
+  // call, not the harness's. Any uncommitted or untracked file refuses the
+  // removal BEFORE the junctions are touched, so a refusal leaves the tree
+  // exactly as it was (no rollback needed, nothing to relink). The infra
+  // links and the env manifest are excluded from git, so they never count.
+  if (options.ifClean) {
+    let status;
+    try {
+      status = execFileSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd: worktreePath, stdio: 'pipe' }).toString();
+    } catch {
+      emit({ 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 = 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),
+        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);
+    }
+  }
+
+  // The env-registry key this tree allocated under: `<f>` for morph/<f>,
+  // `task/<n>` for morph-task/<n>. Read BEFORE the teardown (the entry is gone
+  // from `git worktree list` afterwards). The old `'worktree'` placeholder
+  // meant every --target removal released a slot nobody held and leaked the
+  // one the tree actually used.
+  const envKey = envKeyForWorktree(worktreePath, root);
+
+  // The tree's compose stack goes down BEFORE the tree: a running bind-mounted
+  // container holds the directory (Windows) and turns a clean removal into a
+  // removalFailure. Volumes survive — removing a worktree is not closing the
+  // feature, and a re-`setup` should find its seeded database intact.
+  let e2e = null;
+  try {
+    const { tearDownFeatureStack } = await import('../../lib/e2e/stack-teardown.js');
+    e2e = tearDownFeatureStack(envKey || feature || basename(worktreePath), { root, worktreePath, volumes: false });
+  } catch { e2e = null; /* fail-open */ }
+
   const teardown = await teardownWorktree(worktreePath, {
     root,
-    feature: feature || 'worktree',
+    feature: feature || envKey || 'worktree',
     branch,
     options: { discardIgnored: options.discardIgnored === true },
     // Removing a worktree is not closing a feature: the branch is the work, and
@@ -1421,6 +1634,7 @@ export async function worktreeRemoveCommand(featureArg, options = {}) {
   // 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 (e2e?.attempted) out.e2e = { status: e2e.status, cwd: e2e.cwd, volumes: false };
   if (teardown.worktreeRemoved) {
     if (teardown.discarded.length) out.discardedIgnored = teardown.discarded;
     // Broken out of `discardedIgnored` on purpose: "deleted" and "deleted

package/src/commands/state/delete.js

@@ -4,6 +4,7 @@ import { join, resolve, sep } from 'path';
 import { execSync } from 'child_process';
 import { isValidFeatureName, cwdIsInsideWorktree, teardownWorktree, resolvePrimaryRoot } from '../project/worktree.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
+import { tearDownFeatureStack } from '../../lib/e2e/stack-teardown.js';
 
 /**
  * `morph-spec delete <feature>` — remove a feature. Hard by default (folder is
@@ -144,6 +145,13 @@ export async function deleteCommand(featureName, options = {}) {
       // worktree actually came down. A refusal here must leave EVERYTHING
       // untouched, same contract as `worktree remove`.
       const root = resolvePrimaryRoot(cwd);
+      // The feature's verification stack (containers, ports, volumes, stamp)
+      // comes down BEFORE its worktree: the compose file and the bind mount
+      // live there, and a deleted feature has nothing to keep a volume for.
+      // Fail-open by contract — a stubborn container never blocks the delete.
+      try {
+        tearDownFeatureStack(featureName, { root, worktreePath: owner.tree, volumes: true });
+      } catch { /* fail-open */ }
       const teardown = await teardownWorktree(owner.tree, {
         root,
         feature: featureName,

package/src/commands/state/finish.js

@@ -15,11 +15,7 @@ import {
 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,
-  resolveComposeFile,
-  tearDownStack,
-} from '../../../framework/hooks/shared/e2e-check.js';
+import { tearDownFeatureStack } from '../../lib/e2e/stack-teardown.js';
 import { runArchive } from './archive.js';
 
 /** workType → conventional-commit type. `hotfix` IS a fix; anything else is a chore. */
@@ -101,12 +97,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 +116,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));
   };
@@ -496,9 +490,13 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
       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, worktreePath, teardown, shedBackup }), ...ucNote, e2e });
     process.exit(0);
   }
 
@@ -526,8 +524,9 @@ async function integrateMerge({ emit, root, feature, expectedBranch, defaultBran
     process.exit(1);
   }
   tryGit(['branch', '-d', expectedBranch], root);
+  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({ finished: true, integrated: true, mode: 'merge', feature, merged: expectedBranch, into: defaultBranch, worktreeRemoved: false, nextStep: MERGE_NEXT_STEP, ...ucNote, e2e });
   process.exit(0);
 }
 
@@ -571,6 +570,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 +611,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) }
       : {
@@ -856,28 +861,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). */