feat: repo-level worktree housekeeping

apps/server/src/git/GitWorkflowService.ts

@@ -19,6 +19,12 @@ import {
   type GitPullRequestRefInput,
   type VcsPullResult,
   type VcsRemoveWorktreeInput,
+  type VcsListManagedWorktreesInput,
+  type VcsListManagedWorktreesResult,
+  type VcsWorktreeSizeInput,
+  type VcsWorktreeSizeResult,
+  type VcsRemoveWorktreesInput,
+  type VcsRemoveWorktreesResult,
   type GitResolvePullRequestResult,
   type GitRunStackedActionInput,
   type GitRunStackedActionResult,
@@ -61,6 +67,15 @@ export interface GitWorkflowServiceShape {
     input: VcsCreateWorktreeInput,
   ) => Effect.Effect<VcsCreateWorktreeResult, GitCommandError>;
   readonly removeWorktree: (input: VcsRemoveWorktreeInput) => Effect.Effect<void, GitCommandError>;
+  readonly listManagedWorktrees: (
+    input: VcsListManagedWorktreesInput,
+  ) => Effect.Effect<VcsListManagedWorktreesResult, GitCommandError>;
+  readonly worktreeSize: (
+    input: VcsWorktreeSizeInput,
+  ) => Effect.Effect<VcsWorktreeSizeResult, GitCommandError>;
+  readonly removeWorktrees: (
+    input: VcsRemoveWorktreesInput,
+  ) => Effect.Effect<VcsRemoveWorktreesResult, GitCommandError>;
   readonly createRef: (
     input: VcsCreateRefInput,
   ) => Effect.Effect<VcsCreateRefResult, GitCommandError>;
@@ -298,6 +313,15 @@ export const make = Effect.fn("makeGitWorkflowService")(function* () {
       ensureGitCommand("GitWorkflowService.removeWorktree", input.cwd).pipe(
         Effect.andThen(git.removeWorktree(input)),
       ),
+    listManagedWorktrees: (input) =>
+      ensureGitCommand("GitWorkflowService.listManagedWorktrees", input.cwd).pipe(
+        Effect.andThen(git.listManagedWorktrees(input)),
+      ),
+    worktreeSize: (input) => git.worktreeSize(input),
+    removeWorktrees: (input) =>
+      ensureGitCommand("GitWorkflowService.removeWorktrees", input.cwd).pipe(
+        Effect.andThen(git.removeWorktrees(input)),
+      ),
     createRef: (input) =>
       ensureGitCommand("GitWorkflowService.createRef", input.cwd).pipe(
         Effect.andThen(git.createRef(input)),

apps/server/src/server.test.ts

@@ -4861,6 +4861,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                 worktree: { path: "/tmp/wt", refName: "feature/demo" },
               }),
             removeWorktree: () => Effect.void,
+            listManagedWorktrees: () => Effect.succeed({ worktrees: [] }),
+            worktreeSize: () => Effect.succeed({ sizeBytes: 0 }),
+            removeWorktrees: () => Effect.succeed({ results: [] }),
             createRef: (input) => Effect.succeed({ refName: input.refName }),
             switchRef: (input) => Effect.succeed({ refName: input.refName }),
           },

apps/server/src/vcs/GitVcsDriver.ts

@@ -25,6 +25,12 @@ import {
   type VcsListRefsResult,
   type VcsPullResult,
   type VcsRemoveWorktreeInput,
+  type VcsListManagedWorktreesInput,
+  type VcsListManagedWorktreesResult,
+  type VcsWorktreeSizeInput,
+  type VcsWorktreeSizeResult,
+  type VcsRemoveWorktreesInput,
+  type VcsRemoveWorktreesResult,
   type VcsStatusInput,
   type VcsStatusResult,
 } from "@t3tools/contracts";
@@ -222,6 +228,15 @@ export interface GitVcsDriverShape {
     input: GitSetBranchUpstreamInput,
   ) => Effect.Effect<void, GitCommandError>;
   readonly removeWorktree: (input: VcsRemoveWorktreeInput) => Effect.Effect<void, GitCommandError>;
+  readonly listManagedWorktrees: (
+    input: VcsListManagedWorktreesInput,
+  ) => Effect.Effect<VcsListManagedWorktreesResult, GitCommandError>;
+  readonly worktreeSize: (
+    input: VcsWorktreeSizeInput,
+  ) => Effect.Effect<VcsWorktreeSizeResult, GitCommandError>;
+  readonly removeWorktrees: (
+    input: VcsRemoveWorktreesInput,
+  ) => Effect.Effect<VcsRemoveWorktreesResult, GitCommandError>;
   readonly renameBranch: (
     input: GitRenameBranchInput,
   ) => Effect.Effect<GitRenameBranchResult, GitCommandError>;

apps/server/src/vcs/GitVcsDriverCore.test.ts

@@ -373,6 +373,102 @@ it.layer(TestLayer)("GitVcsDriver core integration", (it) => {
     );
   });
 
