@polymorphism-tech/morph-spec 8.29.0 → 8.32.0

package/src/lib/worktree/fleet-scanner.js

@@ -28,6 +28,8 @@ import {
   pendingGatesFrom,
 } from '../../../framework/hooks/shared/state-reader.js';
 import { listClaims } from '../../../framework/hooks/shared/claim-registry.js';
+import { buildPrIndex } from '../git/pr-index.js';
+import { pendingPrFeatures } from '../git/pending-prs.js';
 
 function countFrom(raw) {
   const data = JSON.parse(raw);
@@ -133,32 +135,18 @@ function remoteHeads(root) {
 /**
  * One `gh pr list` for the whole scan → Map<headRefName, {number, state}>.
  *
- * Gated on the origin URL actually pointing at github.com — `gh` against any
- * other host is a guaranteed error, and paying its start-up cost to learn that
- * on every `fleet` call is pure latency. Fail-open: no `gh`, not authenticated,
- * or a timeout all yield `null`, which just leaves the PR half of the column
- * empty while `pushed` still works.
+ * Delegates to the shared `buildPrIndex` so `fleet`, `branch prune` and
+ * `doctor --worktrees` cannot answer "does this branch have a PR" differently
+ * — the destructive two read it to decide what NOT to delete.
+ *
+ * Fail-open: `null` (no `gh`, not authenticated, not GitHub, timeout) just
+ * leaves the PR half of the column empty while `pushed` still works.
  *
  * @param {string} root
  * @returns {Map<string,{number:number,state:string}>|null}
  */
 function remotePrs(root) {
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
-    if (!/github\.com/i.test(url)) return null;
-    const out = execFileSync('gh', ['pr', 'list', '--state', 'all', '--limit', '100', '--json', 'number,state,headRefName'], {
-      cwd: root, stdio: 'pipe', timeout: 8000,
-    }).toString();
-    const map = new Map();
-    for (const pr of JSON.parse(out)) {
-      // First wins: `gh` lists newest-first, so an OPEN PR shadows an older
-      // closed one on the same branch.
-      if (pr?.headRefName && !map.has(pr.headRefName)) map.set(pr.headRefName, { number: pr.number, state: pr.state });
-    }
-    return map;
-  } catch {
-    return null;
-  }
+  return buildPrIndex(root, { limit: 100 });
 }
 
 /**
@@ -297,5 +285,47 @@ export function scanFleet(cwd = process.cwd()) {
     }
   } catch { /* fail-open */ }
 
+  // Features that exist ONLY as an open PR: no registered worktree, no
+  // `.morph/features/*` folder in this tree. This is exactly what
+  // `finish --pr` leaves behind — and without this pass `fleet` would say
+  // "nothing in flight" about work that is under review on GitHub.
+  //
+  // `prs` was attempted above whenever `heads` is truthy (`remotePrs` runs —
+  // see `const prs = heads ? remotePrs(root) : null;` — regardless of
+  // whether that `gh` call itself succeeded). Gate on the SAME condition
+  // `remotePrs` used, not on `prs !== null`: `remotePrs`/`buildPrIndex` can
+  // fail (timeout, not authenticated, malformed JSON) and legitimately
+  // return `null` even after really invoking `gh`. Passing that `null`
+  // through lets `pendingPrFeatures` short-circuit on its own documented
+  // contract (explicit `null` index = known unknown, never a fallback build)
+  // instead of retrying `gh` a second time in the same scan. Only when
+  // `remotePrs` was never attempted at all (`heads` falsy) does
+  // `pendingPrFeatures` get no index, so it makes the first (and only) `gh`
+  // call itself.
+  try {
+    const seen = new Set(entries.map((e) => e.feature));
+    const pendOpts = heads ? { index: prs } : {};
+    for (const p of pendingPrFeatures(root, pendOpts) || []) {
+      if (seen.has(p.feature)) continue;
+      entries.push({
+        feature: p.feature,
+        workType: null,
+        phase: 'aguardando-merge',
+        status: 'in_progress',
+        pendingGates: [],
+        location: 'pr-pending',
+        path: null,
+        branch: p.branch,
+        tasks: null,
+        env: null,
+        handoff: { exists: false, generatedAt: null },
+        lastCommit: null,
+        dirty: null,
+        remote: { branch: p.branch, pushed: true, sha: null, pr: { number: p.number, state: p.state } },
+        claim: null,
+      });
+    }
+  } catch { /* fail-open — a pendency not listed must never take down the scan */ }
+
   return { root, entries };
 }

