Add execution workspace close readiness and UI

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

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

@@ -1,9 +1,30 @@
-import { describe, expect, it } from "vitest";
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { promisify } from "node:util";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
+  companies,
+  createDb,
+  executionWorkspaces,
+  issues,
+  projectWorkspaces,
+  projects,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import {
+  executionWorkspaceService,
   mergeExecutionWorkspaceConfig,
   readExecutionWorkspaceConfig,
 } from "../services/execution-workspaces.ts";
 
+const execFileAsync = promisify(execFile);
+
 describe("execution workspace config helpers", () => {
   it("reads typed config from persisted metadata", () => {
     expect(readExecutionWorkspaceConfig({
@@ -70,3 +91,232 @@ describe("execution workspace config helpers", () => {
     });
   });
 });
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres execution workspace service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+async function runGit(cwd: string, args: string[]) {
+  await execFileAsync("git", ["-C", cwd, ...args], { cwd });
+}
+
+async function createTempRepo() {
+  const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-execution-workspace-"));
+  await runGit(repoRoot, ["init"]);
+  await runGit(repoRoot, ["config", "user.name", "Paperclip Test"]);
+  await runGit(repoRoot, ["config", "user.email", "test@paperclip.local"]);
+  await fs.writeFile(path.join(repoRoot, "README.md"), "# Test repo\n", "utf8");
+  await runGit(repoRoot, ["add", "README.md"]);
+  await runGit(repoRoot, ["commit", "-m", "Initial commit"]);
+  await runGit(repoRoot, ["branch", "-M", "main"]);
+  return repoRoot;
+}
+
+describeEmbeddedPostgres("executionWorkspaceService.getCloseReadiness", () => {
+  let db!: ReturnType<typeof createDb>;
+  let svc!: ReturnType<typeof executionWorkspaceService>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+  const tempDirs = new Set<string>();
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-execution-workspaces-service-");
+    db = createDb(tempDb.connectionString);
+    svc = executionWorkspaceService(db);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issues);
+    await db.delete(executionWorkspaces);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
+    await db.delete(companies);
+
+    for (const dir of tempDirs) {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+    tempDirs.clear();
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("blocks close for shared workspaces that still have open linked issues", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const executionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: "PAP",
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Workspaces",
+      status: "in_progress",
+      executionWorkspacePolicy: {
+        enabled: true,
+      },
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      sourceType: "local_path",
+      isPrimary: true,
+      cwd: "/tmp/paperclip-primary",
+    });
+    await db.insert(executionWorkspaces).values({
+      id: executionWorkspaceId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      mode: "shared_workspace",
+      strategyType: "project_primary",
+      name: "Shared workspace",
+      status: "active",
+      providerType: "local_fs",
+      cwd: "/tmp/paperclip-primary",
+      metadata: {
+        config: {
+          teardownCommand: "bash ./scripts/teardown.sh",
+        },
+      },
+    });
+    await db.insert(issues).values({
+      id: randomUUID(),
+      companyId,
+      projectId,
+      title: "Still working",
+      status: "todo",
+      priority: "medium",
+      executionWorkspaceId,
+    });
+
+    const readiness = await svc.getCloseReadiness(executionWorkspaceId);
+
+    expect(readiness).toMatchObject({
+      workspaceId: executionWorkspaceId,
+      state: "blocked",
+      isSharedWorkspace: true,
+      isProjectPrimaryWorkspace: true,
+      isDestructiveCloseAllowed: false,
+    });
+    expect(readiness?.blockingReasons).toEqual(expect.arrayContaining([
+      "This workspace is still linked to an open issue.",
+      "Shared execution workspaces are project infrastructure and cannot be destructively closed.",
+    ]));
+  });
+
+  it("warns about dirty and unmerged git worktrees and reports cleanup actions", async () => {
+    const repoRoot = await createTempRepo();
+    tempDirs.add(repoRoot);
+    const worktreePath = path.join(path.dirname(repoRoot), `paperclip-worktree-${randomUUID()}`);
+    tempDirs.add(worktreePath);
+
+    await runGit(repoRoot, ["branch", "paperclip-close-check"]);
+    await runGit(repoRoot, ["worktree", "add", worktreePath, "paperclip-close-check"]);
+    await fs.writeFile(path.join(worktreePath, "feature.txt"), "hello\n", "utf8");
+    await runGit(worktreePath, ["add", "feature.txt"]);
+    await runGit(worktreePath, ["commit", "-m", "Feature commit"]);
+    await fs.writeFile(path.join(worktreePath, "untracked.txt"), "left behind\n", "utf8");
+
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const executionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: "PAP",
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Workspaces",
+      status: "in_progress",
+      executionWorkspacePolicy: {
+        enabled: true,
+        workspaceStrategy: {
+          type: "git_worktree",
+          teardownCommand: "bash ./scripts/project-teardown.sh",
+        },
+      },
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      sourceType: "git_repo",
+      isPrimary: true,
+      cwd: repoRoot,
+      cleanupCommand: "printf 'project cleanup\\n'",
+    });
+    await db.insert(executionWorkspaces).values({
+      id: executionWorkspaceId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      mode: "isolated_workspace",
+      strategyType: "git_worktree",
+      name: "Feature workspace",
+      status: "active",
+      providerType: "git_worktree",
+      cwd: worktreePath,
+      providerRef: worktreePath,
+      branchName: "paperclip-close-check",
+      baseRef: "main",
+      metadata: {
+        createdByRuntime: true,
+        config: {
+          cleanupCommand: "printf 'workspace cleanup\\n'",
+        },
+      },
+    });
+
+    const readiness = await svc.getCloseReadiness(executionWorkspaceId);
+
+    expect(readiness).toMatchObject({
+      workspaceId: executionWorkspaceId,
+      state: "ready_with_warnings",
+      isSharedWorkspace: false,
+      isProjectPrimaryWorkspace: true,
+      isDestructiveCloseAllowed: true,
+      git: {
+        workspacePath: worktreePath,
+        branchName: "paperclip-close-check",
+        baseRef: "main",
+        createdByRuntime: true,
+        hasDirtyTrackedFiles: false,
+        hasUntrackedFiles: true,
+        aheadCount: 1,
+        behindCount: 0,
+        isMergedIntoBase: false,
+      },
+    });
+    expect(readiness?.warnings).toEqual(expect.arrayContaining([
+      "The workspace has 1 untracked file.",
+      "This workspace is 1 commit ahead of main and is not merged.",
+    ]));
+    expect(readiness?.plannedActions.map((action) => action.kind)).toEqual(expect.arrayContaining([
+      "archive_record",
+      "cleanup_command",
+      "teardown_command",
+      "git_worktree_remove",
+      "git_branch_delete",
+    ]));
+  }, 20_000);
+});

