fix: guard Paperclip worktree cleanup lifecycle (WAT-1777)

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: willblanchard

doc/experimental/issue-worktree-support.md

@@ -22,6 +22,45 @@ We are intentionally not shipping the UI for this yet. The runtime code remains
 - seeded worktree instances can keep local-encrypted secrets working
 - seeded worktree instances can rebind same-repo project workspace paths onto the current git worktree
 
+## Large-repo Worktree Lifecycle Policy
+
+Paperclip-owned issue and review worktrees are execution workspaces, not agent-owned scratch directories. The execution workspace record is the source of truth for:
+
+- owner: the Paperclip company/project plus the issue linked through `sourceIssueId` and `issues.executionWorkspaceId`
+- linked work: the issue identifier, branch name, base ref, project workspace, and any PR link carried in the issue thread
+- creation and use time: `openedAt`, `createdAt`, and `lastUsedAt`
+- cleanup eligibility: `closedAt`, `cleanupEligibleAt`, `cleanupReason`, and workspace `status`
+- provider ownership: `providerType: "git_worktree"` plus `metadata.createdByRuntime: true` means Paperclip may remove the derived worktree after close-readiness passes
+
+Retention defaults for large local worktrees:
+
+- active or linked to open issue: keep; report size and readiness only
+- clean, idle, Paperclip-created issue worktree: eligible for cleanup after 24 hours
+- in review: keep for 7 days unless a reviewer explicitly archives the workspace earlier
+- `cleanup_failed`: keep until an operator resolves the reported reason
+- shared/project-primary workspace: never delete the underlying project checkout; archive only the execution workspace record
+
+Close and cleanup must use the execution workspace close-readiness report before deleting anything. The report includes linked open issues, runtime services, git dirty state, untracked files, ahead/behind counts, merge status, and planned cleanup actions. Destructive archive is blocked for isolated git worktrees when:
+
+- the workspace is linked to any non-terminal issue
+- tracked files are modified
+- untracked files are present
+- commits are ahead of the base ref and not merged
+- git status cannot be inspected
+
+The lower-level cleanup helper also refuses to remove a git worktree when `git status --porcelain --untracked-files=all` is non-empty, so direct callers report dirty worktrees instead of deleting them. If a worktree is clean and Paperclip owns it, cleanup removes the git worktree and then attempts to delete the runtime-created branch with `git branch -d`; unmerged branches are reported and kept.
+
+Safe stale-worktree reporting should list, but not delete, candidate `/tmp` worktrees matching all of:
+
+- provider is `git_worktree`
+- workspace path resolves under `/tmp` or the platform temp directory
+- status is `idle`, `in_review`, or `cleanup_failed`, or `lastUsedAt` is older than the retention window
+- close-readiness is not `ready`
+
+Each row should include workspace id, issue identifier, owner agent if known, path, branch, base ref, opened/last-used time, approximate path size, readiness state, blocking reasons, and planned actions. Deletion is only allowed by the archive/close path after readiness returns `ready` or `ready_with_warnings`; blocked rows remain report-only.
+
+Successful release/completion behavior: when a Paperclip-owned isolated worktree is closed, the server archives the execution workspace record, stops attached runtime services, runs configured cleanup/teardown commands, removes the clean git worktree, and records any cleanup warning in `cleanupReason`. If release/completion does not explicitly archive the workspace, the stale-worktree report is the follow-up mechanism that makes the retention breach visible before manual or scheduled archive.
+
 ## Hidden UI entrypoints
 
 These are the current user-facing UI surfaces for the feature, now intentionally disabled:

server/src/__tests__/execution-workspaces-service.test.ts

@@ -343,7 +343,7 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {
     expect(readExecutionWorkspaceConfig(byId.get(untouchedWorkspaceId) ?? null)).toBeNull();
   });
 