package/src/lib/worktree/ignored-triage.js

@@ -0,0 +1,197 @@
+/**
+ * ignored-triage.js — decide, per gitignored leftover, whether removing a
+ * worktree would DESTROY something or merely delete a copy.
+ *
+ * WHY THIS EXISTS: `git worktree remove` deletes gitignored files outright and
+ * the clean-check that gates it (`git status --porcelain`) omits them by
+ * design, so a user's `.env` dies silently while the command reports success.
+ * The first fix for that refused the removal whenever ANY unrecognised
+ * gitignored path was present — correct, but blind: in the observed session a
+ * worktree carried `.env` and `.env.e2e` that were BYTE-IDENTICAL to the
+ * primary root's, alongside a `keys/key-*.xml` that existed nowhere else. The
+ * refusal treated them alike, and the only escape it offered
+ * (`--discard-ignored`) destroyed the unique one together with the replicas.
+ *
+ * The triage below replaces "recognised vs not" with the question that actually
+ * decides whether bytes are lost:
+ *
+ *   REPLICABLE — the primary root has the same relative path with identical
+ *                content. Deleting the worktree's copy loses nothing; the
+ *                original stays where it always was.
+ *   DISPOSABLE — a well-known build artifact (`bin/`, `obj/`, `node_modules/`,
+ *                `__pycache__/`, `test-results/`, `.auth/`, `*.tsbuildinfo`).
+ *                Reproducible from source, which is a STRONGER guarantee than
+ *                backed up.
+ *   EXCLUSIVE  — everything else: no counterpart in the root, or a counterpart
+ *                whose content differs. These are the only bytes at stake, and
+ *                the caller copies them to `finish-backup` before proceeding.
+ *
+ * Fail-CLOSED on every uncertainty: an unreadable file, a hash that cannot be
+ * computed, a directory too large to compare, a counterpart that is a link
+ * rather than a real file — all classify as EXCLUSIVE. Being wrong in that
+ * direction costs a backup copy; being wrong the other way costs the file.
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Well-known, regenerable build artifacts. Deliberately narrow — do NOT add
+ * speculative patterns (`dist/`, `.next/`) that a project might legitimately
+ * hand-edit; anything unlisted still reaches the EXCLUSIVE bucket, where it is
+ * backed up rather than assumed disposable.
+ *
+ * `.auth/` (Playwright storage state) belongs here for a reason worth stating:
+ * it holds a captured session, so it LOOKS like precious local state — but it
+ * is regenerated by the auth setup project on the next run, and it expires on
+ * its own. Keeping it out of the backup avoids copying credentials around.
+ */
+const DISPOSABLE_DIR_NAMES = new Set([
+  'bin', 'obj', 'node_modules', '__pycache__', 'test-results', '.auth',
+]);
+const DISPOSABLE_FILE_RE = /\.tsbuildinfo$/;
+
+/**
+ * Comparing a directory recursively is only worth doing while it stays small:
+ * the point is to spare `.env`-sized replicas from a needless refusal, not to
+ * checksum a data set. Past either cap the answer becomes EXCLUSIVE (the safe
+ * direction), and the caller backs it up.
+ */
+const REPLICABLE_MAX_FILES = 500;
+const REPLICABLE_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * @param {string} p - forward-slash relative path
+ * @returns {boolean}
+ */
+export function isDisposableBuildArtifact(p) {
+  if (DISPOSABLE_FILE_RE.test(p)) return true;
+  return p.split('/').filter(Boolean).some((seg) => DISPOSABLE_DIR_NAMES.has(seg));
+}
+
+function sha256OfFile(path) {
+  try {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Real file (not a link, not a directory)? A reparse point must never be read
+ * THROUGH — following one is the exact failure mode the whole teardown path
+ * exists to prevent — so a link on either side makes the pair incomparable.
+ */
+function isRealFile(path) {
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isRealDir(path) {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every real file under `dir`, relative to it. Returns null when the walk hits
+ * a link, an unreadable entry, or either cap — "cannot enumerate" and "too big
+ * to compare" both mean "do not claim this is replicable".
+ */
+function walkFiles(dir, budget) {
+  const out = [];
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(join(dir, rel), { withFileTypes: true });
+    } catch {
+      return null;
+    }
+    for (const e of entries) {
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      const childAbs = join(dir, childRel);
+      if (e.isSymbolicLink()) return null; // never compare through a link
+      if (e.isDirectory()) { stack.push(childRel); continue; }
+      if (!e.isFile()) return null; // socket/fifo/unknown — incomparable
+      let size;
+      try { size = lstatSync(childAbs).size; } catch { return null; }
+      budget.files += 1;
+      budget.bytes += size;
+      if (budget.files > REPLICABLE_MAX_FILES || budget.bytes > REPLICABLE_MAX_BYTES) return null;
+      out.push(childRel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Does `root/rel` hold exactly the same content as `worktree/rel`?
+ *
+ * Files compare by SHA-256; directories compare by having the SAME set of
+ * files, each with an identical hash — a root copy that is merely a SUPERSET
+ * is not a replica of the worktree's, because the worktree's own extra files
+ * would still be lost.
+ *
+ * @returns {boolean} false on ANY uncertainty
+ */
+export function isReplicatedInRoot(worktreePath, rootPath, rel) {
+  const src = join(worktreePath, rel);
+  const dst = join(rootPath, rel);
+  if (!existsSync(src) || !existsSync(dst)) return false;
+
+  if (isRealFile(src)) {
+    if (!isRealFile(dst)) return false;
+    const a = sha256OfFile(src);
+    const b = sha256OfFile(dst);
+    return a !== null && a === b;
+  }
+
+  if (isRealDir(src)) {
+    if (!isRealDir(dst)) return false;
+    const srcFiles = walkFiles(src, { files: 0, bytes: 0 });
+    if (srcFiles === null) return false;
+    const dstFiles = walkFiles(dst, { files: 0, bytes: 0 });
+    if (dstFiles === null) return false;
+    if (srcFiles.length !== dstFiles.length) return false;
+    const dstSet = new Set(dstFiles);
+    for (const f of srcFiles) {
+      if (!dstSet.has(f)) return false;
+      const a = sha256OfFile(join(src, f));
+      const b = sha256OfFile(join(dst, f));
+      if (a === null || a !== b) return false;
+    }
+    return true;
+  }
+
+  return false; // a link, or something that is neither — incomparable
+}
+
+/**
+ * Split gitignored worktree paths into the three buckets above.
+ *
+ * ORDER IS DELIBERATE: disposable is checked FIRST, so a `bin/` that happens to
+ * be byte-identical to the root's is discarded rather than hashed, and a
+ * `node_modules` never enters the comparison budget at all.
+ *
+ * @param {{ worktreePath: string, rootPath: string, paths: string[] }} args
+ * @returns {{ replicable: string[], disposable: string[], exclusive: string[] }}
+ */
+export function triageIgnoredPaths({ worktreePath, rootPath, paths }) {
+  const replicable = [];
+  const disposable = [];
+  const exclusive = [];
+  for (const rel of paths) {
+    if (isDisposableBuildArtifact(rel)) { disposable.push(rel); continue; }
+    if (isReplicatedInRoot(worktreePath, rootPath, rel)) { replicable.push(rel); continue; }
+    exclusive.push(rel);
+  }
+  return { replicable, disposable, exclusive };
+}

package/src/lib/worktree/worktree-audit.js

@@ -15,14 +15,16 @@
  *
  * Read-only and fail-open: anything unresolvable yields no issue rather than a
  * throw. A diagnostic that invents problems is worse than one that misses some.
- * The one mutation lives in `pruneWorktrees`, and it is deliberately the safest
- * possible: `git worktree prune` drops ADMIN RECORDS for directories that are
- * already gone. Deleting a directory that still exists stays a human decision —
- * the same PROVE-or-DECLINE discipline `teardownWorktree` follows.
+ * The mutations all live in `pruneWorktrees`, and each is deliberately the
+ * safest possible: `git worktree prune` drops ADMIN RECORDS for directories
+ * that are already gone, and the empty-residue sweep removes only directories
+ * with zero entries inside — nothing that can hold work. Deleting a directory
+ * that still HOLDS something stays a human decision, the same PROVE-or-DECLINE
+ * discipline `teardownWorktree` follows.
  */
 
 import { execFileSync } from 'child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, rmdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
 import {
   isGitRepo,
@@ -31,6 +33,9 @@ import {
   WORKTREE_DIR_NAMES,
   clearDanglingWorktreeRegistration,
 } from '../../commands/project/worktree.js';
+import { detectDefaultBranch } from '../git/default-branch.js';
+import { buildPrIndex } from '../git/pr-index.js';
+import { classifyBranch, commitsAhead, resolveBaseRef } from '../git/branch-classifier.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
 
@@ -66,6 +71,54 @@ function featureCommittedOnBranch(root, feature) {
   }
 }
 
+/**
+ * Does this worktree's branch still hold work that is NOT in the default
+ * branch, or an OPEN PR?
+ *
+ * This is the predicate that separates "an orphan directory to clean up" from
+ * "the only copy of somebody's work". Two independent pieces of evidence, and
+ * ANY of them is enough to protect the worktree:
+ *
+ *   1. commits the default branch does not have (`git rev-list base..branch`)
+ *   2. an OPEN pull request on that branch
+ *
+ * Fail-CLOSED, and that asymmetry is the whole design: whenever the answer
+ * cannot be established — no default branch, no origin, git errored — the
+ * worktree counts as UNINTEGRATED. The cost of being wrong that way is a
+ * diagnostic that stays quiet; the cost of the opposite is a suggestion to
+ * delete work that exists nowhere else.
+ *
+ * A squash-merged branch legitimately reports commits ahead, so the tree
+ * comparison (`branch-classifier.js`) is consulted for the same reason
+ * `branch prune` needs it — the two must not disagree about "is this in".
+ *
+ * @returns {{ unintegrated: boolean, evidence: string, pr: number|null }}
+ */
+function unintegratedWork(root, branchRef, prIndex) {
+  const branch = (branchRef || '').replace(/^refs\/heads\//, '');
+  if (!branch) return { unintegrated: true, evidence: 'não foi possível resolver a branch do worktree', pr: null };
+
+  const pr = prIndex?.get(branch) ?? null;
+  if (pr?.state === 'OPEN') return { unintegrated: true, evidence: `PR #${pr.number} OPEN`, pr: pr.number };
+
+  const defaultBranch = detectDefaultBranch(root);
+  const baseRef = resolveBaseRef(defaultBranch, root);
+  if (!baseRef) return { unintegrated: true, evidence: 'sem branch default resolvível para comparar', pr: null };
+
+  const ahead = commitsAhead(baseRef, branch, root);
+  if (ahead === null) return { unintegrated: true, evidence: `não foi possível comparar com ${baseRef}`, pr: null };
+  if (ahead === 0) return { unintegrated: false, evidence: `nenhum commit fora de ${baseRef}`, pr: pr?.number ?? null };
+
+  // Commits ahead, but the work may still be IN: a squash-merge leaves exactly
+  // that shape. Reuse the classifier so `doctor` and `branch prune` cannot
+  // reach opposite conclusions about the same branch.
+  const verdict = classifyBranch({ name: branch, sha: '', current: false, worktreePath: null }, { baseRef, cwd: root, pr });
+  if (verdict.kind === 'merged-ancestral' || verdict.kind === 'merged-squash') {
+    return { unintegrated: false, evidence: verdict.reason, pr: pr?.number ?? null };
+  }
+  return { unintegrated: true, evidence: `${ahead} commit(s) fora de ${baseRef}`, pr: pr?.number ?? null };
+}
+
 /**
  * Every feature's `worktree` registration in the primary root — the OTHER
  * direction from `knownFeatures`/`dirsOnDisk`: not "does git/disk know about
@@ -96,6 +149,22 @@ function featureRegistrations(root) {
   return out;
 }
 
+/**
+ * Is this directory literally empty — zero entries, dotfiles included?
+ *
+ * The whole point of the distinction: an empty residue holds nothing that can
+ * be lost, so it can be removed without a human looking at it. Anything else —
+ * including a directory we cannot read — is reported as NON-empty, because the
+ * safe answer to "might there be work in here?" is yes.
+ */
+function isEmptyDir(path) {
+  try {
+    return readdirSync(path).length === 0;
+  } catch {
+    return false; // unreadable → treat as occupied
+  }
+}
+
 /** Directories physically present under either worktree root. */
 function dirsOnDisk(root) {
   const found = [];
@@ -106,7 +175,9 @@ function dirsOnDisk(root) {
       for (const name of readdirSync(base)) {
         const full = join(base, name);
         try {
-          if (statSync(full).isDirectory()) found.push({ name, path: norm(full), container: dirName });
+          if (statSync(full).isDirectory()) {
+            found.push({ name, path: norm(full), container: dirName, empty: isEmptyDir(full) });
+          }
         } catch { /* unreadable entry — skip */ }
       }
     } catch { /* fail-open */ }
@@ -125,7 +196,13 @@ function dirsOnDisk(root) {
  *   • unregistered-dir          — a directory under worktrees/ git never
  *                                 registered
  *   • no-feature                — a `morph/{f}` worktree for a feature morph
- *                                 does not know
+ *                                 does not know AND whose branch carries
+ *                                 nothing that is not already integrated
+ *   • unintegrated-work (info)  — the same shape, except the branch still holds
+ *                                 commits the default does not, or an OPEN PR.
+ *                                 Reported so the reader knows why no removal
+ *                                 is suggested — this worktree may be the ONLY
+ *                                 copy of the work
  *   • dangling-registration     — a feature's ROOT feature.json still points
  *                                 at a `worktree.path` that no longer exists
  *                                 (the symmetric OTHER direction from
@@ -144,6 +221,11 @@ export function auditWorktrees(cwd = process.cwd()) {
   const rootNorm = norm(root);
   const issues = [];
 
+  // ONE `gh pr list` for the whole audit — null means UNKNOWN (no gh, not
+  // GitHub, not authenticated), never "no PRs"; `unintegratedWork` treats the
+  // two differently on purpose.
+  const prIndex = buildPrIndex(root);
+
   const registered = parseWorktreeList(root);
   const registeredPaths = new Set();
   const features = knownFeatures(root);
@@ -169,27 +251,65 @@ export function auditWorktrees(cwd = process.cwd()) {
       // a worktree the user keeps elsewhere is none of morph's business.
       const inContainer = WORKTREE_DIR_NAMES.some((d) => path.startsWith(`${rootNorm}/${d}/`));
       if (inContainer) {
-        issues.push({
-          type: 'non-morph-branch',
-          path,
-          detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga`,
-          // NEVER raw `git worktree remove` here: it follows the infra junctions
-          // out and empties the primary root's .claude/ and .morph/framework/.
-          // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
-          // --target precisely for worktrees like this one, with no feature.
-          fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
-        });
+        // Same hazard as `no-feature` below, and it needs the same guard:
+        // "invisible to fleet" says nothing about whether the WORK is safe
+        // elsewhere. A worktree on a `feat/*` branch with an open PR is the
+        // most normal thing in the world, and suggesting its removal is a
+        // suggestion to destroy the only copy.
+        const work = unintegratedWork(root, entry.branch, prIndex);
+        issues.push(work.unintegrated
+          ? {
+            type: 'unintegrated-work',
+            severity: 'info',
+            path,
+            detail: `${path} está em ${entry.branch || 'HEAD destacado'} (o \`fleet\` não o enxerga) e carrega trabalho NÃO integrado (${work.evidence})`,
+            fix: work.pr
+              ? `nada a fazer enquanto o PR #${work.pr} estiver aberto`
+              : `integre a branch antes de remover o worktree — ele é o único exemplar`,
+          }
+          : {
+            type: 'non-morph-branch',
+            path,
+            detail: `${path} está em ${entry.branch || 'HEAD destacado'}, não numa branch morph/* — o \`fleet\` não o enxerga (e não há trabalho pendente: ${work.evidence})`,
+            // NEVER raw `git worktree remove` here: it follows the infra junctions
+            // out and empties the primary root's .claude/ and .morph/framework/.
+            // `worktree remove` drops them first (PROVE-or-DECLINE) and takes
+            // --target precisely for worktrees like this one, with no feature.
+            fix: `morph-spec worktree remove --target "${path}"  (se já não serve)`,
+          });
       }
       continue;
     }
 
     if (!features.has(feature) && !featureCommittedOnBranch(root, feature)) {
-      issues.push({
-        type: 'no-feature',
-        path,
-        detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch)`,
-        fix: `morph-spec worktree remove --target "${path}"`,
-      });
+      // "sem feature conhecida" is a bookkeeping fact, NOT a verdict on the
+      // work: a `finish` that archived the feature leaves exactly this shape,
+      // and so does a worktree whose PR is still open. In the observed session
+      // this branch recommended `worktree remove --target` for a worktree
+      // holding the ONLY copy of an open PR with 12 tasks and a 9.5 at Gate 3.
+      // So the diagnosis now depends on whether the WORK is integrated, and the
+      // suggestion to destroy appears only when it provably is.
+      const work = unintegratedWork(root, entry.branch, prIndex);
+      if (work.unintegrated) {
+        issues.push({
+          type: 'unintegrated-work',
+          severity: 'info',
+          path,
+          feature,
+          detail: `worktree com trabalho NÃO integrado (${work.evidence}) — a feature foi arquivada, o trabalho não`,
+          fix: work.pr
+            ? `nada a fazer enquanto o PR #${work.pr} estiver aberto; depois de mergeado, \`morph-spec worktree remove --target "${path}"\``
+            : `integre a branch (\`morph-spec finish\` ou um PR) antes de remover o worktree — ele é o único exemplar`,
+        });
+      } else {
+        issues.push({
+          type: 'no-feature',
+          path,
+          feature,
+          detail: `worktree de "${feature}" sem feature conhecida (nem em .morph/features/, nem na branch) e sem trabalho pendente (${work.evidence})`,
+          fix: `morph-spec worktree remove --target "${path}"`,
+        });
+      }
     }
   }
 
@@ -198,8 +318,16 @@ export function auditWorktrees(cwd = process.cwd()) {
     issues.push({
       type: 'unregistered-dir',
       path: d.path,
-      detail: `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
-      fix: `apague o diretório à mão depois de conferir que nada importante ficou nele`,
+      empty: d.empty,
+      detail: d.empty
+        ? `${d.container}/${d.name} existe no disco, está VAZIO e o git não o registra — resíduo de um finish anterior`
+        : `${d.container}/${d.name} existe no disco mas o git não o registra — resíduo de um finish anterior`,
+      // An empty folder has nothing to lose, so it gets the automatic repair.
+      // One with content keeps the manual chore: there may be work in there,
+      // and the whole PROVE-or-DECLINE discipline exists for exactly that.
+      fix: d.empty
+        ? `morph-spec doctor --worktrees --prune`
+        : `apague o diretório à mão depois de conferir que nada importante ficou nele`,
     });
   }
 
@@ -232,24 +360,59 @@ export function auditWorktrees(cwd = process.cwd()) {
 }
 
 /**
- * Drop git's admin records for worktrees whose directory is already gone, AND
- * clear any feature's `worktree` registration that names one of those same
- * gone directories.
+ * Remove the EMPTY directories under `worktrees/`/`.worktrees/` that git does
+ * not register — the residue a finish leaves behind.
+ *
+ * "Empty" is the whole licence to act: a folder with zero entries cannot be
+ * hiding uncommitted work, so asking a human about it is pure ceremony, and
+ * the audit that only warns leaves it there forever. A directory with anything
+ * in it keeps the manual path.
+ *
+ * Two guards beyond the emptiness check:
+ *   • only directories directly inside morph's own worktree containers, never
+ *     the containers themselves and never a path git registers;
+ *   • `rmdirSync`, not `rm -rf` — it REFUSES a non-empty directory, so a file
+ *     that appears between the check and the call is a failure, not a loss.
+ *
+ * @param {string} root
+ * @returns {string[]} paths actually removed
+ */
+function removeEmptyUnregisteredDirs(root) {
+  const registeredPaths = new Set(parseWorktreeList(root).map((e) => norm(e.path)));
+  const removed = [];
+  for (const d of dirsOnDisk(root)) {
+    if (!d.empty || registeredPaths.has(d.path)) continue;
+    try {
+      rmdirSync(d.path);
+      removed.push(d.path);
+    } catch { /* raced, locked or no longer empty — leave it to the next audit */ }
+  }
+  return removed;
+}
+
+/**
+ * Drop git's admin records for worktrees whose directory is already gone,
+ * remove the EMPTY unregistered residue directories, AND clear any feature's
+ * `worktree` registration that names a directory that is now gone.
+ *
+ * These three are the ONLY prune offered, on purpose: none can destroy
+ * anything, because everything they touch is either already absent from disk
+ * or provably empty. Removing a directory that still HOLDS something is
+ * exactly the operation that needs a human looking at it.
  *
- * Both halves are the ONLY prune offered, on purpose: neither can destroy
- * anything, because everything they touch is already absent from disk.
- * Removing a directory that still exists is exactly the operation that needs
- * a human looking at it.
+ * Order is load-bearing: the empty directories go first, so a root pointer
+ * naming one of them becomes dangling in time for the registration sweep below
+ * to clear it — one command, not two runs.
  *
  * `clearDanglingWorktreeRegistration` re-checks the dangling predicate itself
  * (path unset, or still exists → no-op) rather than trusting a pre-computed
  * list, so this stays correct even called against a stale audit snapshot.
  *
  * @param {string} [cwd]
- * @returns {Promise<{ pruned: boolean, error?: string, clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
+ * @returns {Promise<{ pruned: boolean, error?: string, removedEmptyDirs: string[], clearedRegistrations: Array<{feature: string, cleared: boolean}> }>}
  */
 export async function pruneWorktrees(cwd = process.cwd()) {
-  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', clearedRegistrations: [] };
+  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo', removedEmptyDirs: [], clearedRegistrations: [] };
   const root = resolvePrimaryRoot(cwd);
 
   let pruned = false;
@@ -261,11 +424,13 @@ export async function pruneWorktrees(cwd = process.cwd()) {
     error = (err.message || 'unknown').slice(0, 200);
   }
 
+  const removedEmptyDirs = removeEmptyUnregisteredDirs(root);
+
   const clearedRegistrations = [];
   for (const reg of featureRegistrations(root)) {
     const { cleared } = await clearDanglingWorktreeRegistration(root, reg.feature);
     if (cleared) clearedRegistrations.push({ feature: reg.feature, cleared: true });
   }
 
-  return { pruned, ...(error ? { error } : {}), clearedRegistrations };
+  return { pruned, ...(error ? { error } : {}), removedEmptyDirs, clearedRegistrations };
 }