@polymorphism-tech/morph-spec 8.6.0 → 8.8.0

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

@@ -0,0 +1,181 @@
+/**
+ * worktree-audit.js — reconcile the three views of "which worktrees exist".
+ *
+ * Orphan worktrees accumulate silently. In the observed session,
+ * `.worktrees/verify-tables-ui` and `.worktrees/tmp-cleanup` were registered in
+ * `git worktree list` yet ABSENT from `morph-spec fleet` — fleet only reports
+ * worktrees whose branch matches `refs/heads/morph/*`, so anything else is
+ * invisible by construction and therefore never cleaned up (C2).
+ *
+ * Nothing compared the three sources that must agree:
+ *
+ *   1. git's registry   — `git worktree list --porcelain`
+ *   2. the disk         — directories under `worktrees/` (and legacy `.worktrees/`)
+ *   3. morph's features — `.morph/features/{f}/feature.json`
+ *
+ * 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.
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  isGitRepo,
+  resolvePrimaryRoot,
+  parseWorktreeList,
+  WORKTREE_DIR_NAMES,
+} from '../../commands/project/worktree.js';
+
+const norm = (p) => resolve(p).replace(/\\/g, '/');
+
+/** Feature names morph knows about in the primary root. */
+function knownFeatures(root) {
+  const names = new Set();
+  try {
+    const dir = join(root, '.morph', 'features');
+    if (!existsSync(dir)) return names;
+    for (const name of readdirSync(dir)) {
+      if (existsSync(join(dir, name, 'feature.json'))) names.add(name);
+    }
+  } catch { /* fail-open */ }
+  return names;
+}
+
+/**
+ * Is the feature's authoritative feature.json COMMITTED on its own branch?
+ *
+ * Not "does the branch exist": `git worktree add -b morph/{f}` creates the
+ * branch as a side effect, so branch-existence is true for every registered
+ * worktree and proves nothing. The blob is the real evidence — it is where the
+ * per-feature state model says the truth lives.
+ */
+function featureCommittedOnBranch(root, feature) {
+  try {
+    execFileSync('git', ['cat-file', '-e', `morph/${feature}:.morph/features/${feature}/feature.json`], {
+      cwd: root, stdio: 'pipe',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Directories physically present under either worktree root. */
+function dirsOnDisk(root) {
+  const found = [];
+  for (const dirName of WORKTREE_DIR_NAMES) {
+    const base = join(root, dirName);
+    if (!existsSync(base)) continue;
+    try {
+      for (const name of readdirSync(base)) {
+        const full = join(base, name);
+        try {
+          if (statSync(full).isDirectory()) found.push({ name, path: norm(full), container: dirName });
+        } catch { /* unreadable entry — skip */ }
+      }
+    } catch { /* fail-open */ }
+  }
+  return found;
+}
+
+/**
+ * Reconcile git's registry, the disk and morph's features.
+ *
+ * Issue types:
+ *   • registered-missing — git has a worktree whose directory is gone
+ *   • non-morph-branch   — a registered worktree under worktrees/ on a branch
+ *                          that is not `morph/*`, so `fleet` cannot see it
+ *   • unregistered-dir   — a directory under worktrees/ git never registered
+ *   • no-feature         — a `morph/{f}` worktree for a feature morph does not know
+ *
+ * @param {string} [cwd]
+ * @returns {Array<{ type: string, detail: string, path?: string, fix: string }>}
+ */
+export function auditWorktrees(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) return [];
+  const root = resolvePrimaryRoot(cwd);
+  const rootNorm = norm(root);
+  const issues = [];
+
+  const registered = parseWorktreeList(root);
+  const registeredPaths = new Set();
+  const features = knownFeatures(root);
+
+  for (const entry of registered) {
+    const path = norm(entry.path);
+    registeredPaths.add(path);
+    if (path === rootNorm) continue; // the primary root is not a worktree orphan
+
+    if (!existsSync(path)) {
+      issues.push({
+        type: 'registered-missing',
+        path,
+        detail: `git registra um worktree em ${path}, mas o diretório não existe`,
+        fix: `git worktree prune  (ou \`morph-spec doctor --worktrees --prune\`)`,
+      });
+      continue;
+    }
+
+    const feature = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1] || null;
+    if (!feature) {
+      // Only worth reporting when it sits in morph's own worktree container —
+      // 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`,
+          fix: `git worktree remove "${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: `git worktree remove "${path}"`,
+      });
+    }
+  }
+
+  for (const d of dirsOnDisk(root)) {
+    if (registeredPaths.has(d.path)) continue;
+    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`,
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Drop git's admin records for worktrees whose directory is already gone.
+ *
+ * The ONLY prune offered, on purpose: it cannot destroy anything, because
+ * everything it touches is already absent from disk. Removing a directory that
+ * still exists is exactly the operation that needs a human looking at it.
+ *
+ * @param {string} [cwd]
+ * @returns {{ pruned: boolean, error?: string }}
+ */
+export function pruneWorktrees(cwd = process.cwd()) {
+  if (!isGitRepo(cwd)) return { pruned: false, error: 'not-a-git-repo' };
+  try {
+    execFileSync('git', ['worktree', 'prune'], { cwd: resolvePrimaryRoot(cwd), stdio: 'pipe' });
+    return { pruned: true };
+  } catch (err) {
+    return { pruned: false, error: (err.message || 'unknown').slice(0, 200) };
+  }
+}

package/src/utils/file-copier.js

@@ -165,7 +165,11 @@ export async function updateGitignore(projectPath) {
     '.claude/agents/',
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
-    '.worktrees/',
+    '/worktrees/',
+    // Legacy name (pre-C1). Kept so a project that already has `.worktrees/`
+    // on disk does not suddenly see it as untracked dirt — which would also
+    // make `finish`'s clean-root check refuse.
+    '/.worktrees/',
     '.playwright-mcp/',
     'docs/superpowers/',
     ''

package/src/utils/hooks-installer.js

@@ -504,10 +504,16 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
     ? `"${resolvePythonForStatusline()}" "${join(globalDir, 'statusline.py').replace(/\\/g, '/')}"`
     : join(globalDir, 'statusline.sh').replace(/\\/g, '/');
 
+  // refreshInterval: without it the status line only re-renders on events
+  // (new assistant message, /compact, permission or vim mode change), so the
+  // `↻` countdown to the 5h rate-limit reset — the only widget that moves on
+  // its own — sits frozen through a long turn. Everything else is event-driven
+  // and would be fine without this.
   settings.statusLine = {
     type: 'command',
     command: statuslineCommand,
-    padding: 2
+    padding: 2,
+    refreshInterval: 10
   };
 
   await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');