-  it("warns about dirty and unmerged git worktrees and reports cleanup actions", async () => {
+  it("blocks destructive close for dirty and unmerged git worktrees", async () => {
     const repoRoot = await createTempRepo();
     tempDirs.add(repoRoot);
     const worktreePath = path.join(path.dirname(repoRoot), `paperclip-worktree-${randomUUID()}`);
@@ -416,10 +416,10 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {
 
     expect(readiness).toMatchObject({
       workspaceId: executionWorkspaceId,
-      state: "ready_with_warnings",
+      state: "blocked",
       isSharedWorkspace: false,
       isProjectPrimaryWorkspace: false,
-      isDestructiveCloseAllowed: true,
+      isDestructiveCloseAllowed: false,
       git: {
         workspacePath: worktreePath,
         branchName: "paperclip-close-check",
@@ -432,6 +432,10 @@ describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {
         isMergedIntoBase: false,
       },
     });
+    expect(readiness?.blockingReasons).toEqual(expect.arrayContaining([
+      "This git worktree has 1 untracked file; archive it after committing, stashing, or removing the file.",
+      "This git worktree has 1 unmerged commit ahead of main; push or merge it before archive cleanup.",
+    ]));
     expect(readiness?.warnings).toEqual(expect.arrayContaining([
       "The workspace has 1 untracked file.",
       "This workspace is 1 commit ahead of main and is not merged.",

server/src/__tests__/workspace-runtime.test.ts

@@ -1976,6 +1976,67 @@ describe("realizeExecutionWorkspace", () => {
     });
   }, 10_000);
 
+  it("reports dirty git worktrees instead of removing them during cleanup", async () => {
+    const repoRoot = await createTempRepo();
+
+    const workspace = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-452",
+        title: "Keep dirty worktree",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    await fs.writeFile(path.join(workspace.cwd, "scratch.txt"), "still here\n", "utf8");
+
+    const cleanup = await cleanupExecutionWorkspaceArtifacts({
+      workspace: {
+        id: "execution-workspace-1",
+        cwd: workspace.cwd,
+        providerType: "git_worktree",
+        providerRef: workspace.worktreePath,
+        branchName: workspace.branchName,
+        repoUrl: workspace.repoUrl,
+        baseRef: workspace.repoRef,
+        projectId: workspace.projectId,
+        projectWorkspaceId: workspace.workspaceId,
+        sourceIssueId: "issue-1",
+        metadata: {
+          createdByRuntime: true,
+        },
+      },
+      projectWorkspace: {
+        cwd: repoRoot,
+        cleanupCommand: null,
+      },
+    });
+
+    expect(cleanup.cleaned).toBe(false);
+    expect(cleanup.warnings).toEqual(expect.arrayContaining([
+      `Skipped removing git worktree "${workspace.cwd}" because it has uncommitted or untracked files.`,
+    ]));
+    await expect(fs.stat(path.join(workspace.cwd, "scratch.txt"))).resolves.toBeTruthy();
+  });
+
   it("records teardown and cleanup operations when a recorder is provided", async () => {
     const repoRoot = await createTempRepo();
     const { recorder, operations } = createWorkspaceOperationRecorderDouble();

server/src/services/execution-workspaces.ts

@@ -591,20 +591,41 @@ export function executionWorkspaceService(db: Db) {
             ? "The workspace has 1 modified tracked file."
             : `The workspace has ${git.dirtyEntryCount} modified tracked files.`,
         );
+        if (!isSharedWorkspace && executionWorkspace.providerType === "git_worktree") {
+          blockingReasons.push(
+            git.dirtyEntryCount === 1
+              ? "This git worktree has 1 modified tracked file; archive it after committing, stashing, or reverting the file."
+              : `This git worktree has ${git.dirtyEntryCount} modified tracked files; archive it after committing, stashing, or reverting the files.`,
+          );
+        }
       }
       if (git?.hasUntrackedFiles) {
         warnings.push(
           git.untrackedEntryCount === 1
             ? "The workspace has 1 untracked file."
             : `The workspace has ${git.untrackedEntryCount} untracked files.`,
         );
+        if (!isSharedWorkspace && executionWorkspace.providerType === "git_worktree") {
+          blockingReasons.push(
+            git.untrackedEntryCount === 1
+              ? "This git worktree has 1 untracked file; archive it after committing, stashing, or removing the file."
+              : `This git worktree has ${git.untrackedEntryCount} untracked files; archive it after committing, stashing, or removing the files.`,
+          );
+        }
       }
       if (git?.aheadCount && git.aheadCount > 0 && git.isMergedIntoBase === false) {
         warnings.push(
           git.aheadCount === 1
             ? `This workspace is 1 commit ahead of ${git.baseRef ?? "the base ref"} and is not merged.`
             : `This workspace is ${git.aheadCount} commits ahead of ${git.baseRef ?? "the base ref"} and is not merged.`,
         );
+        if (!isSharedWorkspace && executionWorkspace.providerType === "git_worktree") {
+          blockingReasons.push(
+            git.aheadCount === 1
+              ? `This git worktree has 1 unmerged commit ahead of ${git.baseRef ?? "the base ref"}; push or merge it before archive cleanup.`
+              : `This git worktree has ${git.aheadCount} unmerged commits ahead of ${git.baseRef ?? "the base ref"}; push or merge them before archive cleanup.`,
+          );
+        }
       }
       if (git?.behindCount && git.behindCount > 0) {
         warnings.push(

server/src/services/workspace-runtime.ts

@@ -1377,22 +1377,37 @@ export async function cleanupExecutionWorkspaceArtifacts(input: {
       if (!repoRoot) {
         warnings.push(`Could not resolve git repo root for "${workspacePath}".`);
       } else {
+        let gitStatus: string | null = null;
         try {
-          await recordGitOperation(input.recorder, {
-            phase: "worktree_cleanup",
-            args: ["worktree", "remove", "--force", workspacePath],
-            cwd: repoRoot,
-            metadata: {
-              workspaceId: input.workspace.id,
-              workspacePath,
-              branchName: input.workspace.branchName,
-              cleanupAction: "worktree_remove",
-            },
-            successMessage: `Removed git worktree ${workspacePath}\n`,
-            failureLabel: `git worktree remove ${workspacePath}`,
-          });
+          gitStatus = await runGit(["status", "--porcelain=v1", "--untracked-files=all"], workspacePath);
         } catch (err) {
-          warnings.push(err instanceof Error ? err.message : String(err));
+          warnings.push(
+            `Skipped removing git worktree "${workspacePath}" because Paperclip could not inspect git status: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          );
+        }
+
+        if (gitStatus && gitStatus.length > 0) {
+          warnings.push(`Skipped removing git worktree "${workspacePath}" because it has uncommitted or untracked files.`);
+        } else if (gitStatus === "") {
+          try {
+            await recordGitOperation(input.recorder, {
+              phase: "worktree_cleanup",
+              args: ["worktree", "remove", "--force", workspacePath],
+              cwd: repoRoot,
+              metadata: {
+                workspaceId: input.workspace.id,
+                workspacePath,
+                branchName: input.workspace.branchName,
+                cleanupAction: "worktree_remove",
+              },
+              successMessage: `Removed git worktree ${workspacePath}\n`,
+              failureLabel: `git worktree remove ${workspacePath}`,
+            });
+          } catch (err) {
+            warnings.push(err instanceof Error ? err.message : String(err));
+          }
         }
       }
     }