fix: survive stale git worktree registrations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: centdix

backend/src/__tests__/git-adapter.test.ts

@@ -4,12 +4,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   BunGitGateway,
+  filterLiveWorktreeEntries,
+  listGitWorktrees,
   listLocalGitBranches,
   parseGitWorktreePorcelain,
   readGitWorktreeStatus,
   removeGitWorktree,
   resolveWorktreeGitDir,
   resolveWorktreeRoot,
+  worktreeEntryPathExists,
 } from "../adapters/git";
 
 function normalizePath(path: string): string {
@@ -323,6 +326,79 @@ describe("BunGitGateway", () => {
   });
 });
 
+describe("stale worktree resilience", () => {
+  let repoRoot = "";
+
+  afterEach(async () => {
+    if (repoRoot) {
+      await rm(repoRoot, { recursive: true, force: true });
+      repoRoot = "";
+    }
+  });
+
+  it("does not throw posix_spawn ENOENT for tryRunGit-backed callers when cwd is missing", () => {
+    // Regression for the crash: Bun.spawnSync throws synchronously when cwd is gone.
+    // tryRunGit-backed callers (readDiff, listUnpushedCommits, fetchBranch, ...) must
+    // surface this as a normal failure, not propagate the throw.
+    const gateway = new BunGitGateway();
+    expect(() => gateway.readDiff("/tmp/webmux-missing-xyz-12345-does-not-exist")).not.toThrow();
+    expect(gateway.readDiff("/tmp/webmux-missing-xyz-12345-does-not-exist")).toBe("");
+    expect(() => gateway.listUnpushedCommits("/tmp/webmux-missing-xyz-12345-does-not-exist")).not.toThrow();
+    expect(gateway.listUnpushedCommits("/tmp/webmux-missing-xyz-12345-does-not-exist")).toEqual([]);
+  });
+
+  it("throws a controlled error when runGit is invoked against a missing cwd", () => {
+    // runGit-backed callers re-raise with a readable message that names the cwd —
+    // not a bare posix_spawn stack trace.
+    expect(() => listLocalGitBranches("/tmp/webmux-missing-xyz-12345-does-not-exist"))
+      .toThrow(/cwd=\/tmp\/webmux-missing-xyz-12345-does-not-exist/);
+  });
+
+  it("worktreeEntryPathExists rejects missing paths", () => {
+    expect(worktreeEntryPathExists({
+      path: "/tmp/webmux-missing-xyz-12345-does-not-exist",
+      head: null,
+      branch: null,
+      detached: false,
+      bare: false,
+    })).toBe(false);
+  });
+
+  it("filterLiveWorktreeEntries drops stale entries and keeps live ones", async () => {
+    repoRoot = await mkdtemp(join(tmpdir(), "webmux-filter-live-"));
+    expect(filterLiveWorktreeEntries([
+      { path: repoRoot, head: "abc", branch: "main", detached: false, bare: false },
+      { path: "/tmp/webmux-missing-xyz-12345-does-not-exist", head: "def", branch: "stale", detached: false, bare: false },
+    ])).toEqual([
+      { path: repoRoot, head: "abc", branch: "main", detached: false, bare: false },
+    ]);
+  });
+
+  it("BunGitGateway.listLiveWorktrees omits registrations whose directory was deleted", async () => {
+    repoRoot = await mkdtemp(join(tmpdir(), "webmux-stale-wt-"));
+    run(["git", "init", "-b", "main"], repoRoot);
+    run(["git", "config", "user.name", "Test User"], repoRoot);
+    run(["git", "config", "user.email", "test@example.com"], repoRoot);
+    await Bun.write(join(repoRoot, "README.md"), "# repo\n");
+    run(["git", "add", "README.md"], repoRoot);
+    run(["git", "commit", "-m", "init"], repoRoot);
+
+    const worktreePath = join(repoRoot, "__worktrees", "stale");
+    await mkdir(join(repoRoot, "__worktrees"), { recursive: true });
+    run(["git", "worktree", "add", "-b", "stale", worktreePath], repoRoot);
+
+    await rm(worktreePath, { recursive: true, force: true });
+
+    // Raw list keeps the dangling registration (semantics preserved for removeGitWorktree).
+    expect(listGitWorktrees(repoRoot).some((entry) => entry.path === worktreePath)).toBe(true);
+
+    // Live list filters it out.
+    const gateway = new BunGitGateway();
+    expect(gateway.listLiveWorktrees(repoRoot).some((entry) => entry.path === worktreePath)).toBe(false);
+    expect(gateway.listLiveWorktrees(repoRoot).some((entry) => entry.path === repoRoot)).toBe(true);
+  });
+});
+
 describe("removeGitWorktree", () => {
   it("cleans up the leftover directory when git already unregistered the worktree", () => {
     const removedPaths: string[] = [];

backend/src/__tests__/reconciliation-service.test.ts

@@ -21,6 +21,7 @@ class FakeGitGateway implements GitGateway {
     private readonly worktrees: GitWorktreeEntry[],
     private readonly gitDirs: Map<string, string>,
     private readonly statuses: Map<string, GitWorktreeStatus>,
+    private readonly liveWorktrees?: GitWorktreeEntry[],
   ) {}
 
   resolveRepoRoot(dir: string): string | null {
@@ -41,6 +42,10 @@ class FakeGitGateway implements GitGateway {
     return this.worktrees;
   }
 
+  listLiveWorktrees(): GitWorktreeEntry[] {
+    return this.liveWorktrees ?? this.worktrees;
+  }
+
   listLocalBranches(): string[] {
     return [];
   }
@@ -304,6 +309,58 @@ describe("ReconciliationService", () => {
     expect(runtime.getWorktree("wt_stale")).toBeNull();
   });
 
+  it("ignores stale worktree registrations whose directory no longer exists", async () => {
+    // Reproduces the ENOENT add-flow crash: a git registration points at a directory
+    // that's gone. The service must complete the reconcile, never call git against the
+    // stale path, and not surface it in runtime state.
+    const repoRoot = "/repo/project";
+    const stalePath = "/repo/project/__worktrees/feature-stale-on-disk";
+    const livePath = "/repo/project/__worktrees/feature-live";
+    const liveGitDir = await mkdtemp(join(tmpdir(), "webmux-reconcile-live-"));
+    tempDirs.push(liveGitDir);
+
+    await writeWorktreeMeta(liveGitDir, {
+      schemaVersion: 1,
+      worktreeId: "wt_live",
+      branch: "feature/live",
+      createdAt: "2026-05-13T00:00:00.000Z",
+      profile: "default",
+      agent: "claude",
+      runtime: "host",
+      startupEnvValues: {},
+      allocatedPorts: { FRONTEND_PORT: 3010 },
+    });
+
+    const runtime = new ProjectRuntime();
+    const mainEntry = { path: repoRoot, branch: "main", head: "aaa111", detached: false, bare: false };
+    const liveEntry = { path: livePath, branch: "feature/live", head: "bbb222", detached: false, bare: false };
+    const staleEntry = { path: stalePath, branch: "feature/stale-on-disk", head: "ccc333", detached: false, bare: false };
+
+    const git = new FakeGitGateway(
+      [mainEntry, liveEntry, staleEntry],
+      new Map([
+        [livePath, liveGitDir],
+        // No mapping for stalePath — if the service ever calls resolveWorktreeGitDir
+        // on it, the fake throws and the test fails.
+      ]),
+      new Map([[livePath, { dirty: false, aheadCount: 0, currentCommit: "bbb222" }]]),
+      [mainEntry, liveEntry], // listLiveWorktrees excludes the stale entry
+    );
+
+    const service = new ReconciliationService({
+      config: TEST_CONFIG,
+      git,
+      tmux: new FakeTmuxGateway([]),
+      portProbe: new FakePortProbe(new Set([3010])),
+      runtime,
+    });
+
+    await service.reconcile(repoRoot);
+
+    expect(runtime.getWorktree("wt_live")).not.toBeNull();
+    expect(runtime.getWorktreeByBranch("feature/stale-on-disk")).toBeNull();
+  });
+
   it("creates synthetic ids for unmanaged worktrees", async () => {
     const repoRoot = "/repo/project";
     const unmanagedPath = "/repo/project/__worktrees/unmanaged";

backend/src/__tests__/worktree-storage.test.ts

@@ -53,6 +53,10 @@ class FakeGitGateway implements GitGateway {
     return [];
   }
 
+  listLiveWorktrees() {
+    return [];
+  }
+
   listLocalBranches(): string[] {
     return [];
   }

backend/src/adapters/git.ts

@@ -67,6 +67,7 @@ export interface GitGateway {
   resolveWorktreeRoot(cwd: string): string;
   resolveWorktreeGitDir(cwd: string): string;
   listWorktrees(cwd: string): GitWorktreeEntry[];
+  listLiveWorktrees(cwd: string): GitWorktreeEntry[];
   listLocalBranches(cwd: string): string[];
   listRemoteBranches(cwd: string): string[];
   readWorktreeStatus(cwd: string): GitWorktreeStatus;
@@ -83,12 +84,28 @@ export interface GitGateway {
   hardReset(repoRoot: string, ref: string): TryGitCommandResult;
 }
 
+function spawnGit(args: string[], cwd: string): { ok: true; result: Bun.SyncSubprocess<"pipe", "pipe"> } | { ok: false; stderr: string } {
+  try {
+    return {
+      ok: true,
+      result: Bun.spawnSync(["git", ...args], {
+        cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+      }),
+    };
+  } catch (error) {
+    // Bun.spawnSync throws synchronously when cwd doesn't exist (posix_spawn ENOENT).
+    return { ok: false, stderr: `spawn failed (cwd=${cwd}): ${errorMessage(error)}` };
+  }
+}
+
 function runGit(args: string[], cwd: string): string {
-  const result = Bun.spawnSync(["git", ...args], {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
+  const spawned = spawnGit(args, cwd);
+  if (!spawned.ok) {
+    throw new Error(`git ${args.join(" ")} failed: ${spawned.stderr}`);
+  }
+  const { result } = spawned;
 
   if (result.exitCode !== 0) {
     const stderr = new TextDecoder().decode(result.stderr).trim();
@@ -99,11 +116,11 @@ function runGit(args: string[], cwd: string): string {
 }
 
 function tryRunGit(args: string[], cwd: string): TryGitCommandResult {
-  const result = Bun.spawnSync(["git", ...args], {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
+  const spawned = spawnGit(args, cwd);
+  if (!spawned.ok) {
+    return { ok: false, stderr: spawned.stderr };
+  }
+  const { result } = spawned;
 
   if (result.exitCode !== 0) {
     return {
@@ -248,6 +265,18 @@ export function listGitWorktrees(cwd: string): GitWorktreeEntry[] {
   return parseGitWorktreePorcelain(output);
 }
 
+export function worktreeEntryPathExists(entry: GitWorktreeEntry): boolean {
+  try {
+    return statSync(entry.path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function filterLiveWorktreeEntries(entries: GitWorktreeEntry[]): GitWorktreeEntry[] {
+  return entries.filter(worktreeEntryPathExists);
+}
+
 export function listLocalGitBranches(cwd: string): string[] {
   const output = runGit(["for-each-ref", "--format=%(refname:short)", "refs/heads"], cwd);
   return output
@@ -332,6 +361,10 @@ export class BunGitGateway implements GitGateway {
     return listGitWorktrees(cwd);
   }
 
+  listLiveWorktrees(cwd: string): GitWorktreeEntry[] {
+    return filterLiveWorktreeEntries(listGitWorktrees(cwd));
+  }
+
   listLocalBranches(cwd: string): string[] {
     return listLocalGitBranches(cwd);
   }

backend/src/server.ts

@@ -409,7 +409,7 @@ async function hasValidControlToken(req: Request): Promise<boolean> {
 async function getWorktreeGitDirs(): Promise<Map<string, string>> {
   const gitDirs = new Map<string, string>();
   const projectRoot = resolve(PROJECT_DIR);
-  for (const entry of git.listWorktrees(projectRoot)) {
+  for (const entry of git.listLiveWorktrees(projectRoot)) {
     if (entry.bare || resolve(entry.path) === projectRoot || !entry.branch) continue;
     gitDirs.set(entry.branch, git.resolveWorktreeGitDir(entry.path));
   }

backend/src/services/auto-remove-service.ts

@@ -17,7 +17,7 @@ export interface AutoRemoveDependencies {
 /** Check all worktrees for merged PRs and remove clean ones.
  *  Called after PR sync completes -- reads the PR files that sync just wrote. */
 export async function runAutoRemove(deps: AutoRemoveDependencies): Promise<void> {
-  const worktrees = deps.git.listWorktrees(deps.projectRoot)
+  const worktrees = deps.git.listLiveWorktrees(deps.projectRoot)
     .filter((e) => !e.bare && e.branch !== null && e.path !== deps.projectRoot);
 
   for (const entry of worktrees) {

backend/src/services/lifecycle-service.ts

@@ -526,7 +526,7 @@ export class LifecycleService {
 
   private listProjectWorktrees(): GitWorktreeEntry[] {
     const projectRoot = resolve(this.deps.projectRoot);
-    return this.deps.git.listWorktrees(projectRoot).filter((entry) =>
+    return this.deps.git.listLiveWorktrees(projectRoot).filter((entry) =>
       !entry.bare && resolve(entry.path) !== projectRoot
     );
   }

backend/src/services/reconciliation-service.ts

@@ -150,7 +150,7 @@ export class ReconciliationService {
   }
 
   private async runReconcile(normalizedRepoRoot: string): Promise<void> {
-    const worktrees = this.deps.git.listWorktrees(normalizedRepoRoot);
+    const worktrees = this.deps.git.listLiveWorktrees(normalizedRepoRoot);
     const sessionName = buildProjectSessionName(normalizedRepoRoot);
 
     let windows: TmuxWindowSummary[] = [];