server/src/routes/execution-workspaces.ts

@@ -1,7 +1,7 @@
 import { and, eq } from "drizzle-orm";
 import { Router } from "express";
 import type { Db } from "@paperclipai/db";
-import { issues, projects, projectWorkspaces } from "@paperclipai/db";
+import { projects, projectWorkspaces } from "@paperclipai/db";
 import { updateExecutionWorkspaceSchema } from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
 import { executionWorkspaceService, logActivity, workspaceOperationService } from "../services/index.js";
@@ -13,8 +13,6 @@ import {
 } from "../services/workspace-runtime.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
 
-const TERMINAL_ISSUE_STATUSES = new Set(["done", "cancelled"]);
-
 export function executionWorkspaceRoutes(db: Db) {
   const router = Router();
   const svc = executionWorkspaceService(db);
@@ -44,6 +42,22 @@ export function executionWorkspaceRoutes(db: Db) {
     res.json(workspace);
   });
 
+  router.get("/execution-workspaces/:id/close-readiness", async (req, res) => {
+    const id = req.params.id as string;
+    const workspace = await svc.getById(id);
+    if (!workspace) {
+      res.status(404).json({ error: "Execution workspace not found" });
+      return;
+    }
+    assertCompanyAccess(req, workspace.companyId);
+    const readiness = await svc.getCloseReadiness(id);
+    if (!readiness) {
+      res.status(404).json({ error: "Execution workspace not found" });
+      return;
+    }
+    res.json(readiness);
+  });
+
   router.patch("/execution-workspaces/:id", validate(updateExecutionWorkspaceSchema), async (req, res) => {
     const id = req.params.id as string;
     const existing = await svc.getById(id);
@@ -80,18 +94,16 @@ export function executionWorkspaceRoutes(db: Db) {
     );
 
     if (req.body.status === "archived" && existing.status !== "archived") {
-      const linkedIssues = await db
-        .select({
-          id: issues.id,
-          status: issues.status,
-        })
-        .from(issues)
-        .where(and(eq(issues.companyId, existing.companyId), eq(issues.executionWorkspaceId, existing.id)));
-      const activeLinkedIssues = linkedIssues.filter((issue) => !TERMINAL_ISSUE_STATUSES.has(issue.status));
+      const readiness = await svc.getCloseReadiness(existing.id);
+      if (!readiness) {
+        res.status(404).json({ error: "Execution workspace not found" });
+        return;
+      }
 
-      if (activeLinkedIssues.length > 0) {
+      if (readiness.state === "blocked") {
         res.status(409).json({
-          error: `Cannot archive execution workspace while ${activeLinkedIssues.length} linked issue(s) are still open`,
+          error: readiness.blockingReasons[0] ?? "Execution workspace cannot be closed right now",
+          closeReadiness: readiness,
         });
         return;
       }

server/src/services/execution-workspaces.ts

@@ -1,10 +1,24 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
 import { and, desc, eq, inArray } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import { executionWorkspaces, workspaceRuntimeServices } from "@paperclipai/db";
-import type { ExecutionWorkspace, ExecutionWorkspaceConfig, WorkspaceRuntimeService } from "@paperclipai/shared";
+import { executionWorkspaces, issues, projects, projectWorkspaces, workspaceRuntimeServices } from "@paperclipai/db";
+import type {
+  ExecutionWorkspace,
+  ExecutionWorkspaceCloseAction,
+  ExecutionWorkspaceCloseGitReadiness,
+  ExecutionWorkspaceCloseReadiness,
+  ExecutionWorkspaceConfig,
+  WorkspaceRuntimeService,
+} from "@paperclipai/shared";
+import { parseProjectExecutionWorkspacePolicy } from "./execution-workspace-policy.js";
 
 type ExecutionWorkspaceRow = typeof executionWorkspaces.$inferSelect;
 type WorkspaceRuntimeServiceRow = typeof workspaceRuntimeServices.$inferSelect;
+const execFileAsync = promisify(execFile);
+const TERMINAL_ISSUE_STATUSES = new Set(["done", "cancelled"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -21,6 +35,149 @@ function cloneRecord(value: unknown): Record<string, unknown> | null {
   return { ...value };
 }
 
+async function pathExists(value: string | null | undefined) {
+  if (!value) return false;
+  try {
+    await fs.access(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runGit(args: string[], cwd: string) {
+  return await execFileAsync("git", ["-C", cwd, ...args], { cwd });
+}
+
+async function inspectGitCloseReadiness(workspace: ExecutionWorkspace): Promise<{
+  git: ExecutionWorkspaceCloseGitReadiness | null;
+  warnings: string[];
+}> {
+  const warnings: string[] = [];
+  const workspacePath = readNullableString(workspace.providerRef) ?? readNullableString(workspace.cwd);
+  const createdByRuntime = workspace.metadata?.createdByRuntime === true;
+  const expectsGitInspection =
+    workspace.providerType === "git_worktree" ||
+    Boolean(workspace.repoUrl || workspace.baseRef || workspace.branchName || workspacePath);
+
+  if (!expectsGitInspection) {
+    return { git: null, warnings };
+  }
+
+  if (!workspacePath) {
+    warnings.push("Workspace has no local path, so Paperclip cannot inspect git status before close.");
+    return { git: null, warnings };
+  }
+
+  if (!(await pathExists(workspacePath))) {
+    warnings.push(`Workspace path "${workspacePath}" does not exist, so Paperclip cannot inspect git status before close.`);
+    return {
+      git: {
+        repoRoot: null,
+        workspacePath,
+        branchName: workspace.branchName,
+        baseRef: workspace.baseRef,
+        hasDirtyTrackedFiles: false,
+        hasUntrackedFiles: false,
+        dirtyEntryCount: 0,
+        untrackedEntryCount: 0,
+        aheadCount: null,
+        behindCount: null,
+        isMergedIntoBase: null,
+        createdByRuntime,
+      },
+      warnings,
+    };
+  }
+
+  let repoRoot: string | null = null;
+  try {
+    repoRoot = (await runGit(["rev-parse", "--show-toplevel"], workspacePath)).stdout.trim() || null;
+  } catch (error) {
+    warnings.push(
+      `Could not inspect git status for "${workspacePath}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  let branchName = workspace.branchName;
+  if (repoRoot && !branchName) {
+    try {
+      branchName = (await runGit(["rev-parse", "--abbrev-ref", "HEAD"], workspacePath)).stdout.trim() || null;
+    } catch {
+      branchName = workspace.branchName;
+    }
+  }
+
+  let dirtyEntryCount = 0;
+  let untrackedEntryCount = 0;
+  if (repoRoot) {
+    try {
+      const statusOutput = (await runGit(["status", "--porcelain=v1", "--untracked-files=all"], workspacePath)).stdout;
+      for (const line of statusOutput.split(/\r?\n/)) {
+        if (!line) continue;
+        if (line.startsWith("??")) {
+          untrackedEntryCount += 1;
+          continue;
+        }
+        dirtyEntryCount += 1;
+      }
+    } catch (error) {
+      warnings.push(
+        `Could not read git working tree status for "${workspacePath}": ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  let aheadCount: number | null = null;
+  let behindCount: number | null = null;
+  let isMergedIntoBase: boolean | null = null;
+  const baseRef = workspace.baseRef;
+
+  if (repoRoot && baseRef) {
+    try {
+      const counts = (await runGit(["rev-list", "--left-right", "--count", `${baseRef}...HEAD`], workspacePath)).stdout.trim();
+      const [behindRaw, aheadRaw] = counts.split(/\s+/);
+      behindCount = behindRaw ? Number.parseInt(behindRaw, 10) : 0;
+      aheadCount = aheadRaw ? Number.parseInt(aheadRaw, 10) : 0;
+    } catch (error) {
+      warnings.push(
+        `Could not compare this workspace against ${baseRef}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    try {
+      await runGit(["merge-base", "--is-ancestor", "HEAD", baseRef], workspacePath);
+      isMergedIntoBase = true;
+    } catch (error) {
+      const code = typeof error === "object" && error && "code" in error ? (error as { code?: unknown }).code : null;
+      if (code === 1) isMergedIntoBase = false;
+      else {
+        warnings.push(
+          `Could not determine whether this workspace is merged into ${baseRef}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+  }
+
+  return {
+    git: {
+      repoRoot,
+      workspacePath,
+      branchName,
+      baseRef,
+      hasDirtyTrackedFiles: dirtyEntryCount > 0,
+      hasUntrackedFiles: untrackedEntryCount > 0,
+      dirtyEntryCount,
+      untrackedEntryCount,
+      aheadCount,
+      behindCount,
+      isMergedIntoBase,
+      createdByRuntime,
+    },
+    warnings,
+  };
+}
+
 export function readExecutionWorkspaceConfig(metadata: Record<string, unknown> | null | undefined): ExecutionWorkspaceConfig | null {
   const raw = isRecord(metadata?.config) ? metadata.config : null;
   if (!raw) return null;
@@ -198,6 +355,250 @@ export function executionWorkspaceService(db: Db) {
       return toExecutionWorkspace(row, runtimeServiceRows.map(toRuntimeService));
     },
 
+    getCloseReadiness: async (id: string): Promise<ExecutionWorkspaceCloseReadiness | null> => {
+      const workspace = await db
+        .select()
+        .from(executionWorkspaces)
+        .where(eq(executionWorkspaces.id, id))
+        .then((rows) => rows[0] ?? null);
+      if (!workspace) return null;
+
+      const runtimeServiceRows = await db
+        .select()
+        .from(workspaceRuntimeServices)
+        .where(eq(workspaceRuntimeServices.executionWorkspaceId, workspace.id))
+        .orderBy(desc(workspaceRuntimeServices.updatedAt), desc(workspaceRuntimeServices.createdAt));
+      const runtimeServices = runtimeServiceRows.map(toRuntimeService);
+
+      const linkedIssues = await db
+        .select({
+          id: issues.id,
+          identifier: issues.identifier,
+          title: issues.title,
+          status: issues.status,
+        })
+        .from(issues)
+        .where(and(eq(issues.companyId, workspace.companyId), eq(issues.executionWorkspaceId, workspace.id)));
+
+      const projectWorkspace = workspace.projectWorkspaceId
+        ? await db
+            .select({
+              id: projectWorkspaces.id,
+              cwd: projectWorkspaces.cwd,
+              cleanupCommand: projectWorkspaces.cleanupCommand,
+              isPrimary: projectWorkspaces.isPrimary,
+            })
+            .from(projectWorkspaces)
+            .where(
+              and(
+                eq(projectWorkspaces.companyId, workspace.companyId),
+                eq(projectWorkspaces.id, workspace.projectWorkspaceId),
+              ),
+            )
+            .then((rows) => rows[0] ?? null)
+        : null;
+
+      const primaryProjectWorkspace = workspace.projectId
+        ? await db
+            .select({
+              id: projectWorkspaces.id,
+            })
+            .from(projectWorkspaces)
+            .where(
+              and(
+                eq(projectWorkspaces.companyId, workspace.companyId),
+                eq(projectWorkspaces.projectId, workspace.projectId),
+                eq(projectWorkspaces.isPrimary, true),
+              ),
+            )
+            .then((rows) => rows[0] ?? null)
+        : null;
+
+      const projectPolicy = workspace.projectId
+        ? await db
+            .select({
+              executionWorkspacePolicy: projects.executionWorkspacePolicy,
+            })
+            .from(projects)
+            .where(and(eq(projects.id, workspace.projectId), eq(projects.companyId, workspace.companyId)))
+            .then((rows) => parseProjectExecutionWorkspacePolicy(rows[0]?.executionWorkspacePolicy))
+        : null;
+
+      const executionWorkspace = toExecutionWorkspace(workspace, runtimeServices);
+      const config = readExecutionWorkspaceConfig((workspace.metadata as Record<string, unknown> | null) ?? null);
+      const { git, warnings: gitWarnings } = await inspectGitCloseReadiness(executionWorkspace);
+      const warnings = [...gitWarnings];
+      const blockingReasons: string[] = [];
+      const isSharedWorkspace = executionWorkspace.mode === "shared_workspace";
+      const isProjectPrimaryWorkspace = workspace.projectWorkspaceId != null && workspace.projectWorkspaceId === primaryProjectWorkspace?.id;
+
+      const linkedIssueSummaries = linkedIssues.map((issue) => ({
+        ...issue,
+        isTerminal: TERMINAL_ISSUE_STATUSES.has(issue.status),
+      }));
+
+      const blockingIssues = linkedIssueSummaries.filter((issue) => !issue.isTerminal);
+      if (blockingIssues.length > 0) {
+        blockingReasons.push(
+          blockingIssues.length === 1
+            ? "This workspace is still linked to an open issue."
+            : `This workspace is still linked to ${blockingIssues.length} open issues.`,
+        );
+      }
+
+      if (isSharedWorkspace) {
+        blockingReasons.push("Shared execution workspaces are project infrastructure and cannot be destructively closed.");
+      }
+
+      if (runtimeServices.some((service) => service.status !== "stopped")) {
+        warnings.push(
+          runtimeServices.length === 1
+            ? "Closing this workspace will stop 1 attached runtime service."
+            : `Closing this workspace will stop ${runtimeServices.length} attached runtime services.`,
+        );
+      }
+
+      if (git?.hasDirtyTrackedFiles) {
+        warnings.push(
+          git.dirtyEntryCount === 1
+            ? "The workspace has 1 modified tracked file."
+            : `The workspace has ${git.dirtyEntryCount} modified tracked files.`,
+        );
+      }
+      if (git?.hasUntrackedFiles) {
+        warnings.push(
+          git.untrackedEntryCount === 1
+            ? "The workspace has 1 untracked file."
+            : `The workspace has ${git.untrackedEntryCount} untracked 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 (git?.behindCount && git.behindCount > 0) {
+        warnings.push(
+          git.behindCount === 1
+            ? `This workspace is 1 commit behind ${git.baseRef ?? "the base ref"}.`
+            : `This workspace is ${git.behindCount} commits behind ${git.baseRef ?? "the base ref"}.`,
+        );
+      }
+
+      const plannedActions: ExecutionWorkspaceCloseAction[] = [
+        {
+          kind: "archive_record",
+          label: "Archive workspace record",
+          description: "Keep the execution workspace history and issue linkage, but remove it from active workspace lists.",
+          command: null,
+        },
+      ];
+
+      if (runtimeServices.some((service) => service.status !== "stopped")) {
+        plannedActions.push({
+          kind: "stop_runtime_services",
+          label: runtimeServices.length === 1 ? "Stop attached runtime service" : "Stop attached runtime services",
+          description:
+            runtimeServices.length === 1
+              ? `${runtimeServices[0]?.serviceName ?? "A runtime service"} will be stopped before cleanup.`
+              : `${runtimeServices.length} runtime services will be stopped before cleanup.`,
+          command: null,
+        });
+      }
+
+      const configuredCleanupCommands = [
+        {
+          kind: "cleanup_command" as const,
+          label: "Run workspace cleanup command",
+          description: "Workspace-specific cleanup runs before teardown.",
+          command: config?.cleanupCommand ?? null,
+        },
+        {
+          kind: "cleanup_command" as const,
+          label: "Run project workspace cleanup command",
+          description: "Project workspace cleanup runs before execution workspace teardown.",
+          command: projectWorkspace?.cleanupCommand ?? null,
+        },
+      ];
+      for (const action of configuredCleanupCommands) {
+        if (!action.command) continue;
+        plannedActions.push(action);
+      }
+
+      const teardownCommand = config?.teardownCommand ?? projectPolicy?.workspaceStrategy?.teardownCommand ?? null;
+      if (teardownCommand) {
+        plannedActions.push({
+          kind: "teardown_command",
+          label: "Run teardown command",
+          description: "Teardown runs after cleanup commands during workspace close.",
+          command: teardownCommand,
+        });
+      }
+
+      const workspacePath = readNullableString(executionWorkspace.providerRef) ?? readNullableString(executionWorkspace.cwd);
+      if (executionWorkspace.providerType === "git_worktree" && workspacePath) {
+        plannedActions.push({
+          kind: "git_worktree_remove",
+          label: "Remove git worktree",
+          description: `Paperclip will run git worktree cleanup for ${workspacePath}.`,
+          command: `git worktree remove --force ${workspacePath}`,
+        });
+      }
+
+      if (git?.createdByRuntime && executionWorkspace.branchName) {
+        plannedActions.push({
+          kind: "git_branch_delete",
+          label: "Delete runtime-created branch",
+          description: "Paperclip will try to delete the runtime-created branch after removing the worktree.",
+          command: `git branch -d ${executionWorkspace.branchName}`,
+        });
+      }
+
+      if (executionWorkspace.providerType === "local_fs" && git?.createdByRuntime && workspacePath) {
+        const resolvedWorkspacePath = path.resolve(workspacePath);
+        const resolvedProjectWorkspacePath = projectWorkspace?.cwd ? path.resolve(projectWorkspace.cwd) : null;
+        const containsProjectWorkspace = resolvedProjectWorkspacePath
+          ? (
+              resolvedWorkspacePath === resolvedProjectWorkspacePath ||
+              resolvedProjectWorkspacePath.startsWith(`${resolvedWorkspacePath}${path.sep}`)
+            )
+          : false;
+        if (containsProjectWorkspace) {
+          warnings.push(`Paperclip will archive this workspace but keep "${workspacePath}" because it contains the project workspace.`);
+        } else {
+          plannedActions.push({
+            kind: "remove_local_directory",
+            label: "Remove runtime-created directory",
+            description: `Paperclip will remove the runtime-created directory at ${workspacePath}.`,
+            command: `rm -rf ${workspacePath}`,
+          });
+        }
+      }
+
+      const state =
+        blockingReasons.length > 0
+          ? "blocked"
+          : warnings.length > 0
+            ? "ready_with_warnings"
+            : "ready";
+
+      return {
+        workspaceId: workspace.id,
+        state,
+        blockingReasons,
+        warnings,
+        linkedIssues: linkedIssueSummaries,
+        plannedActions,
+        isDestructiveCloseAllowed: blockingReasons.length === 0,
+        isSharedWorkspace,
+        isProjectPrimaryWorkspace,
+        git,
+        runtimeServices,
+      };
+    },
+
     create: async (data: typeof executionWorkspaces.$inferInsert) => {
       const row = await db
         .insert(executionWorkspaces)