Clean up merged worktrees after thread deletion

- Add merged worktree candidate detection and prune support
- Auto-remove orphaned worktrees after merged thread cleanup
- Surface cleanup state through the web client and WS contract

Author: BunsDev

apps/server/src/git/Layers/GitCore.ts

@@ -1963,6 +1963,24 @@ export const makeGitCore = (options?: { executeOverride?: GitCoreShape["execute"
             ),
           ),
         );
+
+        // Keep Git's worktree bookkeeping tidy after removing a checkout.
+        yield* executeGit("GitCore.removeWorktree.prune", input.cwd, [
+          "worktree",
+          "prune",
+          "--expire",
+          "now",
+        ], {
+          allowNonZeroExit: true,
+          timeoutMs: 15_000,
+        }).pipe(
+          Effect.catchAll((error) =>
+            Effect.logWarning("GitCore.removeWorktree: worktree prune failed", {
+              cwd: input.cwd,
+              error: error instanceof Error ? error.message : String(error),
+            }).pipe(Effect.asVoid),
+          ),
+        );
       });
 
     const renameBranch: GitCoreShape["renameBranch"] = (input) =>

apps/server/src/git/worktreeCleanup.ts

@@ -0,0 +1,135 @@
+import { realpathSync } from "node:fs";
+
+export interface WorktreeCleanupCandidate {
+  readonly path: string;
+  readonly branch: string;
+  readonly prNumber: number;
+  readonly prTitle: string;
+  readonly prUrl: string;
+  readonly mergedAt: string;
+  readonly pathExists: boolean;
+  readonly prunable: boolean;
+}
+
+interface WorktreeListEntry {
+  path: string;
+  branch: string | null;
+  prunable: boolean;
+}
+
+interface MergedPullRequestLike {
+  readonly number: number;
+  readonly title: string;
+  readonly url: string;
+  readonly headBranch: string;
+  readonly mergedAt: string;
+}
+
+function canonicalizePath(value: string): string {
+  try {
+    return realpathSync.native(value);
+  } catch {
+    return value.replace(/\\/g, "/").replace(/\/+$/, "");
+  }
+}
+
+function parseWorktreeList(stdout: string): WorktreeListEntry[] {
+  const entries: WorktreeListEntry[] = [];
+  let current: WorktreeListEntry | null = null;
+
+  for (const rawLine of stdout.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (line.length === 0) {
+      if (current) {
+        entries.push(current);
+      }
+      current = null;
+      continue;
+    }
+
+    if (line.startsWith("worktree ")) {
+      if (current) {
+        entries.push(current);
+      }
+      current = {
+        path: line.slice("worktree ".length).trim(),
+        branch: null,
+        prunable: false,
+      };
+      continue;
+    }
+
+    if (!current) {
+      continue;
+    }
+
+    if (line.startsWith("branch refs/heads/")) {
+      current.branch = line.slice("branch refs/heads/".length).trim() || null;
+      continue;
+    }
+
+    if (line.startsWith("prunable")) {
+      current.prunable = true;
+    }
+  }
+
+  if (current) {
+    entries.push(current);
+  }
+
+  return entries;
+}
+
+export function collectMergedWorktreeCleanupCandidates(input: {
+  cwd: string;
+  worktreeListStdout: string;
+  mergedPullRequests: ReadonlyArray<MergedPullRequestLike>;
+}): WorktreeCleanupCandidate[] {
+  const mergedPullRequestsByHeadBranch = new Map(
+    input.mergedPullRequests.map((pr) => [pr.headBranch, pr] as const),
+  );
+  const rootPath = canonicalizePath(input.cwd);
+
+  return parseWorktreeList(input.worktreeListStdout)
+    .flatMap((entry) => {
+      const branch = entry.branch?.trim() ?? "";
+      if (!branch) {
+        return [];
+      }
+      const pullRequest = mergedPullRequestsByHeadBranch.get(branch);
+      if (!pullRequest) {
+        return [];
+      }
+
+      const candidatePath = entry.path.trim();
+      if (!candidatePath) {
+        return [];
+      }
+
+      if (canonicalizePath(candidatePath) === rootPath) {
+        return [];
+      }
+
+      return [
+        {
+          path: candidatePath,
+          branch,
+          prNumber: pullRequest.number,
+          prTitle: pullRequest.title,
+          prUrl: pullRequest.url,
+          mergedAt: pullRequest.mergedAt,
+          pathExists: !entry.prunable,
+          prunable: entry.prunable,
+        },
+      ];
+    })
+    .toSorted((a, b) => {
+      if (a.pathExists !== b.pathExists) {
+        return a.pathExists ? -1 : 1;
+      }
+      if (a.mergedAt !== b.mergedAt) {
+        return b.mergedAt.localeCompare(a.mergedAt);
+      }
+      return a.branch.localeCompare(b.branch);
+    });
+}

apps/server/src/wsServer.ts

@@ -69,6 +69,7 @@ import { clamp } from "effect/Number";
 import { Open, resolveAvailableEditors } from "./open";
 import { ServerConfig } from "./config";
 import { GitCore } from "./git/Services/GitCore.ts";