+  describe("managed worktrees", () => {
+    it.effect("lists managed worktrees under the worktrees dir with dirty status", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        yield* driver.createWorktree({
+          cwd,
+          refName: initialBranch,
+          newRefName: "feature-a",
+          path: null,
+        });
+
+        const result = yield* driver.listManagedWorktrees({ cwd });
+
+        assert.equal(result.worktrees.length, 1);
+        assert.equal(result.worktrees[0]?.refName, "feature-a");
+        // Fresh worktree branch has no remote => treated as dirty (unpushed).
+        assert.equal(result.worktrees[0]?.isDirty, true);
+      }),
+    );
+
+    it.effect("computes the on-disk byte size of a worktree", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        const created = yield* driver.createWorktree({
+          cwd,
+          refName: initialBranch,
+          newRefName: "feature-size",
+          path: null,
+        });
+
+        const { sizeBytes } = yield* driver.worktreeSize({ path: created.worktree.path });
+
+        // A real checkout always has tracked files on disk.
+        assert.isAbove(sizeBytes, 0);
+      }),
+    );
+
+    it.effect("batch-removes worktrees and reports per-path outcomes", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        const { initialBranch } = yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        const a = yield* driver.createWorktree({
+          cwd,
+          refName: initialBranch,
+          newRefName: "rm-a",
+          path: null,
+        });
+
+        const { results } = yield* driver.removeWorktrees({
+          cwd,
+          items: [
+            { path: a.worktree.path, force: true },
+            { path: "/does/not/exist", force: true },
+          ],
+        });
+
+        assert.equal(results.length, 2);
+        assert.equal(results.find((r) => r.path === a.worktree.path)?.ok, true);
+        const missing = results.find((r) => r.path === "/does/not/exist");
+        assert.equal(missing?.ok, false);
+        assert.isString(missing?.error);
+      }),
+    );
+
+    it.effect("refuses to remove a path outside the managed worktrees dir", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTmpDir();
+        yield* initRepoWithCommit(cwd);
+        const driver = yield* GitVcsDriver.GitVcsDriver;
+
+        // A real directory that exists but is not under the server worktrees dir.
+        const outside = yield* makeTmpDir("outside-");
+
+        const { results } = yield* driver.removeWorktrees({
+          cwd,
+          items: [{ path: outside, force: true }],
+        });
+
+        assert.equal(results.length, 1);
+        assert.equal(results[0]?.ok, false);
+        assert.match(results[0]?.error ?? "", /managed worktrees directory/i);
+        // The refusal must not delete the directory.
+        const fileSystem = yield* FileSystem.FileSystem;
+        assert.equal(yield* fileSystem.exists(outside), true);
+      }),
+    );
+  });
+
   describe("commit context", () => {
     it.effect("stages selected files and commits only those files", () =>
       Effect.gen(function* () {

apps/server/src/vcs/GitVcsDriverCore.ts

@@ -2247,6 +2247,177 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     );
   });
 
+  const readWorktreeDirty = (worktreePath: string): Effect.Effect<boolean, never> =>
+    Effect.gen(function* () {
+      const statusResult = yield* executeGit(
+        "GitVcsDriver.listManagedWorktrees.status",
+        worktreePath,
+        ["status", "--porcelain"],
+        { timeoutMs: 10_000, allowNonZeroExit: true },
+      ).pipe(Effect.orElseSucceed(() => null));
+      if (statusResult && statusResult.stdout.trim().length > 0) {
+        return true;
+      }
+      const remoteContains = yield* executeGit(
+        "GitVcsDriver.listManagedWorktrees.remoteContains",
+        worktreePath,
+        ["branch", "--remotes", "--contains", "HEAD"],
+        { timeoutMs: 10_000, allowNonZeroExit: true },
+      ).pipe(Effect.orElseSucceed(() => null));
+      const hasRemoteContainingHead =
+        remoteContains !== null &&
+        remoteContains.exitCode === 0 &&
+        remoteContains.stdout.trim().length > 0;
+      // No remote branch contains HEAD => there is unpushed work.
+      return !hasRemoteContainingHead;
+    });
+
+  const resolveRealPath = (p: string): Effect.Effect<string, never> =>
+    fileSystem.realPath(p).pipe(Effect.orElseSucceed(() => p));
+
+  const listManagedWorktrees: GitVcsDriver.GitVcsDriverShape["listManagedWorktrees"] = Effect.fn(
+    "listManagedWorktrees",
+  )(function* (input) {
+    const result = yield* executeGit(
+      "GitVcsDriver.listManagedWorktrees",
+      input.cwd,
+      ["worktree", "list", "--porcelain"],
+      { timeoutMs: 10_000, fallbackErrorMessage: "git worktree list failed" },
+    );
+
+    const realWorktreesDir = yield* resolveRealPath(worktreesDir);
+    const isUnderWorktreesDir = (candidate: string): boolean =>
+      candidate === realWorktreesDir || candidate.startsWith(realWorktreesDir + path.sep);
+
+    const rawCandidates: { path: string; refName: string }[] = [];
+    let currentPath: string | null = null;
+    let currentBranch: string | null = null;
+    const flush = () => {
+      if (currentPath) {
+        rawCandidates.push({
+          path: currentPath,
+          refName: currentBranch ?? path.basename(currentPath),
+        });
+      }
+      currentPath = null;
+      currentBranch = null;
+    };
+    for (const line of result.stdout.split("\n")) {
+      if (line.startsWith("worktree ")) {
+        flush();
+        currentPath = line.slice("worktree ".length).trim();
+      } else if (line.startsWith("branch refs/heads/")) {
+        currentBranch = line.slice("branch refs/heads/".length).trim();
+      } else if (line.trim() === "") {
+        flush();
+      }
+    }
+    flush();
+
+    // Resolve each candidate's real path (also confirms it still exists on disk) and
+    // compare against the resolved worktrees dir so symlinked paths match symmetrically.
+    const existing = yield* Effect.forEach(
+      rawCandidates,
+      (candidate) =>
+        fileSystem.realPath(candidate.path).pipe(
+          Effect.map((realCandidatePath) =>
+            isUnderWorktreesDir(realCandidatePath)
+              ? Option.some({ path: candidate.path, refName: candidate.refName })
+              : Option.none<{ path: string; refName: string }>(),
+          ),
+          Effect.orElseSucceed(() => Option.none<{ path: string; refName: string }>()),
+        ),
+      { concurrency: 8 },
+    ).pipe(Effect.map((options) => options.flatMap((o) => (Option.isSome(o) ? [o.value] : []))));
+
+    const worktrees = yield* Effect.forEach(
+      existing,
+      (candidate) =>
+        readWorktreeDirty(candidate.path).pipe(
+          Effect.map((isDirty) => ({ path: candidate.path, refName: candidate.refName, isDirty })),
+        ),
+      { concurrency: 4 },
+    );
+
+    return { worktrees };
+  });
+
+  const directorySizeBytes = (rootPath: string): Effect.Effect<number, never> => {
+    const walk = (current: string): Effect.Effect<number, never> =>
+      fileSystem.readDirectory(current).pipe(
+        Effect.flatMap((entries) =>
+          Effect.forEach(
+            entries,
+            (entry) => {
+              const childPath = path.join(current, entry);
+              return fileSystem.stat(childPath).pipe(
+                Effect.flatMap((info) =>
+                  info.type === "Directory"
+                    ? walk(childPath)
+                    : Effect.succeed(Number(info.size)),
+                ),
+                Effect.orElseSucceed(() => 0),
+              );
+            },
+            { concurrency: 8 },
+          ),
+        ),
+        Effect.map((sizes) => sizes.reduce((total, size) => total + size, 0)),
+        Effect.orElseSucceed(() => 0),
+      );
+    return walk(rootPath);
+  };
+
+  const worktreeSize: GitVcsDriver.GitVcsDriverShape["worktreeSize"] = Effect.fn("worktreeSize")(
+    function* (input) {
+      const sizeBytes = yield* directorySizeBytes(input.path);
+      return { sizeBytes };
+    },
+  );
+
+  const removeWorktrees: GitVcsDriver.GitVcsDriverShape["removeWorktrees"] = Effect.fn(
+    "removeWorktrees",
+  )(function* (input) {
+    // Defense-in-depth: never run `git worktree remove` on a client-supplied path
+    // that is not under the managed worktrees dir, even though git itself only
+    // operates on registered worktrees.
+    const realWorktreesDir = yield* resolveRealPath(worktreesDir);
+    const results = yield* Effect.forEach(
+      input.items,
+      (item) =>
+        resolveRealPath(item.path).pipe(
+          Effect.flatMap((realCandidate) => {
+            const isManaged =
+              realCandidate === realWorktreesDir ||
+              realCandidate.startsWith(realWorktreesDir + path.sep);
+            if (!isManaged) {
+              return Effect.succeed({
+                path: item.path,
+                ok: false as const,
+                error: "refused: path is outside the managed worktrees directory",
+              });
+            }
+            const args = ["worktree", "remove"];
+            if (item.force) {
+              args.push("--force");
+            }
+            args.push(item.path);
+            return executeGit("GitVcsDriver.removeWorktrees", input.cwd, args, {
+              timeoutMs: 15_000,
+              fallbackErrorMessage: "git worktree remove failed",
+            }).pipe(
+              Effect.as({ path: item.path, ok: true as const }),
+              Effect.catch((error) =>
+                Effect.succeed({ path: item.path, ok: false as const, error: error.message }),
+              ),
+            );
+          }),
+        ),
+      { concurrency: 1 },
+    );
+    return { results };
+  });
+
   const renameBranch: GitVcsDriver.GitVcsDriverShape["renameBranch"] = Effect.fn("renameBranch")(
     function* (input) {
       if (input.oldBranch === input.newBranch) {
@@ -2411,6 +2582,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     fetchRemoteTrackingBranch,
     setBranchUpstream,
     removeWorktree,
+    listManagedWorktrees,
+    worktreeSize,
+    removeWorktrees,
     renameBranch,
     createRef,
     switchRef,