+import { collectMergedWorktreeCleanupCandidates } from "./git/worktreeCleanup.ts";
 import { tryHandleProjectFaviconRequest } from "./projectFaviconRoute";
 import {
   ATTACHMENTS_ROUTE_PREFIX,
@@ -1183,6 +1184,39 @@ export const createServer = Effect.fn(function* (): Effect.fn.Return<
           .pipe(Effect.provideService(RuntimeEnv, gitEnv));
       }
 
+      case WS_METHODS.gitListMergedWorktreeCleanupCandidates: {
+        const body = stripRequestTag(request.body);
+        const snapshot = yield* projectionReadModelQuery.getSnapshot();
+        const gitEnv = yield* resolveRuntimeEnvironment({ cwd: body.cwd, readModel: snapshot });
+        const mergedPullRequests = yield* gitManager
+          .listPullRequests({
+            cwd: body.cwd,
+            state: "merged",
+            limit: 500,
+          })
+          .pipe(Effect.provideService(RuntimeEnv, gitEnv));
+        const worktreeList = yield* git
+          .execute({
+            cwd: body.cwd,
+            args: ["worktree", "list", "--porcelain"],
+            timeoutMs: 5_000,
+            allowNonZeroExit: true,
+          })
+          .pipe(Effect.provideService(RuntimeEnv, gitEnv));
+
+        return collectMergedWorktreeCleanupCandidates({
+          cwd: body.cwd,
+          worktreeListStdout: worktreeList.stdout,
+          mergedPullRequests: mergedPullRequests.pullRequests.map((pr) => ({
+            number: pr.number,
+            title: pr.title,
+            url: pr.url,
+            headBranch: pr.headBranch,
+            mergedAt: pr.updatedAt,
+          })),
+        });
+      }
+
       case WS_METHODS.prReviewGetConfig: {
         const body = stripRequestTag(request.body);
         yield* prReview
@@ -1341,6 +1375,19 @@ export const createServer = Effect.fn(function* (): Effect.fn.Return<
         return yield* git.removeWorktree(body).pipe(Effect.provideService(RuntimeEnv, gitEnv));
       }
 
+      case WS_METHODS.gitPruneWorktrees: {
+        const body = stripRequestTag(request.body);
+        const snapshot = yield* projectionReadModelQuery.getSnapshot();
+        const gitEnv = yield* resolveRuntimeEnvironment({ cwd: body.cwd, readModel: snapshot });
+        return yield* git
+          .execute({
+            cwd: body.cwd,
+            args: ["worktree", "prune", "--expire", "now"],
+            timeoutMs: 15_000,
+          })
+          .pipe(Effect.provideService(RuntimeEnv, gitEnv));
+      }
+
       case WS_METHODS.gitCreateBranch: {
         const body = stripRequestTag(request.body);
         const snapshot = yield* projectionReadModelQuery.getSnapshot();

apps/web/src/hooks/useAutoDeleteMergedThreads.ts

@@ -1,12 +1,13 @@
 import { useEffect, useRef } from "react";
-import { useQueries } from "@tanstack/react-query";
+import { useQueries, useQueryClient } from "@tanstack/react-query";
 import type { ThreadId } from "@okcode/contracts";
 
 import type { AppSettings } from "../appSettings";
-import { gitStatusQueryOptions } from "../lib/gitReactQuery";
+import { gitQueryKeys, gitStatusQueryOptions } from "../lib/gitReactQuery";
 import { readNativeApi } from "../nativeApi";
 import { newCommandId } from "../lib/utils";
 import { useStore } from "../store";
+import { formatWorktreePathForDisplay, getOrphanedWorktreePathForThread } from "../worktreeCleanup";
 import { toastManager } from "../components/ui/toast";
 
 /**
@@ -33,6 +34,7 @@ interface MergedThreadTimer {
 export function useAutoDeleteMergedThreads(settings: AppSettings) {
   const threads = useStore((store) => store.threads);
   const projects = useStore((store) => store.projects);
+  const queryClient = useQueryClient();
 
   // Track active timers per thread so we can cancel on setting change or
   // unmount, and avoid double-scheduling.
@@ -72,11 +74,14 @@ export function useAutoDeleteMergedThreads(settings: AppSettings) {
     for (let i = 0; i < threads.length; i++) {
       const thread = threads[i]!;
       const prState = statusQueries[i]?.data?.pr?.state;
+      const orphanedWorktreePath = getOrphanedWorktreePathForThread(threads, thread.id);
 
-      if (prState === "merged" && !timersRef.current.has(thread.id)) {
+      if (prState === "merged" && orphanedWorktreePath && !timersRef.current.has(thread.id)) {
         // PR just detected as merged – start countdown.
         const threadTitle = thread.title || `Thread ${thread.id.slice(0, 8)}`;
         const minutesLabel = delayMinutes === 1 ? "1 minute" : `${delayMinutes} minutes`;
+        const threadProject = projects.find((project) => project.id === thread.projectId) ?? null;
+        const displayWorktreePath = formatWorktreePathForDisplay(orphanedWorktreePath);
 
         const toastId = toastManager.add({
           type: "info",
@@ -101,20 +106,33 @@ export function useAutoDeleteMergedThreads(settings: AppSettings) {
         });
 
         const timeoutId = setTimeout(() => {
-          void deleteThreadById(thread.id);
-          timersRef.current.delete(thread.id);
-          toastManager.add({
-            type: "success",
-            title: "Merged thread deleted",
-            description: `"${threadTitle}" was auto-deleted after its PR was merged.`,
-          });
+          void (async () => {
+            try {
+              await deleteThreadById(thread.id);
+              if (threadProject && orphanedWorktreePath) {
+                await removeOrphanedWorktree({
+                  threadId: thread.id,
+                  projectCwd: threadProject.cwd,
+                  worktreePath: orphanedWorktreePath,
+                });
+              }
+              toastManager.add({
+                type: "success",
+                title: "Merged thread deleted",
+                description: `"${threadTitle}" was auto-deleted after its PR was merged.`,
+              });
+            } finally {
+              timersRef.current.delete(thread.id);
+              void queryClient.invalidateQueries({ queryKey: gitQueryKeys.all });
+            }
+          })();
         }, delayMs);
 
         timersRef.current.set(thread.id, { timeoutId, toastId });
       }
 
       // If a timer exists but the thread is gone (deleted externally), clean up.
-      if (prState !== "merged" && timersRef.current.has(thread.id)) {
+      if ((prState !== "merged" || !orphanedWorktreePath) && timersRef.current.has(thread.id)) {
         const timer = timersRef.current.get(thread.id)!;
         clearTimeout(timer.timeoutId);
         if (timer.toastId !== null) {
@@ -184,3 +202,33 @@ async function deleteThreadById(threadId: ThreadId): Promise<void> {
     threadId,
   });
 }
+
+async function removeOrphanedWorktree(input: {
+  threadId: ThreadId;
+  projectCwd: string;
+  worktreePath: string;
+}): Promise<void> {
+  const api = readNativeApi();
+  if (!api) return;
+
+  try {
+    await api.git.removeWorktree({
+      cwd: input.projectCwd,
+      path: input.worktreePath,
+      force: true,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error removing worktree.";
+    console.error("Failed to remove orphaned worktree after merged-thread auto-delete", {
+      threadId: input.threadId,
+      projectCwd: input.projectCwd,
+      worktreePath: input.worktreePath,
+      error,
+    });
+    toastManager.add({
+      type: "error",
+      title: "Thread deleted, but worktree removal failed",
+      description: `Could not remove ${formatWorktreePathForDisplay(input.worktreePath)}. ${message}`,
+    });
+  }
+}

apps/web/src/lib/gitReactQuery.ts

@@ -1,4 +1,4 @@
-import type { GitStackedAction } from "@okcode/contracts";
+import type { GitStackedAction, GitWorktreeCleanupCandidate } from "@okcode/contracts";
 import { mutationOptions, queryOptions, type QueryClient } from "@tanstack/react-query";
 import { ensureNativeApi } from "../nativeApi";
 
@@ -12,6 +12,8 @@ export const gitQueryKeys = {
   status: (cwd: string | null) => ["git", "status", cwd] as const,
   branches: (cwd: string | null) => ["git", "branches", cwd] as const,
   pullRequests: (cwd: string | null) => ["git", "pull-requests", cwd] as const,
+  mergedWorktreeCleanupCandidates: (cwd: string | null) =>
+    ["git", "merged-worktree-cleanup-candidates", cwd] as const,
 };
 
 export const gitMutationKeys = {
@@ -243,6 +245,36 @@ export function gitRemoveWorktreeMutationOptions(input: { queryClient: QueryClie
   });
 }
 
+export function gitPruneWorktreesMutationOptions(input: { queryClient: QueryClient }) {
+  return mutationOptions({
+    mutationFn: async ({ cwd }: { cwd: string }) => {
+      const api = ensureNativeApi();
+      if (!cwd) throw new Error("Git worktree pruning is unavailable.");
+      return api.git.pruneWorktrees({ cwd });
+    },
+    mutationKey: ["git", "mutation", "prune-worktrees"] as const,
+    onSettled: async () => {
+      await invalidateGitQueries(input.queryClient);
+    },
+  });
+}
+
+export function gitMergedWorktreeCleanupCandidatesQueryOptions(cwd: string | null) {
+  return queryOptions({
+    queryKey: gitQueryKeys.mergedWorktreeCleanupCandidates(cwd),
+    queryFn: async (): Promise<ReadonlyArray<GitWorktreeCleanupCandidate>> => {
+      const api = ensureNativeApi();
+      if (!cwd) throw new Error("Merged worktree cleanup is unavailable.");
+      return api.git.listMergedWorktreeCleanupCandidates({ cwd });
+    },
+    enabled: cwd !== null,
+    staleTime: 15_000,
+    refetchOnWindowFocus: true,
+    refetchOnReconnect: true,
+    refetchInterval: 30_000,
+  });
+}
+
 export function gitCloneRepositoryMutationOptions(input: { queryClient: QueryClient }) {
   return mutationOptions({
     mutationKey: ["git", "mutation", "clone-repository"] as const,