Merge public-gh/master into PAP-881-document-revisions-bulid-it

server/src/__tests__/adapter-models.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { models as codexFallbackModels } from "@paperclipai/adapter-codex-local";
 import { models as cursorFallbackModels } from "@paperclipai/adapter-cursor-local";
+import { models as opencodeFallbackModels } from "@paperclipai/adapter-opencode-local";
 import { resetOpenCodeModelsCacheForTests } from "@paperclipai/adapter-opencode-local/server";
 import { listAdapterModels } from "../adapters/index.js";
 import { resetCodexModelsCacheForTests } from "../adapters/codex-models.js";
@@ -76,6 +77,14 @@ describe("adapter model listing", () => {
     expect(models).toEqual(cursorFallbackModels);
   });
 
+  it("returns opencode fallback models including gpt-5.4", async () => {
+    process.env.PAPERCLIP_OPENCODE_COMMAND = "__paperclip_missing_opencode_command__";
+
+    const models = await listAdapterModels("opencode_local");
+
+    expect(models).toEqual(opencodeFallbackModels);
+  });
+
   it("loads cursor models dynamically and caches them", async () => {
     const runner = vi.fn(() => ({
       status: 0,
@@ -95,10 +104,4 @@ describe("adapter model listing", () => {
     expect(first.some((model) => model.id === "composer-1")).toBe(true);
   });
 
-  it("returns no opencode models when opencode command is unavailable", async () => {
-    process.env.PAPERCLIP_OPENCODE_COMMAND = "__paperclip_missing_opencode_command__";
-
-    const models = await listAdapterModels("opencode_local");
-    expect(models).toEqual([]);
-  });
 });

server/src/__tests__/agent-permissions-routes.test.ts

@@ -1,6 +1,7 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { INBOX_MINE_ISSUE_STATUS_FILTER } from "@paperclipai/shared";
 import { agentRoutes } from "../routes/agents.js";
 import { errorHandler } from "../middleware/index.js";
 
@@ -272,4 +273,42 @@ describe("agent permission routes", () => {
     expect(res.body.access.canAssignTasks).toBe(true);
     expect(res.body.access.taskAssignSource).toBe("agent_creator");
   });
+
+  it("exposes a dedicated agent route for the inbox mine view", async () => {
+    mockIssueService.list.mockResolvedValue([
+      {
+        id: "issue-1",
+        identifier: "PAP-910",
+        title: "Inbox follow-up",
+        status: "todo",
+      },
+    ]);
+
+    const app = createApp({
+      type: "agent",
+      agentId,
+      companyId,
+      runId: "run-1",
+      source: "agent_key",
+    });
+
+    const res = await request(app)
+      .get("/api/agents/me/inbox/mine")
+      .query({ userId: "board-user" });
+
+    expect(res.status).toBe(200);
+    expect(mockIssueService.list).toHaveBeenCalledWith(companyId, {
+      touchedByUserId: "board-user",
+      inboxArchivedByUserId: "board-user",
+      status: INBOX_MINE_ISSUE_STATUS_FILTER,
+    });
+    expect(res.body).toEqual([
+      {
+        id: "issue-1",
+        identifier: "PAP-910",
+        title: "Inbox follow-up",
+        status: "todo",
+      },
+    ]);
+  });
 });

server/src/__tests__/board-mutation-guard.test.ts

@@ -84,6 +84,28 @@ describe("boardMutationGuard", () => {
     expect(res.status).toBe(204);
   });
 
+  it("allows board mutations when x-forwarded-host matches origin", async () => {
+    const app = createApp("board");
+    const res = await request(app)
+      .post("/mutate")
+      .set("Host", "127.0.0.1")
+      .set("X-Forwarded-Host", "10.90.10.20:3443")
+      .set("Origin", "https://10.90.10.20:3443")
+      .send({ ok: true });
+    expect(res.status).toBe(204);
+  });
+
+  it("blocks board mutations when x-forwarded-host does not match origin", async () => {
+    const app = createApp("board");
+    const res = await request(app)
+      .post("/mutate")
+      .set("Host", "127.0.0.1")
+      .set("X-Forwarded-Host", "10.90.10.20:3443")
+      .set("Origin", "https://evil.example.com")
+      .send({ ok: true });
+    expect(res.status).toBe(403);
+  });
+
   it("does not block authenticated agent mutations", async () => {
     const middleware = boardMutationGuard();
     const req = {

server/src/__tests__/claude-local-adapter.test.ts

@@ -1,5 +1,7 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { isClaudeMaxTurnsResult } from "@paperclipai/adapter-claude-local/server";
+import { parseClaudeStdoutLine } from "@paperclipai/adapter-claude-local/ui";
+import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
 
 describe("claude_local max-turn detection", () => {
   it("detects max-turn exhaustion by subtype", () => {
@@ -28,3 +30,158 @@ describe("claude_local max-turn detection", () => {
     ).toBe(false);
   });
 });
+
+describe("claude_local ui stdout parser", () => {
+  it("maps assistant text, thinking, tool calls, and tool results into transcript entries", () => {
+    const ts = "2026-03-29T00:00:00.000Z";
+
+    expect(
+      parseClaudeStdoutLine(
+        JSON.stringify({
+          type: "system",
+          subtype: "init",
+          model: "claude-sonnet-4-6",
+          session_id: "claude-session-1",
+        }),
+        ts,
+      ),
+    ).toEqual([
+      {
+        kind: "init",
+        ts,
+        model: "claude-sonnet-4-6",
+        sessionId: "claude-session-1",
+      },
+    ]);
+
+    expect(
+      parseClaudeStdoutLine(
+        JSON.stringify({
+          type: "assistant",
+          session_id: "claude-session-1",
+          message: {
+            content: [
+              { type: "text", text: "I will inspect the repo." },
+              { type: "thinking", thinking: "Checking the adapter wiring" },
+              { type: "tool_use", id: "tool_1", name: "bash", input: { command: "ls -1" } },
+            ],
+          },
+        }),
+        ts,
+      ),
+    ).toEqual([
+      { kind: "assistant", ts, text: "I will inspect the repo." },
+      { kind: "thinking", ts, text: "Checking the adapter wiring" },
+      { kind: "tool_call", ts, name: "bash", toolUseId: "tool_1", input: { command: "ls -1" } },
+    ]);
+
+    expect(
+      parseClaudeStdoutLine(
+        JSON.stringify({
+          type: "user",
+          message: {
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: "tool_1",
+                content: [{ type: "text", text: "AGENTS.md\nREADME.md" }],
+                is_error: false,
+              },
+            ],
+          },
+        }),
+        ts,
+      ),
+    ).toEqual([
+      {
+        kind: "tool_result",
+        ts,
+        toolUseId: "tool_1",
+        content: "AGENTS.md\nREADME.md",
+        isError: false,
+      },
+    ]);
+  });
+});
+
+function stripAnsi(value: string) {
+  return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+describe("claude_local cli formatter", () => {
+  it("prints the user-visible and background transcript events from stream-json output", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      printClaudeStreamEvent(
+        JSON.stringify({
+          type: "system",
+          subtype: "init",
+          model: "claude-sonnet-4-6",
+          session_id: "claude-session-1",
+        }),
+        false,
+      );
+      printClaudeStreamEvent(
+        JSON.stringify({
+          type: "assistant",
+          message: {
+            content: [
+              { type: "text", text: "I will inspect the repo." },
+              { type: "thinking", thinking: "Checking the adapter wiring" },
+              { type: "tool_use", id: "tool_1", name: "bash", input: { command: "ls -1" } },
+            ],
+          },
+        }),
+        false,
+      );
+      printClaudeStreamEvent(
+        JSON.stringify({
+          type: "user",
+          message: {
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: "tool_1",
+                content: [{ type: "text", text: "AGENTS.md\nREADME.md" }],
+                is_error: false,
+              },
+            ],
+          },
+        }),
+        false,
+      );
+      printClaudeStreamEvent(
+        JSON.stringify({
+          type: "result",
+          subtype: "success",
+          result: "Done",
+          usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 2 },
+          total_cost_usd: 0.00042,
+        }),
+        false,
+      );
+
+      const lines = spy.mock.calls
+        .map((call) => call.map((value) => String(value)).join(" "))
+        .map(stripAnsi);
+
+      expect(lines).toEqual(
+        expect.arrayContaining([
+          "Claude initialized (model: claude-sonnet-4-6, session: claude-session-1)",
+          "assistant: I will inspect the repo.",
+          "thinking: Checking the adapter wiring",
+          "tool_call: bash",
+          '{\n  "command": "ls -1"\n}',
+          "tool_result",
+          "AGENTS.md\nREADME.md",
+          "result:",
+          "Done",
+          "tokens: in=10 out=5 cached=2 cost=$0.000420",
+        ]),
+      );
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

server/src/__tests__/claude-local-execute.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execute } from "@paperclipai/adapter-claude-local/server";
+
+async function writeFakeClaudeCommand(commandPath: string): Promise<void> {
+  const script = `#!/usr/bin/env node
+const fs = require("node:fs");
+
+const capturePath = process.env.PAPERCLIP_TEST_CAPTURE_PATH;
+const payload = {
+  argv: process.argv.slice(2),
+  prompt: fs.readFileSync(0, "utf8"),
+  claudeConfigDir: process.env.CLAUDE_CONFIG_DIR || null,
+};
+if (capturePath) {
+  fs.writeFileSync(capturePath, JSON.stringify(payload), "utf8");
+}
+console.log(JSON.stringify({ type: "system", subtype: "init", session_id: "claude-session-1", model: "claude-sonnet" }));
+console.log(JSON.stringify({ type: "assistant", session_id: "claude-session-1", message: { content: [{ type: "text", text: "hello" }] } }));
+console.log(JSON.stringify({ type: "result", session_id: "claude-session-1", result: "hello", usage: { input_tokens: 1, cache_read_input_tokens: 0, output_tokens: 1 } }));
+`;
+  await fs.writeFile(commandPath, script, "utf8");
+  await fs.chmod(commandPath, 0o755);
+}
+
+describe("claude execute", () => {
+  it("logs HOME, CLAUDE_CONFIG_DIR, and the resolved executable path in invocation metadata", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-execute-meta-"));
+    const workspace = path.join(root, "workspace");
+    const binDir = path.join(root, "bin");
+    const commandPath = path.join(binDir, "claude");
+    const capturePath = path.join(root, "capture.json");
+    const claudeConfigDir = path.join(root, "claude-config");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.mkdir(binDir, { recursive: true });
+    await fs.mkdir(claudeConfigDir, { recursive: true });
+    await writeFakeClaudeCommand(commandPath);
+
+    const previousHome = process.env.HOME;
+    const previousPath = process.env.PATH;
+    const previousClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.HOME = root;
+    process.env.PATH = `${binDir}${path.delimiter}${process.env.PATH ?? ""}`;
+    process.env.CLAUDE_CONFIG_DIR = claudeConfigDir;
+
+    let loggedCommand: string | null = null;
+    let loggedEnv: Record<string, string> = {};
+    try {
+      const result = await execute({
+        runId: "run-meta",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Claude Coder",
+          adapterType: "claude_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: "claude",
+          cwd: workspace,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+        onMeta: async (meta) => {
+          loggedCommand = meta.command;
+          loggedEnv = meta.env ?? {};
+        },
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.errorMessage).toBeNull();
+      expect(loggedCommand).toBe(commandPath);
+      expect(loggedEnv.HOME).toBe(root);
+      expect(loggedEnv.CLAUDE_CONFIG_DIR).toBe(claudeConfigDir);
+      expect(loggedEnv.PAPERCLIP_RESOLVED_COMMAND).toBe(commandPath);
+    } finally {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+      if (previousClaudeConfigDir === undefined) delete process.env.CLAUDE_CONFIG_DIR;
+      else process.env.CLAUDE_CONFIG_DIR = previousClaudeConfigDir;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});

server/src/__tests__/codex-local-execute.test.ts

@@ -195,6 +195,70 @@ describe("codex execute", () => {
     }
   });
 
+  it("logs HOME and the resolved executable path in invocation metadata", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-execute-meta-"));
+    const workspace = path.join(root, "workspace");
+    const binDir = path.join(root, "bin");
+    const commandPath = path.join(binDir, "codex");
+    const capturePath = path.join(root, "capture.json");
+    await fs.mkdir(workspace, { recursive: true });
+    await fs.mkdir(binDir, { recursive: true });
+    await writeFakeCodexCommand(commandPath);
+
+    const previousHome = process.env.HOME;
+    const previousPath = process.env.PATH;
+    process.env.HOME = root;
+    process.env.PATH = `${binDir}${path.delimiter}${process.env.PATH ?? ""}`;
+
+    let loggedCommand: string | null = null;
+    let loggedEnv: Record<string, string> = {};
+    try {
+      const result = await execute({
+        runId: "run-meta",
+        agent: {
+          id: "agent-1",
+          companyId: "company-1",
+          name: "Codex Coder",
+          adapterType: "codex_local",
+          adapterConfig: {},
+        },
+        runtime: {
+          sessionId: null,
+          sessionParams: null,
+          sessionDisplayId: null,
+          taskKey: null,
+        },
+        config: {
+          command: "codex",
+          cwd: workspace,
+          env: {
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath,
+          },
+          promptTemplate: "Follow the paperclip heartbeat.",
+        },
+        context: {},
+        authToken: "run-jwt-token",
+        onLog: async () => {},
+        onMeta: async (meta) => {
+          loggedCommand = meta.command;
+          loggedEnv = meta.env ?? {};
+        },
+      });
+
+      expect(result.exitCode).toBe(0);
+      expect(result.errorMessage).toBeNull();
+      expect(loggedCommand).toBe(commandPath);
+      expect(loggedEnv.HOME).toBe(root);
+      expect(loggedEnv.PAPERCLIP_RESOLVED_COMMAND).toBe(commandPath);
+    } finally {
+      if (previousHome === undefined) delete process.env.HOME;
+      else process.env.HOME = previousHome;
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("uses a worktree-isolated CODEX_HOME while preserving shared auth and config", async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-execute-"));
     const workspace = path.join(root, "workspace");

server/src/__tests__/dev-watch-ignore.test.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveServerDevWatchIgnorePaths } from "../dev-watch-ignore.js";
+
+describe("resolveServerDevWatchIgnorePaths", () => {
+  it("includes both the worktree UI paths and their real shared targets", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-dev-watch-"));
+    const sharedUiRoot = path.join(tempRoot, "shared-ui");
+    const worktreeRoot = path.join(tempRoot, "repo", ".paperclip", "worktrees", "PAP-884");
+    const serverRoot = path.join(worktreeRoot, "server");
+    const worktreeUiRoot = path.join(worktreeRoot, "ui");
+
+    fs.mkdirSync(path.join(sharedUiRoot, "node_modules"), { recursive: true });
+    fs.mkdirSync(path.join(sharedUiRoot, ".vite"), { recursive: true });
+    fs.mkdirSync(path.join(sharedUiRoot, "dist"), { recursive: true });
+    fs.mkdirSync(serverRoot, { recursive: true });
+    fs.mkdirSync(worktreeUiRoot, { recursive: true });
+
+    fs.symlinkSync(path.join(sharedUiRoot, "node_modules"), path.join(worktreeUiRoot, "node_modules"));
+    fs.symlinkSync(path.join(sharedUiRoot, ".vite"), path.join(worktreeUiRoot, ".vite"));
+    fs.symlinkSync(path.join(sharedUiRoot, "dist"), path.join(worktreeUiRoot, "dist"));
+
+    const ignorePaths = resolveServerDevWatchIgnorePaths(serverRoot);
+
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, "node_modules"));
+    expect(ignorePaths).toContain(`${path.join(worktreeUiRoot, "node_modules").replaceAll(path.sep, "/")}/**`);
+    expect(ignorePaths).toContain(fs.realpathSync(path.join(sharedUiRoot, "node_modules")));
+    expect(ignorePaths).toContain(`${fs.realpathSync(path.join(sharedUiRoot, "node_modules")).replaceAll(path.sep, "/")}/**`);
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, "node_modules", ".vite-temp"));
+    expect(ignorePaths).toContain(
+      `${path.join(worktreeUiRoot, "node_modules", ".vite-temp").replaceAll(path.sep, "/")}/**`,
+    );
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, ".vite"));
+    expect(ignorePaths).toContain(fs.realpathSync(path.join(sharedUiRoot, ".vite")));
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, "dist"));
+    expect(ignorePaths).toContain(fs.realpathSync(path.join(sharedUiRoot, "dist")));
+    expect(ignorePaths).toContain("**/{node_modules,bower_components,vendor}/**");
+    expect(ignorePaths).toContain("**/.vite-temp/**");
+  });
+});

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

@@ -0,0 +1,325 @@
+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({
+      source: "project_primary",
+      config: {
+        provisionCommand: "bash ./scripts/provision-worktree.sh",
+        teardownCommand: "bash ./scripts/teardown-worktree.sh",
+        cleanupCommand: "pkill -f vite || true",
+        workspaceRuntime: {
+          services: [{ name: "web", command: "pnpm dev", port: 3100 }],
+        },
+      },
+    })).toEqual({
+      provisionCommand: "bash ./scripts/provision-worktree.sh",
+      teardownCommand: "bash ./scripts/teardown-worktree.sh",
+      cleanupCommand: "pkill -f vite || true",
+      desiredState: null,
+      workspaceRuntime: {
+        services: [{ name: "web", command: "pnpm dev", port: 3100 }],
+      },
+    });
+  });
+
+  it("merges config patches without dropping unrelated metadata", () => {
+    expect(mergeExecutionWorkspaceConfig(
+      {
+        source: "project_primary",
+        createdByRuntime: false,
+        config: {
+          provisionCommand: "bash ./scripts/provision-worktree.sh",
+          cleanupCommand: "pkill -f vite || true",
+        },
+      },
+      {
+        teardownCommand: "bash ./scripts/teardown-worktree.sh",
+        workspaceRuntime: {
+          services: [{ name: "web", command: "pnpm dev" }],
+        },
+      },
+    )).toEqual({
+      source: "project_primary",
+      createdByRuntime: false,
+      config: {
+        provisionCommand: "bash ./scripts/provision-worktree.sh",
+        teardownCommand: "bash ./scripts/teardown-worktree.sh",
+        cleanupCommand: "pkill -f vite || true",
+        desiredState: null,
+        workspaceRuntime: {
+          services: [{ name: "web", command: "pnpm dev" }],
+        },
+      },
+    });
+  });
+
+  it("clears the nested config block when requested", () => {
+    expect(mergeExecutionWorkspaceConfig(
+      {
+        source: "project_primary",
+        config: {
+          provisionCommand: "bash ./scripts/provision-worktree.sh",
+        },
+      },
+      null,
+    )).toEqual({
+      source: "project_primary",
+    });
+  });
+});
+
+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("allows archiving shared workspace sessions with warnings even when issues are still open", 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: "ready_with_warnings",
+      isSharedWorkspace: true,
+      isProjectPrimaryWorkspace: true,
+      isDestructiveCloseAllowed: true,
+    });
+    expect(readiness?.blockingReasons).toEqual([]);
+    expect(readiness?.warnings).toEqual(expect.arrayContaining([
+      "This workspace is still linked to an open issue. Archiving it will detach this shared workspace session from those issues, but keep the underlying project workspace available.",
+      "This shared workspace session points at project workspace infrastructure. Archiving it only removes the session record.",
+    ]));
+  });
+
+  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: false,
+      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/__tests__/health.test.ts

@@ -1,16 +1,56 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import express from "express";
 import request from "supertest";
+import type { Db } from "@paperclipai/db";
 import { healthRoutes } from "../routes/health.js";
+import * as devServerStatus from "../dev-server-status.js";
 import { serverVersion } from "../version.js";
 
 describe("GET /health", () => {
-  const app = express();
-  app.use("/health", healthRoutes());
+  beforeEach(() => {
+    vi.spyOn(devServerStatus, "readPersistedDevServerStatus").mockReturnValue(undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
 
   it("returns 200 with status ok", async () => {
+    const app = express();
+    app.use("/health", healthRoutes());
+
     const res = await request(app).get("/health");
     expect(res.status).toBe(200);
     expect(res.body).toEqual({ status: "ok", version: serverVersion });
   });
+
+  it("returns 200 when the database probe succeeds", async () => {
+    const db = {
+      execute: vi.fn().mockResolvedValue([{ "?column?": 1 }]),
+    } as unknown as Db;
+    const app = express();
+    app.use("/health", healthRoutes(db));
+
+    const res = await request(app).get("/health");
+
+    expect(res.status).toBe(200);
+    expect(res.body).toMatchObject({ status: "ok", version: serverVersion });
+  });
+
+  it("returns 503 when the database probe fails", async () => {
+    const db = {
+      execute: vi.fn().mockRejectedValue(new Error("connect ECONNREFUSED")),
+    } as unknown as Db;
+    const app = express();
+    app.use("/health", healthRoutes(db));
+
+    const res = await request(app).get("/health");
+
+    expect(res.status).toBe(503);
+    expect(res.body).toEqual({
+      status: "unhealthy",
+      version: serverVersion,
+      error: "database_unreachable",
+    });
+  });
 });

server/src/__tests__/heartbeat-process-recovery.test.ts

@@ -1,89 +1,29 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { spawn, type ChildProcess } from "node:child_process";
 import { eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
-  applyPendingMigrations,
-  createDb,
-  ensurePostgresDatabase,
   agents,
   agentWakeupRequests,
   companies,
+  createDb,
   heartbeatRunEvents,
   heartbeatRuns,
   issues,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { runningProcesses } from "../adapters/index.ts";
 import { heartbeatService } from "../services/heartbeat.ts";
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
 
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
-}
-
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-heartbeat-recovery-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, instance, dataDir };
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres heartbeat recovery tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
 }
 
 function spawnAliveProcess() {
@@ -92,17 +32,14 @@ function spawnAliveProcess() {
   });
 }
 
-describe("heartbeat orphaned process recovery", () => {
+describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
-  let dataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
   const childProcesses = new Set<ChildProcess>();
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
-    db = createDb(started.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-recovery-");
+    db = createDb(tempDb.connectionString);
   }, 20_000);
 
   afterEach(async () => {
@@ -125,10 +62,7 @@ describe("heartbeat orphaned process recovery", () => {
     }
     childProcesses.clear();
     runningProcesses.clear();
-    await instance?.stop();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
+    await tempDb?.cleanup();
   });
 
   async function seedRunFixture(input?: {

server/src/__tests__/heartbeat-workspace-session.test.ts

@@ -3,11 +3,14 @@ import type { agents } from "@paperclipai/db";
 import { sessionCodec as codexSessionCodec } from "@paperclipai/adapter-codex-local/server";
 import { resolveDefaultAgentWorkspaceDir } from "../home-paths.js";
 import {
+  applyPersistedExecutionWorkspaceConfig,
+  buildRealizedExecutionWorkspaceFromPersisted,
   buildExplicitResumeSessionOverride,
   formatRuntimeWorkspaceWarningLog,
   prioritizeProjectWorkspaceCandidatesForRun,
   parseSessionCompactionPolicy,
   resolveRuntimeSessionParamsForWorkspace,
+  stripWorkspaceRuntimeFromExecutionRunConfig,
   shouldResetTaskSessionForWake,
   type ResolvedWorkspaceForRun,
 } from "../services/heartbeat.ts";
@@ -120,6 +123,147 @@ describe("resolveRuntimeSessionParamsForWorkspace", () => {
   });
 });
 
+describe("applyPersistedExecutionWorkspaceConfig", () => {
+  it("does not add workspace runtime when only the project workspace had manual runtime config", () => {
+    const result = applyPersistedExecutionWorkspaceConfig({
+      config: {},
+      workspaceConfig: null,
+      mode: "isolated_workspace",
+    });
+
+    expect("workspaceRuntime" in result).toBe(false);
+  });
+
+  it("applies explicit persisted execution workspace runtime config when present", () => {
+    const result = applyPersistedExecutionWorkspaceConfig({
+      config: {},
+      workspaceConfig: {
+        provisionCommand: null,
+        teardownCommand: null,
+        cleanupCommand: null,
+        desiredState: null,
+        workspaceRuntime: {
+          services: [{ name: "workspace-web" }],
+        },
+      },
+      mode: "isolated_workspace",
+    });
+
+    expect(result.workspaceRuntime).toEqual({
+      services: [{ name: "workspace-web" }],
+    });
+  });
+});
+
+describe("buildRealizedExecutionWorkspaceFromPersisted", () => {
+  it("reuses the persisted execution workspace path instead of deriving a new worktree", () => {
+    const result = buildRealizedExecutionWorkspaceFromPersisted({
+      base: buildResolvedWorkspace({
+        cwd: "/tmp/project-primary",
+        repoRef: "main",
+      }),
+      workspace: {
+        id: "execution-workspace-1",
+        companyId: "company-1",
+        projectId: "project-1",
+        projectWorkspaceId: "workspace-1",
+        sourceIssueId: "issue-1",
+        mode: "isolated_workspace",
+        strategyType: "git_worktree",
+        name: "PAP-880-thumbs-capture-for-evals-feature",
+        status: "active",
+        cwd: "/tmp/reused-worktree",
+        repoUrl: "https://example.com/paperclip.git",
+        baseRef: "main",
+        branchName: "PAP-880-thumbs-capture-for-evals-feature",
+        providerType: "git_worktree",
+        providerRef: "/tmp/reused-worktree",
+        derivedFromExecutionWorkspaceId: null,
+        lastUsedAt: new Date(),
+        openedAt: new Date(),
+        closedAt: null,
+        cleanupEligibleAt: null,
+        cleanupReason: null,
+        config: null,
+        metadata: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    });
+
+    expect(result.created).toBe(false);
+    expect(result.strategy).toBe("git_worktree");
+    expect(result.cwd).toBe("/tmp/reused-worktree");
+    expect(result.worktreePath).toBe("/tmp/reused-worktree");
+    expect(result.branchName).toBe("PAP-880-thumbs-capture-for-evals-feature");
+    expect(result.source).toBe("task_session");
+  });
+
+  it("falls back to realization when the persisted workspace has no local path yet", () => {
+    const result = buildRealizedExecutionWorkspaceFromPersisted({
+      base: buildResolvedWorkspace({
+        cwd: "/tmp/project-primary",
+        repoRef: "main",
+      }),
+      workspace: {
+        id: "execution-workspace-2",
+        companyId: "company-1",
+        projectId: "project-1",
+        projectWorkspaceId: "workspace-1",
+        sourceIssueId: "issue-2",
+        mode: "isolated_workspace",
+        strategyType: "git_worktree",
+        name: "PAP-999-missing-provider-ref",
+        status: "active",
+        cwd: null,
+        repoUrl: "https://example.com/paperclip.git",
+        baseRef: "main",
+        branchName: "feature/PAP-999-missing-provider-ref",
+        providerType: "git_worktree",
+        providerRef: null,
+        derivedFromExecutionWorkspaceId: null,
+        lastUsedAt: new Date(),
+        openedAt: new Date(),
+        closedAt: null,
+        cleanupEligibleAt: null,
+        cleanupReason: null,
+        config: null,
+        metadata: null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    });
+
+    expect(result).toBeNull();
+  });
+});
+
+describe("stripWorkspaceRuntimeFromExecutionRunConfig", () => {
+  it("removes workspace runtime before heartbeat execution", () => {
+    const input = {
+      cwd: "/tmp/project",
+      workspaceStrategy: {
+        type: "git_worktree",
+      },
+      workspaceRuntime: {
+        services: [{ name: "web" }],
+      },
+    };
+
+    const result = stripWorkspaceRuntimeFromExecutionRunConfig(input);
+
+    expect(result).toEqual({
+      cwd: "/tmp/project",
+      workspaceStrategy: {
+        type: "git_worktree",
+      },
+    });
+    expect(input.workspaceRuntime).toEqual({
+      services: [{ name: "web" }],
+    });
+  });
+});
+
 describe("shouldResetTaskSessionForWake", () => {
   it("resets session context on assignment wake", () => {
     expect(shouldResetTaskSessionForWake({ wakeReason: "issue_assigned" })).toBe(true);

server/src/__tests__/helpers/embedded-postgres.ts

@@ -0,0 +1,6 @@
+export {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestSupport,
+} from "@paperclipai/db";

server/src/__tests__/issue-comment-reopen-routes.test.ts

@@ -19,6 +19,9 @@ const mockAccessService = vi.hoisted(() => ({
 const mockHeartbeatService = vi.hoisted(() => ({
   wakeup: vi.fn(async () => undefined),
   reportRunActivity: vi.fn(async () => undefined),
+  getRun: vi.fn(async () => null),
+  getActiveRunForAgent: vi.fn(async () => null),
+  cancelRun: vi.fn(async () => null),
 }));
 
 const mockAgentService = vi.hoisted(() => ({
@@ -143,4 +146,46 @@ describe("issue comment reopen routes", () => {
       }),
     );
   });
+
+  it("interrupts an active run before a combined comment update", async () => {
+    const issue = {
+      ...makeIssue("todo"),
+      executionRunId: "run-1",
+    };
+    mockIssueService.getById.mockResolvedValue(issue);
+    mockIssueService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) => ({
+      ...issue,
+      ...patch,
+    }));
+    mockHeartbeatService.getRun.mockResolvedValue({
+      id: "run-1",
+      companyId: "company-1",
+      agentId: "22222222-2222-4222-8222-222222222222",
+      status: "running",
+    });
+    mockHeartbeatService.cancelRun.mockResolvedValue({
+      id: "run-1",
+      companyId: "company-1",
+      agentId: "22222222-2222-4222-8222-222222222222",
+      status: "cancelled",
+    });
+
+    const res = await request(createApp())
+      .patch("/api/issues/11111111-1111-4111-8111-111111111111")
+      .send({ comment: "hello", interrupt: true, assigneeAgentId: "33333333-3333-4333-8333-333333333333" });
+
+    expect(res.status).toBe(200);
+    expect(mockHeartbeatService.getRun).toHaveBeenCalledWith("run-1");
+    expect(mockHeartbeatService.cancelRun).toHaveBeenCalledWith("run-1");
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        action: "heartbeat.cancelled",
+        details: expect.objectContaining({
+          source: "issue_comment_interrupt",
+          issueId: "11111111-1111-4111-8111-111111111111",
+        }),
+      }),
+    );
+  });
 });

server/src/__tests__/issues-service.test.ts

@@ -1,114 +1,60 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
   activityLog,
   agents,
-  applyPendingMigrations,
   companies,
   createDb,
-  ensurePostgresDatabase,
+  executionWorkspaces,
+  instanceSettings,
   issueComments,
+  issueInboxArchives,
   issues,
+  projectWorkspaces,
+  projects,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { instanceSettingsService } from "../services/instance-settings.ts";
 import { issueService } from "../services/issues.ts";
 
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
 
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres issue service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
 }
 
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-issues-service-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
-
-describe("issueService.list participantAgentId", () => {
+describeEmbeddedPostgres("issueService.list participantAgentId", () => {
   let db!: ReturnType<typeof createDb>;
   let svc!: ReturnType<typeof issueService>;
-  let instance: EmbeddedPostgresInstance | null = null;
-  let dataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
-    db = createDb(started.connectionString);
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-issues-service-");
+    db = createDb(tempDb.connectionString);
     svc = issueService(db);
-    instance = started.instance;
-    dataDir = started.dataDir;
   }, 20_000);
 
   afterEach(async () => {
     await db.delete(issueComments);
+    await db.delete(issueInboxArchives);
     await db.delete(activityLog);
     await db.delete(issues);
+    await db.delete(executionWorkspaces);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
     await db.delete(agents);
+    await db.delete(instanceSettings);
     await db.delete(companies);
   });
 
   afterAll(async () => {
-    await instance?.stop();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
+    await tempDb?.cleanup();
   });
 
   it("returns issues an agent participated in across the supported signals", async () => {
@@ -281,4 +227,454 @@ describe("issueService.list participantAgentId", () => {
 
     expect(result.map((issue) => issue.id)).toEqual([matchedIssueId]);
   });
+
+  it("filters issues by execution workspace id", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const targetWorkspaceId = randomUUID();
+    const otherWorkspaceId = randomUUID();
+    const linkedIssueId = randomUUID();
+    const otherLinkedIssueId = randomUUID();
+    const unlinkedIssueId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Workspace project",
+      status: "in_progress",
+    });
+
+    await db.insert(executionWorkspaces).values([
+      {
+        id: targetWorkspaceId,
+        companyId,
+        projectId,
+        mode: "shared_workspace",
+        strategyType: "project_primary",
+        name: "Target workspace",
+        status: "active",
+        providerType: "local_fs",
+      },
+      {
+        id: otherWorkspaceId,
+        companyId,
+        projectId,
+        mode: "shared_workspace",
+        strategyType: "project_primary",
+        name: "Other workspace",
+        status: "active",
+        providerType: "local_fs",
+      },
+    ]);
+
+    await db.insert(issues).values([
+      {
+        id: linkedIssueId,
+        companyId,
+        projectId,
+        title: "Linked issue",
+        status: "todo",
+        priority: "medium",
+        executionWorkspaceId: targetWorkspaceId,
+      },
+      {
+        id: otherLinkedIssueId,
+        companyId,
+        projectId,
+        title: "Other linked issue",
+        status: "todo",
+        priority: "medium",
+        executionWorkspaceId: otherWorkspaceId,
+      },
+      {
+        id: unlinkedIssueId,
+        companyId,
+        projectId,
+        title: "Unlinked issue",
+        status: "todo",
+        priority: "medium",
+      },
+    ]);
+
+    const result = await svc.list(companyId, { executionWorkspaceId: targetWorkspaceId });
+
+    expect(result.map((issue) => issue.id)).toEqual([linkedIssueId]);
+  });
+
+  it("hides archived inbox issues until new external activity arrives", async () => {
+    const companyId = randomUUID();
+    const userId = "user-1";
+    const otherUserId = "user-2";
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    const visibleIssueId = randomUUID();
+    const archivedIssueId = randomUUID();
+    const resurfacedIssueId = randomUUID();
+
+    await db.insert(issues).values([
+      {
+        id: visibleIssueId,
+        companyId,
+        title: "Visible issue",
+        status: "todo",
+        priority: "medium",
+        createdByUserId: userId,
+        createdAt: new Date("2026-03-26T10:00:00.000Z"),
+        updatedAt: new Date("2026-03-26T10:00:00.000Z"),
+      },
+      {
+        id: archivedIssueId,
+        companyId,
+        title: "Archived issue",
+        status: "todo",
+        priority: "medium",
+        createdByUserId: userId,
+        createdAt: new Date("2026-03-26T11:00:00.000Z"),
+        updatedAt: new Date("2026-03-26T11:00:00.000Z"),
+      },
+      {
+        id: resurfacedIssueId,
+        companyId,
+        title: "Resurfaced issue",
+        status: "todo",
+        priority: "medium",
+        createdByUserId: userId,
+        createdAt: new Date("2026-03-26T12:00:00.000Z"),
+        updatedAt: new Date("2026-03-26T12:00:00.000Z"),
+      },
+    ]);
+
+    await svc.archiveInbox(
+      companyId,
+      archivedIssueId,
+      userId,
+      new Date("2026-03-26T12:30:00.000Z"),
+    );
+    await svc.archiveInbox(
+      companyId,
+      resurfacedIssueId,
+      userId,
+      new Date("2026-03-26T13:00:00.000Z"),
+    );
+
+    await db.insert(issueComments).values({
+      companyId,
+      issueId: resurfacedIssueId,
+      authorUserId: otherUserId,
+      body: "This should bring the issue back into Mine.",
+      createdAt: new Date("2026-03-26T13:30:00.000Z"),
+      updatedAt: new Date("2026-03-26T13:30:00.000Z"),
+    });
+
+    const archivedFiltered = await svc.list(companyId, {
+      touchedByUserId: userId,
+      inboxArchivedByUserId: userId,
+    });
+
+    expect(archivedFiltered.map((issue) => issue.id)).toEqual([
+      resurfacedIssueId,
+      visibleIssueId,
+    ]);
+
+    await svc.unarchiveInbox(companyId, archivedIssueId, userId);
+
+    const afterUnarchive = await svc.list(companyId, {
+      touchedByUserId: userId,
+      inboxArchivedByUserId: userId,
+    });
+
+    expect(new Set(afterUnarchive.map((issue) => issue.id))).toEqual(new Set([
+      visibleIssueId,
+      archivedIssueId,
+      resurfacedIssueId,
+    ]));
+  });
+});
+
+describeEmbeddedPostgres("issueService.create workspace inheritance", () => {
+  let db!: ReturnType<typeof createDb>;
+  let svc!: ReturnType<typeof issueService>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-issues-create-");
+    db = createDb(tempDb.connectionString);
+    svc = issueService(db);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issueComments);
+    await db.delete(issueInboxArchives);
+    await db.delete(activityLog);
+    await db.delete(issues);
+    await db.delete(executionWorkspaces);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
+    await db.delete(agents);
+    await db.delete(instanceSettings);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("inherits the parent issue workspace linkage when child workspace fields are omitted", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const parentIssueId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const executionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: true });
+
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Workspace project",
+      status: "in_progress",
+    });
+
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary workspace",
+      isPrimary: true,
+      sharedWorkspaceKey: "workspace-key",
+    });
+
+    await db.insert(executionWorkspaces).values({
+      id: executionWorkspaceId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      mode: "isolated_workspace",
+      strategyType: "git_worktree",
+      name: "Issue worktree",
+      status: "active",
+      providerType: "git_worktree",
+      providerRef: `/tmp/${executionWorkspaceId}`,
+    });
+
+    await db.insert(issues).values({
+      id: parentIssueId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      title: "Parent issue",
+      status: "in_progress",
+      priority: "medium",
+      executionWorkspaceId,
+      executionWorkspacePreference: "reuse_existing",
+      executionWorkspaceSettings: {
+        mode: "isolated_workspace",
+        workspaceRuntime: { profile: "agent" },
+      },
+    });
+
+    const child = await svc.create(companyId, {
+      parentId: parentIssueId,
+      projectId,
+      title: "Child issue",
+    });
+
+    expect(child.parentId).toBe(parentIssueId);
+    expect(child.projectWorkspaceId).toBe(projectWorkspaceId);
+    expect(child.executionWorkspaceId).toBe(executionWorkspaceId);
+    expect(child.executionWorkspacePreference).toBe("reuse_existing");
+    expect(child.executionWorkspaceSettings).toEqual({
+      mode: "isolated_workspace",
+      workspaceRuntime: { profile: "agent" },
+    });
+  });
+
+  it("keeps explicit workspace fields instead of inheriting the parent linkage", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const parentIssueId = randomUUID();
+    const parentProjectWorkspaceId = randomUUID();
+    const parentExecutionWorkspaceId = randomUUID();
+    const explicitProjectWorkspaceId = randomUUID();
+    const explicitExecutionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: true });
+
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Workspace project",
+      status: "in_progress",
+    });
+
+    await db.insert(projectWorkspaces).values([
+      {
+        id: parentProjectWorkspaceId,
+        companyId,
+        projectId,
+        name: "Parent workspace",
+      },
+      {
+        id: explicitProjectWorkspaceId,
+        companyId,
+        projectId,
+        name: "Explicit workspace",
+      },
+    ]);
+
+    await db.insert(executionWorkspaces).values([
+      {
+        id: parentExecutionWorkspaceId,
+        companyId,
+        projectId,
+        projectWorkspaceId: parentProjectWorkspaceId,
+        mode: "isolated_workspace",
+        strategyType: "git_worktree",
+        name: "Parent worktree",
+        status: "active",
+        providerType: "git_worktree",
+      },
+      {
+        id: explicitExecutionWorkspaceId,
+        companyId,
+        projectId,
+        projectWorkspaceId: explicitProjectWorkspaceId,
+        mode: "shared_workspace",
+        strategyType: "project_primary",
+        name: "Explicit shared workspace",
+        status: "active",
+        providerType: "local_fs",
+      },
+    ]);
+
+    await db.insert(issues).values({
+      id: parentIssueId,
+      companyId,
+      projectId,
+      projectWorkspaceId: parentProjectWorkspaceId,
+      title: "Parent issue",
+      status: "in_progress",
+      priority: "medium",
+      executionWorkspaceId: parentExecutionWorkspaceId,
+      executionWorkspacePreference: "reuse_existing",
+      executionWorkspaceSettings: {
+        mode: "isolated_workspace",
+      },
+    });
+
+    const child = await svc.create(companyId, {
+      parentId: parentIssueId,
+      projectId,
+      title: "Child issue",
+      projectWorkspaceId: explicitProjectWorkspaceId,
+      executionWorkspaceId: explicitExecutionWorkspaceId,
+      executionWorkspacePreference: "reuse_existing",
+      executionWorkspaceSettings: {
+        mode: "shared_workspace",
+      },
+    });
+
+    expect(child.projectWorkspaceId).toBe(explicitProjectWorkspaceId);
+    expect(child.executionWorkspaceId).toBe(explicitExecutionWorkspaceId);
+    expect(child.executionWorkspacePreference).toBe("reuse_existing");
+    expect(child.executionWorkspaceSettings).toEqual({
+      mode: "shared_workspace",
+    });
+  });
+
+  it("inherits workspace linkage from an explicit source issue without creating a parent-child relationship", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const sourceIssueId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const executionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: true });
+
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Workspace project",
+      status: "in_progress",
+    });
+
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary workspace",
+    });
+
+    await db.insert(executionWorkspaces).values({
+      id: executionWorkspaceId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      mode: "operator_branch",
+      strategyType: "git_worktree",
+      name: "Operator branch",
+      status: "active",
+      providerType: "git_worktree",
+    });
+
+    await db.insert(issues).values({
+      id: sourceIssueId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      title: "Source issue",
+      status: "todo",
+      priority: "medium",
+      executionWorkspaceId,
+      executionWorkspacePreference: "reuse_existing",
+      executionWorkspaceSettings: {
+        mode: "operator_branch",
+      },
+    });
+
+    const followUp = await svc.create(companyId, {
+      projectId,
+      title: "Follow-up issue",
+      inheritExecutionWorkspaceFromIssueId: sourceIssueId,
+    });
+
+    expect(followUp.parentId).toBeNull();
+    expect(followUp.projectWorkspaceId).toBe(projectWorkspaceId);
+    expect(followUp.executionWorkspaceId).toBe(executionWorkspaceId);
+    expect(followUp.executionWorkspacePreference).toBe("reuse_existing");
+    expect(followUp.executionWorkspaceSettings).toEqual({
+      mode: "operator_branch",
+    });
+  });
 });

server/src/__tests__/openclaw-invite-prompt-route.test.ts

@@ -1,6 +1,7 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { companies, invites } from "@paperclipai/db";
 import { accessRoutes } from "../routes/access.js";
 import { errorHandler } from "../middleware/index.js";
 
@@ -51,19 +52,35 @@ function createDbStub() {
     inviteType: "company_join",
     allowedJoinTypes: "agent",
     defaultsPayload: null,
-    expiresAt: new Date("2026-03-07T00:10:00.000Z"),
+    expiresAt: new Date("2099-03-07T00:10:00.000Z"),
     invitedByUserId: null,
     tokenHash: "hash",
     revokedAt: null,
     acceptedAt: null,
-    createdAt: new Date("2026-03-07T00:00:00.000Z"),
-    updatedAt: new Date("2026-03-07T00:00:00.000Z"),
+    createdAt: new Date("2099-03-07T00:00:00.000Z"),
+    updatedAt: new Date("2099-03-07T00:00:00.000Z"),
   };
   const returning = vi.fn().mockResolvedValue([createdInvite]);
   const values = vi.fn().mockReturnValue({ returning });
   const insert = vi.fn().mockReturnValue({ values });
+  const select = vi.fn(() => ({
+    from(table: unknown) {
+      return {
+        where: vi.fn().mockImplementation(() => {
+          if (table === invites) {
+            return Promise.resolve([createdInvite]);
+          }
+          if (table === companies) {
+            return Promise.resolve([{ name: "Acme AI" }]);
+          }
+          return Promise.resolve([]);
+        }),
+      };
+    },
+  }));
   return {
     insert,
+    select,
   };
 }
 
@@ -143,9 +160,30 @@ describe("POST /companies/:companyId/openclaw/invite-prompt", () => {
     expect(res.status).toBe(201);
     expect(res.body.allowedJoinTypes).toBe("agent");
     expect(typeof res.body.token).toBe("string");
+    expect(res.body.companyName).toBe("Acme AI");
     expect(res.body.onboardingTextPath).toContain("/api/invites/");
   });
 
+  it("includes companyName in invite summary responses", async () => {
+    const db = createDbStub();
+    const app = createApp(
+      {
+        type: "board",
+        userId: "user-1",
+        companyIds: ["company-1"],
+        source: "session",
+        isInstanceAdmin: false,
+      },
+      db,
+    );
+
+    const res = await request(app).get("/api/invites/pcp_invite_test");
+
+    expect(res.status).toBe(200);
+    expect(res.body.companyId).toBe("company-1");
+    expect(res.body.companyName).toBe("Acme AI");
+  });
+
   it("allows board callers with invite permission", async () => {
     const db = createDbStub();
     mockAccessService.canUser.mockResolvedValue(true);

server/src/__tests__/routines-e2e.test.ts

@@ -1,8 +1,4 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { eq } from "drizzle-orm";
 import express from "express";
 import request from "supertest";
@@ -11,11 +7,9 @@ import {
   activityLog,
   agentWakeupRequests,
   agents,
-  applyPendingMigrations,
   companies,
   companyMemberships,
   createDb,
-  ensurePostgresDatabase,
   heartbeatRunEvents,
   heartbeatRuns,
   instanceSettings,
@@ -26,6 +20,10 @@ import {
   routines,
   routineTriggers,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { errorHandler } from "../middleware/index.js";
 import { accessService } from "../services/access.js";
 
@@ -78,82 +76,22 @@ vi.mock("../services/index.js", async () => {
   };
 });
 
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
 
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres routine route tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
 }
 
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-routines-e2e-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
-
-describe("routine routes end-to-end", () => {
+describeEmbeddedPostgres("routine routes end-to-end", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
-  let dataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
-    db = createDb(started.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-routines-e2e-");
+    db = createDb(tempDb.connectionString);
   }, 20_000);
 
   afterEach(async () => {
@@ -174,10 +112,7 @@ describe("routine routes end-to-end", () => {
   });
 
   afterAll(async () => {
-    await instance?.stop();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
+    await tempDb?.cleanup();
   });
 
   async function createApp(actor: Record<string, unknown>) {

server/src/__tests__/routines-service.test.ts

@@ -1,19 +1,13 @@
 import { createHmac, randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
   activityLog,
   agents,
-  applyPendingMigrations,
   companies,
   companySecrets,
   companySecretVersions,
   createDb,
-  ensurePostgresDatabase,
   heartbeatRuns,
   issues,
   projects,
@@ -21,85 +15,29 @@ import {
   routines,
   routineTriggers,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { issueService } from "../services/issues.ts";
 import { routineService } from "../services/routines.ts";
 
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
 
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres routines service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
 }
 
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-routines-service-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
-
-describe("routine service live-execution coalescing", () => {
+describeEmbeddedPostgres("routine service live-execution coalescing", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
-  let dataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
-    db = createDb(started.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-routines-service-");
+    db = createDb(tempDb.connectionString);
   }, 20_000);
 
   afterEach(async () => {
@@ -117,10 +55,7 @@ describe("routine service live-execution coalescing", () => {
   });
 
   afterAll(async () => {
-    await instance?.stop();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
+    await tempDb?.cleanup();
   });
 
   async function seedFixture(opts?: {

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

@@ -1,23 +1,51 @@
 import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  agents,
+  companies,
+  createDb,
+  executionWorkspaces,
+  heartbeatRuns,
+  projects,
+  workspaceRuntimeServices,
+} from "@paperclipai/db";
+import { eq } from "drizzle-orm";
 import {
   cleanupExecutionWorkspaceArtifacts,
   ensureRuntimeServicesForRun,
   normalizeAdapterManagedRuntimeServices,
+  reconcilePersistedRuntimeServicesOnStartup,
   realizeExecutionWorkspace,
   releaseRuntimeServicesForRun,
+  resetRuntimeServicesForTests,
+  sanitizeRuntimeServiceBaseEnv,
   stopRuntimeServicesForExecutionWorkspace,
   type RealizedExecutionWorkspace,
 } from "../services/workspace-runtime.ts";
+import { resolvePaperclipConfigPath } from "../paths.ts";
 import type { WorkspaceOperation } from "@paperclipai/shared";
 import type { WorkspaceOperationRecorder } from "../services/workspace-operations.ts";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 
 const execFileAsync = promisify(execFile);
 const leasedRunIds = new Set<string>();
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres workspace-runtime tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
 
 async function runGit(cwd: string, args: string[]) {
   await execFileAsync("git", args, { cwd });
@@ -124,7 +152,30 @@ afterEach(async () => {
   delete process.env.PAPERCLIP_CONFIG;
   delete process.env.PAPERCLIP_HOME;
   delete process.env.PAPERCLIP_INSTANCE_ID;
+  delete process.env.PAPERCLIP_WORKTREES_DIR;
   delete process.env.DATABASE_URL;
+  await resetRuntimeServicesForTests();
+});
+
+describe("sanitizeRuntimeServiceBaseEnv", () => {
+  it("removes inherited Paperclip and pnpm auth flags before spawning runtime services", () => {
+    const sanitized = sanitizeRuntimeServiceBaseEnv({
+      PATH: process.env.PATH,
+      DATABASE_URL: "postgres://example.test/paperclip",
+      PAPERCLIP_HOME: "/tmp/paperclip-home",
+      PAPERCLIP_INSTANCE_ID: "runtime-instance",
+      npm_config_tailscale_auth: "true",
+      npm_config_authenticated_private: "true",
+      HOST: "0.0.0.0",
+    });
+
+    expect(sanitized.PAPERCLIP_HOME).toBeUndefined();
+    expect(sanitized.PAPERCLIP_INSTANCE_ID).toBeUndefined();
+    expect(sanitized.DATABASE_URL).toBeUndefined();
+    expect(sanitized.npm_config_tailscale_auth).toBeUndefined();
+    expect(sanitized.npm_config_authenticated_private).toBeUndefined();
+    expect(sanitized.HOST).toBe("0.0.0.0");
+  });
 });
 
 describe("realizeExecutionWorkspace", () => {
@@ -196,6 +247,77 @@ describe("realizeExecutionWorkspace", () => {
     expect(second.branchName).toBe(first.branchName);
   });
 
+  it("slugifies unsafe issue titles for branch names and worktree folders", async () => {
+    const repoRoot = await createTempRepo();
+
+    const realized = 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-unsafe",
+        identifier: "PAP-991",
+        title: "there should be a setting for the allowance of thumbs up / thumbs down data; `rm -rf`",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(realized.branchName).toBe(
+      "PAP-991-there-should-be-a-setting-for-the-allowance-of-thumbs-up-thumbs-down-data-rm-rf",
+    );
+    expect(realized.branchName?.includes("/")).toBe(false);
+    expect(path.basename(realized.cwd)).toBe(realized.branchName);
+  });
+
+  it("preserves intentional slashes and dots from the branch template", async () => {
+    const repoRoot = await createTempRepo();
+
+    const realized = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "HEAD",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "release/{{issue.identifier}}.{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-template-safe",
+        identifier: "PAP-992",
+        title: "Hotfix / April.1",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(realized.branchName).toBe("release/PAP-992.hotfix-april-1");
+    expect(path.basename(realized.cwd)).toBe("PAP-992.hotfix-april-1");
+  });
+
   it("runs a configured provision command inside the derived worktree", async () => {
     const repoRoot = await createTempRepo();
     await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });
@@ -282,6 +404,156 @@ describe("realizeExecutionWorkspace", () => {
     await expect(fs.readFile(path.join(reused.cwd, ".paperclip-provision-created"), "utf8")).resolves.toBe("false\n");
   });
 
+  it("writes an isolated repo-local Paperclip config and worktree branding when provisioning", async () => {
+    const repoRoot = await createTempRepo();
+    const previousCwd = process.cwd();
+    const paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-home-"));
+    const isolatedWorktreeHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktrees-"));
+    const instanceId = "worktree-base";
+    const sharedConfigDir = path.join(paperclipHome, "instances", instanceId);
+    const sharedConfigPath = path.join(sharedConfigDir, "config.json");
+    const sharedEnvPath = path.join(sharedConfigDir, ".env");
+
+    process.env.PAPERCLIP_HOME = paperclipHome;
+    process.env.PAPERCLIP_INSTANCE_ID = instanceId;
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedWorktreeHome;
+
+    await fs.mkdir(sharedConfigDir, { recursive: true });
+    await fs.writeFile(
+      sharedConfigPath,
+      JSON.stringify(
+        {
+          $meta: {
+            version: 1,
+            updatedAt: "2026-03-26T00:00:00.000Z",
+            source: "doctor",
+          },
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(sharedConfigDir, "db"),
+            embeddedPostgresPort: 54329,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(sharedConfigDir, "backups"),
+            },
+          },
+          logging: {
+            mode: "file",
+            logDir: path.join(sharedConfigDir, "logs"),
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3100,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+          auth: {
+            baseUrlMode: "auto",
+            disableSignUp: false,
+          },
+          storage: {
+            provider: "local_disk",
+            localDisk: {
+              baseDir: path.join(sharedConfigDir, "storage"),
+            },
+            s3: {
+              bucket: "paperclip",
+              region: "us-east-1",
+              prefix: "",
+              forcePathStyle: false,
+            },
+          },
+          secrets: {
+            provider: "local_encrypted",
+            strictMode: false,
+            localEncrypted: {
+              keyFilePath: path.join(sharedConfigDir, "master.key"),
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+    await fs.writeFile(sharedEnvPath, 'DATABASE_URL="postgres://worktree:test@db.example.com:6543/paperclip"\n', "utf8");
+
+    await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });
+    await fs.copyFile(
+      fileURLToPath(new URL("../../../scripts/provision-worktree.sh", import.meta.url)),
+      path.join(repoRoot, "scripts", "provision-worktree.sh"),
+    );
+    await runGit(repoRoot, ["add", "scripts/provision-worktree.sh"]);
+    await runGit(repoRoot, ["commit", "-m", "Add worktree provision script"]);
+
+    try {
+      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}}",
+            provisionCommand: "bash ./scripts/provision-worktree.sh",
+          },
+        },
+        issue: {
+          id: "issue-1",
+          identifier: "PAP-885",
+          title: "Show worktree banner",
+        },
+        agent: {
+          id: "agent-1",
+          name: "Codex Coder",
+          companyId: "company-1",
+        },
+      });
+
+      const configPath = path.join(workspace.cwd, ".paperclip", "config.json");
+      const envPath = path.join(workspace.cwd, ".paperclip", ".env");
+      const envContents = await fs.readFile(envPath, "utf8");
+      const configContents = JSON.parse(await fs.readFile(configPath, "utf8"));
+      const configStats = await fs.lstat(configPath);
+      const expectedInstanceId = "pap-885-show-worktree-banner";
+      const expectedInstanceRoot = path.join(
+        isolatedWorktreeHome,
+        "instances",
+        expectedInstanceId,
+      );
+
+      expect(configStats.isSymbolicLink()).toBe(false);
+      expect(configContents.database.embeddedPostgresDataDir).toBe(path.join(expectedInstanceRoot, "db"));
+      expect(configContents.database.embeddedPostgresDataDir).not.toBe(path.join(sharedConfigDir, "db"));
+      expect(configContents.server.port).not.toBe(3100);
+      expect(configContents.secrets.localEncrypted.keyFilePath).toBe(
+        path.join(expectedInstanceRoot, "secrets", "master.key"),
+      );
+      expect(envContents).not.toContain("DATABASE_URL=");
+      expect(envContents).toContain(`PAPERCLIP_HOME=${JSON.stringify(isolatedWorktreeHome)}`);
+      expect(envContents).toContain(`PAPERCLIP_INSTANCE_ID=${JSON.stringify(expectedInstanceId)}`);
+      expect(envContents).toContain(`PAPERCLIP_CONFIG=${JSON.stringify(configPath)}`);
+      expect(envContents).toContain("PAPERCLIP_IN_WORKTREE=true");
+      expect(envContents).toContain(
+        `PAPERCLIP_WORKTREE_NAME=${JSON.stringify("PAP-885-show-worktree-banner")}`,
+      );
+
+      process.chdir(workspace.cwd);
+      expect(resolvePaperclipConfigPath()).toBe(configPath);
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+
   it("records worktree setup and provision operations when a recorder is provided", async () => {
     const repoRoot = await createTempRepo();
     const { recorder, operations } = createWorkspaceOperationRecorderDouble();
@@ -681,6 +953,101 @@ describe("ensureRuntimeServicesForRun", () => {
     expect(third[0]?.id).not.toBe(first[0]?.id);
   });
 
+  it("does not reuse project-scoped shared services across different workspace launch contexts", async () => {
+    const primaryWorkspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-primary-"));
+    const worktreeWorkspaceRoot = path.join(primaryWorkspaceRoot, ".paperclip", "worktrees", "PAP-874-chat-speed-issues");
+    await fs.mkdir(worktreeWorkspaceRoot, { recursive: true });
+
+    const primaryWorkspace = buildWorkspace(primaryWorkspaceRoot);
+    const executionWorkspace: RealizedExecutionWorkspace = {
+      ...buildWorkspace(worktreeWorkspaceRoot),
+      source: "task_session",
+      strategy: "git_worktree",
+      cwd: worktreeWorkspaceRoot,
+      branchName: "PAP-874-chat-speed-issues",
+      worktreePath: worktreeWorkspaceRoot,
+    };
+    const serviceCommand =
+      "node -e \"require('node:http').createServer((req,res)=>res.end(process.env.PAPERCLIP_HOME)).listen(Number(process.env.PORT), '127.0.0.1')\"";
+    const config = {
+      workspaceRuntime: {
+        services: [
+          {
+            name: "paperclip-dev",
+            command: serviceCommand,
+            cwd: ".",
+            env: {
+              PAPERCLIP_HOME: "{{workspace.cwd}}/.paperclip/runtime-services",
+            },
+            port: { type: "auto" },
+            readiness: {
+              type: "http",
+              urlTemplate: "http://127.0.0.1:{{port}}",
+              timeoutSec: 10,
+              intervalMs: 100,
+            },
+            expose: {
+              type: "url",
+              urlTemplate: "http://127.0.0.1:{{port}}",
+            },
+            lifecycle: "shared",
+            reuseScope: "project_workspace",
+            stopPolicy: {
+              type: "on_run_finish",
+            },
+          },
+        ],
+      },
+    };
+
+    const primaryRunId = "run-project-workspace";
+    const executionRunId = "run-execution-workspace";
+    leasedRunIds.add(primaryRunId);
+    leasedRunIds.add(executionRunId);
+
+    const primaryServices = await ensureRuntimeServicesForRun({
+      runId: primaryRunId,
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace: primaryWorkspace,
+      config,
+      adapterEnv: {},
+    });
+
+    const executionServices = await ensureRuntimeServicesForRun({
+      runId: executionRunId,
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+      issue: null,
+      workspace: executionWorkspace,
+      executionWorkspaceId: "execution-workspace-1",
+      config,
+      adapterEnv: {},
+    });
+
+    expect(primaryServices).toHaveLength(1);
+    expect(executionServices).toHaveLength(1);
+    expect(primaryServices[0]?.reused).toBe(false);
+    expect(executionServices[0]?.reused).toBe(false);
+    expect(executionServices[0]?.id).not.toBe(primaryServices[0]?.id);
+    expect(executionServices[0]?.executionWorkspaceId).toBe("execution-workspace-1");
+    expect(executionServices[0]?.cwd).toBe(worktreeWorkspaceRoot);
+    expect(executionServices[0]?.url).not.toBe(primaryServices[0]?.url);
+
+    const primaryResponse = await fetch(primaryServices[0]!.url!);
+    expect(await primaryResponse.text()).toBe(path.join(primaryWorkspaceRoot, ".paperclip", "runtime-services"));
+
+    const executionResponse = await fetch(executionServices[0]!.url!);
+    expect(await executionResponse.text()).toBe(path.join(worktreeWorkspaceRoot, ".paperclip", "runtime-services"));
+  });
+
   it("does not leak parent Paperclip instance env into runtime service commands", async () => {
     const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-env-"));
     const workspace = buildWorkspace(workspaceRoot);
@@ -875,6 +1242,258 @@ describe("ensureRuntimeServicesForRun", () => {
   });
 });
 
+describeEmbeddedPostgres("workspace runtime startup reconciliation", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-workspace-runtime-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  afterEach(async () => {
+    await db.delete(workspaceRuntimeServices);
+    await db.delete(executionWorkspaces);
+    await db.delete(projects);
+    await db.delete(heartbeatRuns);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  it("adopts a live auto-port shared service after runtime state is reset", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-reconcile-"));
+    const paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-home-"));
+    process.env.PAPERCLIP_HOME = paperclipHome;
+    process.env.PAPERCLIP_INSTANCE_ID = `runtime-reconcile-${randomUUID()}`;
+
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const runId = randomUUID();
+    const executionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "Codex Coder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "manual",
+      status: "running",
+      startedAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const workspace = {
+      ...buildWorkspace(workspaceRoot),
+      projectId: null,
+      workspaceId: null,
+    };
+    leasedRunIds.add(runId);
+
+    const services = await ensureRuntimeServicesForRun({
+      db,
+      runId,
+      agent: {
+        id: agentId,
+        name: "Codex Coder",
+        companyId,
+      },
+      issue: null,
+      workspace,
+      config: {
+        workspaceRuntime: {
+          services: [
+            {
+              name: "web",
+              command:
+                "node -e \"require('node:http').createServer((req,res)=>res.end('ok')).listen(Number(process.env.PORT), '127.0.0.1')\"",
+              port: { type: "auto" },
+              readiness: {
+                type: "http",
+                urlTemplate: "http://127.0.0.1:{{port}}",
+                timeoutSec: 10,
+                intervalMs: 100,
+              },
+              lifecycle: "shared",
+              reuseScope: "agent",
+              stopPolicy: {
+                type: "manual",
+              },
+            },
+          ],
+        },
+      },
+      adapterEnv: {},
+    });
+
+    expect(services).toHaveLength(1);
+    const service = services[0];
+    expect(service?.url).toMatch(/^http:\/\/127\.0\.0\.1:\d+$/);
+    await expect(fetch(service!.url!)).resolves.toMatchObject({ ok: true });
+
+    await resetRuntimeServicesForTests();
+
+    const result = await reconcilePersistedRuntimeServicesOnStartup(db);
+    expect(result).toMatchObject({ reconciled: 1, adopted: 1, stopped: 0 });
+
+    const persisted = await db
+      .select()
+      .from(workspaceRuntimeServices)
+      .where(eq(workspaceRuntimeServices.id, service!.id))
+      .then((rows) => rows[0] ?? null);
+    expect(persisted?.status).toBe("running");
+    expect(persisted?.providerRef).toMatch(/^\d+$/);
+
+    await stopRuntimeServicesForExecutionWorkspace({
+      db,
+      executionWorkspaceId,
+      workspaceCwd: workspace.cwd,
+    });
+
+    await expect(fetch(service!.url!)).rejects.toThrow();
+  });
+
+  it("persists controlled execution workspace stops as stopped", async () => {
+    const workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-stop-persisted-"));
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const projectId = randomUUID();
+    const runId = randomUUID();
+    const executionWorkspaceId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "Codex Coder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Runtime stop test",
+      status: "active",
+    });
+    await db.insert(executionWorkspaces).values({
+      id: executionWorkspaceId,
+      companyId,
+      projectId,
+      mode: "isolated_workspace",
+      strategyType: "git_worktree",
+      name: "Execution workspace stop test",
+      status: "active",
+      cwd: workspaceRoot,
+      providerType: "local_fs",
+      providerRef: workspaceRoot,
+    });
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "manual",
+      status: "running",
+      startedAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    const workspace = {
+      ...buildWorkspace(workspaceRoot),
+      projectId: null,
+      workspaceId: null,
+    };
+    leasedRunIds.add(runId);
+
+    const services = await ensureRuntimeServicesForRun({
+      db,
+      runId,
+      agent: {
+        id: agentId,
+        name: "Codex Coder",
+        companyId,
+      },
+      issue: null,
+      workspace,
+      executionWorkspaceId,
+      config: {
+        workspaceRuntime: {
+          services: [
+            {
+              name: "web",
+              command:
+                "node -e \"require('node:http').createServer((req,res)=>res.end('ok')).listen(Number(process.env.PORT), '127.0.0.1')\"",
+              port: { type: "auto" },
+              readiness: {
+                type: "http",
+                urlTemplate: "http://127.0.0.1:{{port}}",
+                timeoutSec: 10,
+                intervalMs: 100,
+              },
+              lifecycle: "shared",
+              reuseScope: "execution_workspace",
+              stopPolicy: {
+                type: "manual",
+              },
+            },
+          ],
+        },
+      },
+      adapterEnv: {},
+    });
+
+    expect(services[0]?.url).toBeTruthy();
+
+    await stopRuntimeServicesForExecutionWorkspace({
+      db,
+      executionWorkspaceId,
+      workspaceCwd: workspace.cwd,
+    });
+    await releaseRuntimeServicesForRun(runId);
+    leasedRunIds.delete(runId);
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    await expect(fetch(services[0]!.url!)).rejects.toThrow();
+
+    const persisted = await db
+      .select()
+      .from(workspaceRuntimeServices)
+      .where(eq(workspaceRuntimeServices.id, services[0]!.id))
+      .then((rows) => rows[0] ?? null);
+
+    expect(persisted?.status).toBe("stopped");
+    expect(persisted?.healthStatus).toBe("unknown");
+    expect(persisted?.stoppedAt).toBeTruthy();
+  });
+});
+
 describe("normalizeAdapterManagedRuntimeServices", () => {
   it("fills workspace defaults and derives stable ids for adapter-managed services", () => {
     const workspace = buildWorkspace("/tmp/project");

server/src/__tests__/worktree-config.test.ts

@@ -0,0 +1,426 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  applyRuntimePortSelectionToConfig,
+  maybePersistWorktreeRuntimePorts,
+  maybeRepairLegacyWorktreeConfigAndEnvFiles,
+} from "../worktree-config.js";
+
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
+
+afterEach(() => {
+  process.chdir(ORIGINAL_CWD);
+
+  for (const key of Object.keys(process.env)) {
+    if (!(key in ORIGINAL_ENV)) {
+      delete process.env[key];
+    }
+  }
+  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
+    process.env[key] = value;
+  }
+});
+
+function buildLegacyConfig(sharedRoot: string) {
+  return {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-26T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres" as const,
+      embeddedPostgresDataDir: path.join(sharedRoot, "db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(sharedRoot, "data", "backups"),
+      },
+    },
+    logging: {
+      mode: "file" as const,
+      logDir: path.join(sharedRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted" as const,
+      exposure: "private" as const,
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "explicit" as const,
+      publicBaseUrl: "http://127.0.0.1:3100",
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk" as const,
+      localDisk: {
+        baseDir: path.join(sharedRoot, "data", "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted" as const,
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(sharedRoot, "secrets", "master.key"),
+      },
+    },
+  };
+}
+
+describe("worktree config repair", () => {
+  it("repairs legacy repo-local worktree config and env files into an isolated instance", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-repair-"));
+    const worktreeRoot = path.join(tempRoot, "PAP-884-ai-commits-component");
+    const paperclipDir = path.join(worktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const envPath = path.join(paperclipDir, ".env");
+    const sharedRoot = path.join(tempRoot, ".paperclip", "instances", "default");
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(buildLegacyConfig(sharedRoot), null, 2) + "\n", "utf8");
+    await fs.writeFile(
+      envPath,
+      [
+        "# Paperclip environment variables",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=PAP-884-ai-commits-component",
+        "PAPERCLIP_AGENT_JWT_SECRET=shared-secret",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+
+    process.chdir(worktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-884-ai-commits-component";
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedHome;
+    delete process.env.PAPERCLIP_HOME;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+    delete process.env.PAPERCLIP_CONFIG;
+    delete process.env.PAPERCLIP_CONTEXT;
+
+    const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+
+    expect(result).toEqual({
+      repairedConfig: true,
+      repairedEnv: true,
+    });
+
+    const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+    const repairedEnv = await fs.readFile(envPath, "utf8");
+    const instanceRoot = path.join(isolatedHome, "instances", "pap-884-ai-commits-component");
+
+    expect(repairedConfig.database.embeddedPostgresDataDir).toBe(path.join(instanceRoot, "db"));
+    expect(repairedConfig.database.backup.dir).toBe(path.join(instanceRoot, "data", "backups"));
+    expect(repairedConfig.logging.logDir).toBe(path.join(instanceRoot, "logs"));
+    expect(repairedConfig.storage.localDisk.baseDir).toBe(path.join(instanceRoot, "data", "storage"));
+    expect(repairedConfig.secrets.localEncrypted.keyFilePath).toBe(path.join(instanceRoot, "secrets", "master.key"));
+    expect(repairedEnv).toContain(`PAPERCLIP_HOME=${JSON.stringify(isolatedHome)}`);
+    expect(repairedEnv).toContain('PAPERCLIP_INSTANCE_ID="pap-884-ai-commits-component"');
+    expect(repairedEnv).toContain(`PAPERCLIP_CONFIG=${JSON.stringify(await fs.realpath(configPath))}`);
+    expect(repairedEnv).toContain(`PAPERCLIP_CONTEXT=${JSON.stringify(path.join(isolatedHome, "context.json"))}`);
+    expect(repairedEnv).toContain('PAPERCLIP_AGENT_JWT_SECRET="shared-secret"');
+    expect(process.env.PAPERCLIP_HOME).toBe(isolatedHome);
+    expect(process.env.PAPERCLIP_INSTANCE_ID).toBe("pap-884-ai-commits-component");
+  });
+
+  it("avoids sibling worktree ports when repairing legacy configs", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-repair-ports-"));
+    const worktreeRoot = path.join(tempRoot, "PAP-880-thumbs-capture-for-evals-feature");
+    const paperclipDir = path.join(worktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const envPath = path.join(paperclipDir, ".env");
+    const sharedRoot = path.join(tempRoot, ".paperclip", "instances", "default");
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+    const siblingInstanceRoot = path.join(isolatedHome, "instances", "pap-878-create-a-mine-tab-in-inbox");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.mkdir(siblingInstanceRoot, { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(buildLegacyConfig(sharedRoot), null, 2) + "\n", "utf8");
+    await fs.writeFile(
+      envPath,
+      [
+        "# Paperclip environment variables",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=PAP-880-thumbs-capture-for-evals-feature",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    await fs.writeFile(
+      path.join(siblingInstanceRoot, "config.json"),
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(siblingInstanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(siblingInstanceRoot, "db"),
+            embeddedPostgresPort: 54330,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(siblingInstanceRoot, "data", "backups"),
+            },
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+
+    process.chdir(worktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-880-thumbs-capture-for-evals-feature";
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedHome;
+
+    const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+    const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    expect(result.repairedConfig).toBe(true);
+    expect(repairedConfig.server.port).toBe(3102);
+    expect(repairedConfig.database.embeddedPostgresPort).toBe(54331);
+  });
+
+  it("rebalances duplicate ports for already isolated worktree configs", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-rebalance-"));
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+    const repoWorktreesRoot = path.join(tempRoot, "repo", ".paperclip", "worktrees");
+    const siblingWorktreeRoot = path.join(repoWorktreesRoot, "PAP-878-create-a-mine-tab-in-inbox");
+    const siblingInstanceRoot = path.join(isolatedHome, "instances", "pap-878-create-a-mine-tab-in-inbox");
+    const currentWorktreeRoot = path.join(repoWorktreesRoot, "PAP-884-ai-commits-component");
+    const paperclipDir = path.join(currentWorktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const envPath = path.join(paperclipDir, ".env");
+    const currentInstanceRoot = path.join(isolatedHome, "instances", "pap-884-ai-commits-component");
+    const siblingConfigPath = path.join(siblingWorktreeRoot, ".paperclip", "config.json");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.mkdir(path.dirname(siblingConfigPath), { recursive: true });
+    await fs.writeFile(
+      configPath,
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(currentInstanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(currentInstanceRoot, "db"),
+            embeddedPostgresPort: 54330,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(currentInstanceRoot, "data", "backups"),
+            },
+          },
+          logging: {
+            mode: "file",
+            logDir: path.join(currentInstanceRoot, "logs"),
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+          storage: {
+            provider: "local_disk",
+            localDisk: {
+              baseDir: path.join(currentInstanceRoot, "data", "storage"),
+            },
+            s3: {
+              bucket: "paperclip",
+              region: "us-east-1",
+              prefix: "",
+              forcePathStyle: false,
+            },
+          },
+          secrets: {
+            provider: "local_encrypted",
+            strictMode: false,
+            localEncrypted: {
+              keyFilePath: path.join(currentInstanceRoot, "secrets", "master.key"),
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+    await fs.writeFile(
+      envPath,
+      [
+        "# Paperclip environment variables",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=PAP-884-ai-commits-component",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    await fs.writeFile(
+      siblingConfigPath,
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(siblingInstanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(siblingInstanceRoot, "db"),
+            embeddedPostgresPort: 54330,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(siblingInstanceRoot, "data", "backups"),
+            },
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+
+    process.chdir(currentWorktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-884-ai-commits-component";
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedHome;
+
+    const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+    const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    expect(result.repairedConfig).toBe(true);
+    expect(repairedConfig.server.port).toBe(3102);
+    expect(repairedConfig.database.embeddedPostgresPort).toBe(54331);
+  });
+
+  it("persists runtime-selected worktree ports back into config", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-ports-"));
+    const worktreeRoot = path.join(tempRoot, "PAP-878-create-a-mine-tab-in-inbox");
+    const paperclipDir = path.join(worktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+    const instanceRoot = path.join(isolatedHome, "instances", "pap-878-create-a-mine-tab-in-inbox");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.writeFile(
+      configPath,
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(instanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(instanceRoot, "db"),
+            embeddedPostgresPort: 54331,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(instanceRoot, "data", "backups"),
+            },
+          },
+          logging: {
+            mode: "file",
+            logDir: path.join(instanceRoot, "logs"),
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+          storage: {
+            provider: "local_disk",
+            localDisk: {
+              baseDir: path.join(instanceRoot, "data", "storage"),
+            },
+            s3: {
+              bucket: "paperclip",
+              region: "us-east-1",
+              prefix: "",
+              forcePathStyle: false,
+            },
+          },
+          secrets: {
+            provider: "local_encrypted",
+            strictMode: false,
+            localEncrypted: {
+              keyFilePath: path.join(instanceRoot, "secrets", "master.key"),
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+
+    process.chdir(worktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-878-create-a-mine-tab-in-inbox";
+    process.env.PAPERCLIP_HOME = isolatedHome;
+    process.env.PAPERCLIP_INSTANCE_ID = "pap-878-create-a-mine-tab-in-inbox";
+    process.env.PAPERCLIP_CONFIG = configPath;
+
+    maybePersistWorktreeRuntimePorts({
+      serverPort: 3103,
+      databasePort: 54335,
+    });
+
+    const writtenConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    expect(writtenConfig.server.port).toBe(3103);
+    expect(writtenConfig.database.embeddedPostgresPort).toBe(54335);
+    expect(writtenConfig.auth.publicBaseUrl).toBe("http://127.0.0.1:3103/");
+  });
+
+  it("can update the in-memory config without rewriting env-driven ports", () => {
+    const { config, changed } = applyRuntimePortSelectionToConfig(buildLegacyConfig("/tmp/shared"), {
+      serverPort: 3104,
+      databasePort: 54340,
+      allowServerPortWrite: false,
+      allowDatabasePortWrite: true,
+    });
+
+    expect(changed).toBe(true);
+    expect(config.server.port).toBe(3100);
+    expect(config.database.embeddedPostgresPort).toBe(54340);
+    expect(config.auth.publicBaseUrl).toBe("http://127.0.0.1:3104/");
+  });
+});

server/src/adapters/index.ts

@@ -1,4 +1,4 @@
-export { getServerAdapter, listAdapterModels, listServerAdapters, findServerAdapter } from "./registry.js";
+export { getServerAdapter, listAdapterModels, listServerAdapters, findServerAdapter, detectAdapterModel } from "./registry.js";
 export type {
   ServerAdapterModule,
   AdapterExecutionContext,

server/src/adapters/process/execute.ts

@@ -5,7 +5,9 @@ import {
   asStringArray,
   parseObject,
   buildPaperclipEnv,
-  redactEnvForLogs,
+  buildInvocationEnvForLogs,
+  ensurePathInEnv,
+  resolveCommandForLogs,
   runChildProcess,
 } from "../utils.js";
 
@@ -21,6 +23,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   for (const [k, v] of Object.entries(envConfig)) {
     if (typeof v === "string") env[k] = v;
   }
+  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  const resolvedCommand = await resolveCommandForLogs(command, cwd, runtimeEnv);
+  const loggedEnv = buildInvocationEnvForLogs(env, {
+    runtimeEnv,
+    includeRuntimeKeys: ["HOME"],
+    resolvedCommand,
+  });
 
   const timeoutSec = asNumber(config.timeoutSec, 0);
   const graceSec = asNumber(config.graceSec, 15);
@@ -28,10 +37,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (onMeta) {
     await onMeta({
       adapterType: "process",
-      command,
+      command: resolvedCommand,
       cwd,
       commandArgs: args,
-      env: redactEnvForLogs(env),
+      env: loggedEnv,
     });
   }
 

server/src/adapters/registry.ts

@@ -44,6 +44,7 @@ import {
 } from "@paperclipai/adapter-opencode-local/server";
 import {
   agentConfigurationDoc as openCodeAgentConfigurationDoc,
+  models as openCodeModels,
 } from "@paperclipai/adapter-opencode-local";
 import {
   execute as openclawGatewayExecute,
@@ -70,6 +71,9 @@ import {
   execute as hermesExecute,
   testEnvironment as hermesTestEnvironment,
   sessionCodec as hermesSessionCodec,
+  listSkills as hermesListSkills,
+  syncSkills as hermesSyncSkills,
+  detectModel as detectModelFromHermes,
 } from "hermes-paperclip-adapter/server";
 import {
   agentConfigurationDoc as hermesAgentConfigurationDoc,
@@ -150,8 +154,8 @@ const openCodeLocalAdapter: ServerAdapterModule = {
   listSkills: listOpenCodeSkills,
   syncSkills: syncOpenCodeSkills,
   sessionCodec: openCodeSessionCodec,
+  models: openCodeModels,
   sessionManagement: getAdapterSessionManagement("opencode_local") ?? undefined,
-  models: [],
   listModels: listOpenCodeModels,
   supportsLocalAgentJwt: true,
   agentConfigurationDoc: openCodeAgentConfigurationDoc,
@@ -176,9 +180,12 @@ const hermesLocalAdapter: ServerAdapterModule = {
   execute: hermesExecute,
   testEnvironment: hermesTestEnvironment,
   sessionCodec: hermesSessionCodec,
+  listSkills: hermesListSkills,
+  syncSkills: hermesSyncSkills,
   models: hermesModels,
   supportsLocalAgentJwt: true,
   agentConfigurationDoc: hermesAgentConfigurationDoc,
+  detectModel: () => detectModelFromHermes(),
 };
 
 const adaptersByType = new Map<string, ServerAdapterModule>(
@@ -219,6 +226,15 @@ export function listServerAdapters(): ServerAdapterModule[] {
   return Array.from(adaptersByType.values());
 }
 
+export async function detectAdapterModel(
+  type: string,
+): Promise<{ model: string; provider: string; source: string } | null> {
+  const adapter = adaptersByType.get(type);
+  if (!adapter?.detectModel) return null;
+  const detected = await adapter.detectModel();
+  return detected ? { model: detected.model, provider: detected.provider, source: detected.source } : null;
+}
+
 export function findServerAdapter(type: string): ServerAdapterModule | null {
   return adaptersByType.get(type) ?? null;
 }

server/src/adapters/utils.ts

@@ -1,32 +1,78 @@
 // Re-export everything from the shared adapter-utils/server-utils package.
 // This file is kept as a convenience shim so existing in-tree
 // imports (process/, http/, heartbeat.ts) don't need rewriting.
+import type { ChildProcess } from "node:child_process";
 import { logger } from "../middleware/logger.js";
-export {
-  type RunProcessResult,
-  runningProcesses,
-  MAX_CAPTURE_BYTES,
-  MAX_EXCERPT_BYTES,
-  parseObject,
-  asString,
-  asNumber,
-  asBoolean,
-  asStringArray,
-  parseJson,
-  appendWithCap,
-  resolvePathValue,
-  renderTemplate,
-  redactEnvForLogs,
-  buildPaperclipEnv,
-  defaultPathForPlatform,
-  ensurePathInEnv,
-  ensureAbsoluteDirectory,
-  ensureCommandResolvable,
-} from "@paperclipai/adapter-utils/server-utils";
+import * as serverUtils from "@paperclipai/adapter-utils/server-utils";
+export type { RunProcessResult } from "@paperclipai/adapter-utils/server-utils";
+
+type BuildInvocationEnvForLogsOptions = {
+  runtimeEnv?: NodeJS.ProcessEnv | Record<string, string>;
+  includeRuntimeKeys?: string[];
+  resolvedCommand?: string | null;
+  resolvedCommandEnvKey?: string;
+};
+
+export const runningProcesses: Map<string, { child: ChildProcess; graceSec: number }> =
+  serverUtils.runningProcesses;
+export const MAX_CAPTURE_BYTES = serverUtils.MAX_CAPTURE_BYTES;
+export const MAX_EXCERPT_BYTES = serverUtils.MAX_EXCERPT_BYTES;
+export const parseObject = serverUtils.parseObject;
+export const asString = serverUtils.asString;
+export const asNumber = serverUtils.asNumber;
+export const asBoolean = serverUtils.asBoolean;
+export const asStringArray = serverUtils.asStringArray;
+export const parseJson = serverUtils.parseJson;
+export const appendWithCap = serverUtils.appendWithCap;
+export const resolvePathValue = serverUtils.resolvePathValue;
+export const renderTemplate = serverUtils.renderTemplate;
+export const redactEnvForLogs = serverUtils.redactEnvForLogs;
+export const buildPaperclipEnv = serverUtils.buildPaperclipEnv;
+export const defaultPathForPlatform = serverUtils.defaultPathForPlatform;
+export const ensurePathInEnv = serverUtils.ensurePathInEnv;
+export const ensureAbsoluteDirectory = serverUtils.ensureAbsoluteDirectory;
+export const ensureCommandResolvable = serverUtils.ensureCommandResolvable;
+export const resolveCommandForLogs = serverUtils.resolveCommandForLogs;
+
+export function buildInvocationEnvForLogs(
+  env: Record<string, string>,
+  options: BuildInvocationEnvForLogsOptions = {},
+): Record<string, string> {
+  // TODO: Remove this fallback once @paperclipai/adapter-utils exports buildInvocationEnvForLogs everywhere we consume it.
+  const maybeBuildInvocationEnvForLogs = (
+    serverUtils as typeof serverUtils & {
+      buildInvocationEnvForLogs?: (
+        env: Record<string, string>,
+        options?: BuildInvocationEnvForLogsOptions,
+      ) => Record<string, string>;
+    }
+  ).buildInvocationEnvForLogs;
+
+  if (typeof maybeBuildInvocationEnvForLogs === "function") {
+    return maybeBuildInvocationEnvForLogs(env, options);
+  }
+
+  const merged: Record<string, string> = { ...env };
+  const runtimeEnv = options.runtimeEnv ?? {};
+
+  for (const key of options.includeRuntimeKeys ?? []) {
+    if (key in merged) continue;
+    const value = runtimeEnv[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    merged[key] = value;
+  }
+
+  const resolvedCommand = options.resolvedCommand?.trim();
+  if (resolvedCommand) {
+    merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = resolvedCommand;
+  }
+
+  return redactEnvForLogs(merged);
+}
 
 // Re-export runChildProcess with the server's pino logger wired in.
-import { runChildProcess as _runChildProcess } from "@paperclipai/adapter-utils/server-utils";
 import type { RunProcessResult } from "@paperclipai/adapter-utils/server-utils";
+const _runChildProcess = serverUtils.runChildProcess;
 
 export async function runChildProcess(
   runId: string,

server/src/config.ts

@@ -3,6 +3,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { config as loadDotenv } from "dotenv";
 import { resolvePaperclipEnvPath } from "./paths.js";
+import { maybeRepairLegacyWorktreeConfigAndEnvFiles } from "./worktree-config.js";
 import {
   AUTH_BASE_URL_MODES,
   DEPLOYMENT_EXPOSURES,
@@ -36,6 +37,8 @@ if (!isSameFile && existsSync(CWD_ENV_PATH)) {
   loadDotenv({ path: CWD_ENV_PATH, override: false, quiet: true });
 }
 
+maybeRepairLegacyWorktreeConfigAndEnvFiles();
+
 type DatabaseMode = "embedded-postgres" | "postgres";
 
 export interface Config {

server/src/dev-watch-ignore.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function toGlobstarPath(candidate: string): string {
+  return `${candidate.replaceAll(path.sep, "/")}/**`;
+}
+
+function addIgnorePath(target: Set<string>, candidate: string): void {
+  target.add(candidate);
+  target.add(toGlobstarPath(candidate));
+  try {
+    const realPath = fs.realpathSync(candidate);
+    target.add(realPath);
+    target.add(toGlobstarPath(realPath));
+  } catch {
+    // Ignore paths that do not exist in the current checkout.
+  }
+}
+
+export function resolveServerDevWatchIgnorePaths(serverRoot: string): string[] {
+  const ignorePaths = new Set<string>([
+    "**/{node_modules,bower_components,vendor}/**",
+    "**/.vite-temp/**",
+  ]);
+
+  for (const relativePath of [
+    "../ui/node_modules",
+    "../ui/node_modules/.vite-temp",
+    "../ui/.vite",
+    "../ui/dist",
+  ]) {
+    addIgnorePath(ignorePaths, path.resolve(serverRoot, relativePath));
+  }
+
+  return [...ignorePaths];
+}

server/src/index.ts

@@ -10,9 +10,11 @@ import { and, eq } from "drizzle-orm";
 import {
   createDb,
   ensurePostgresDatabase,
+  formatEmbeddedPostgresError,
   getPostgresDataDirectory,
   inspectMigrations,
   applyPendingMigrations,
+  createEmbeddedPostgresLogBuffer,
   reconcilePendingMigrationHistory,
   formatDatabaseBackupResult,
   runDatabaseBackup,
@@ -30,6 +32,7 @@ import { heartbeatService, reconcilePersistedRuntimeServicesOnStartup, routineSe
 import { createStorageServiceFromConfig } from "./storage/index.js";
 import { printStartupBanner } from "./startup-banner.js";
 import { getBoardClaimWarningUrl, initializeBoardClaimChallenge } from "./board-claim.js";
+import { maybePersistWorktreeRuntimePorts } from "./worktree-config.js";
 
 type BetterAuthSessionUser = {
   id: string;
@@ -69,7 +72,7 @@ export interface StartedServer {
 }
 
 export async function startServer(): Promise<StartedServer> {
-  const config = loadConfig();
+  let config = loadConfig();
   if (process.env.PAPERCLIP_SECRETS_PROVIDER === undefined) {
     process.env.PAPERCLIP_SECRETS_PROVIDER = config.secretsProvider;
   }
@@ -167,6 +170,18 @@ export async function startServer(): Promise<StartedServer> {
     const normalized = host.trim().toLowerCase();
     return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
   }
+
+  function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
+    if (!rawUrl) return undefined;
+    try {
+      const parsed = new URL(rawUrl);
+      if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+      parsed.port = String(port);
+      return parsed.toString();
+    } catch {
+      return rawUrl;
+    }
+  }
   
   const LOCAL_BOARD_USER_ID = "local-board";
   const LOCAL_BOARD_USER_EMAIL = "local@paperclip.local";
@@ -233,6 +248,7 @@ export async function startServer(): Promise<StartedServer> {
   let embeddedPostgresStartedByThisProcess = false;
   let migrationSummary: MigrationSummary = "skipped";
   let activeDatabaseConnectionString: string;
+  let resolvedEmbeddedPostgresPort: number | null = null;
   let startupDbInfo:
     | { mode: "external-postgres"; connectionString: string }
     | { mode: "embedded-postgres"; dataDir: string; port: number };
@@ -258,29 +274,31 @@ export async function startServer(): Promise<StartedServer> {
     const dataDir = resolve(config.embeddedPostgresDataDir);
     const configuredPort = config.embeddedPostgresPort;
     let port = configuredPort;
-    const embeddedPostgresLogBuffer: string[] = [];
-    const EMBEDDED_POSTGRES_LOG_BUFFER_LIMIT = 120;
+    const logBuffer = createEmbeddedPostgresLogBuffer(120);
     const verboseEmbeddedPostgresLogs = process.env.PAPERCLIP_EMBEDDED_POSTGRES_VERBOSE === "true";
     const appendEmbeddedPostgresLog = (message: unknown) => {
-      const text = typeof message === "string" ? message : message instanceof Error ? message.message : String(message ?? "");
-      for (const lineRaw of text.split(/\r?\n/)) {
+      logBuffer.append(message);
+      if (!verboseEmbeddedPostgresLogs) {
+        return;
+      }
+      const lines = typeof message === "string"
+        ? message.split(/\r?\n/)
+        : message instanceof Error
+          ? [message.message]
+          : [String(message ?? "")];
+      for (const lineRaw of lines) {
         const line = lineRaw.trim();
         if (!line) continue;
-        embeddedPostgresLogBuffer.push(line);
-        if (embeddedPostgresLogBuffer.length > EMBEDDED_POSTGRES_LOG_BUFFER_LIMIT) {
-          embeddedPostgresLogBuffer.splice(0, embeddedPostgresLogBuffer.length - EMBEDDED_POSTGRES_LOG_BUFFER_LIMIT);
-        }
-        if (verboseEmbeddedPostgresLogs) {
-          logger.info({ embeddedPostgresLog: line }, "embedded-postgres");
-        }
+        logger.info({ embeddedPostgresLog: line }, "embedded-postgres");
       }
     };
     const logEmbeddedPostgresFailure = (phase: "initialise" | "start", err: unknown) => {
-      if (embeddedPostgresLogBuffer.length > 0) {
+      const recentLogs = logBuffer.getRecentLogs();
+      if (recentLogs.length > 0) {
         logger.error(
           {
             phase,
-            recentLogs: embeddedPostgresLogBuffer,
+            recentLogs,
             err,
           },
           "Embedded PostgreSQL failed; showing buffered startup logs",
@@ -357,7 +375,10 @@ export async function startServer(): Promise<StartedServer> {
             await embeddedPostgres.initialise();
           } catch (err) {
             logEmbeddedPostgresFailure("initialise", err);
-            throw err;
+            throw formatEmbeddedPostgresError(err, {
+              fallbackMessage: `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${port}`,
+              recentLogs: logBuffer.getRecentLogs(),
+            });
           }
         } else {
           logger.info(`Embedded PostgreSQL cluster already exists (${clusterVersionFile}); skipping init`);
@@ -371,7 +392,10 @@ export async function startServer(): Promise<StartedServer> {
           await embeddedPostgres.start();
         } catch (err) {
           logEmbeddedPostgresFailure("start", err);
-          throw err;
+          throw formatEmbeddedPostgresError(err, {
+            fallbackMessage: `Failed to start embedded PostgreSQL on port ${port}`,
+            recentLogs: logBuffer.getRecentLogs(),
+          });
         }
         embeddedPostgresStartedByThisProcess = true;
       }
@@ -395,6 +419,7 @@ export async function startServer(): Promise<StartedServer> {
     db = createDb(embeddedConnectionString);
     logger.info("Embedded PostgreSQL ready");
     activeDatabaseConnectionString = embeddedConnectionString;
+    resolvedEmbeddedPostgresPort = port;
     startupDbInfo = { mode: "embedded-postgres", dataDir, port };
   }
   
@@ -476,6 +501,19 @@ export async function startServer(): Promise<StartedServer> {
   }
   
   const listenPort = await detectPort(config.port);
+  if (listenPort !== config.port) {
+    config.port = listenPort;
+  }
+  if (resolvedEmbeddedPostgresPort !== null && resolvedEmbeddedPostgresPort !== config.embeddedPostgresPort) {
+    config.embeddedPostgresPort = resolvedEmbeddedPostgresPort;
+  }
+  if (config.authBaseUrlMode === "explicit" && config.authPublicBaseUrl) {
+    config.authPublicBaseUrl = rewriteLocalUrlPort(config.authPublicBaseUrl, listenPort);
+  }
+  maybePersistWorktreeRuntimePorts({
+    serverPort: listenPort,
+    databasePort: resolvedEmbeddedPostgresPort,
+  });
   const uiMode = config.uiDevMiddleware ? "vite-dev" : config.serveUi ? "static" : "none";
   const storageService = createStorageServiceFromConfig(config);
   const app = await createApp(db as any, {

server/src/middleware/board-mutation-guard.ts

@@ -18,7 +18,8 @@ function parseOrigin(value: string | undefined) {
 
 function trustedOriginsForRequest(req: Request) {
   const origins = new Set(DEFAULT_DEV_ORIGINS.map((value) => value.toLowerCase()));
-  const host = req.header("host")?.trim();
+  const forwardedHost = req.header("x-forwarded-host")?.split(",")[0]?.trim();
+  const host = forwardedHost || req.header("host")?.trim();
   if (host) {
     origins.add(`http://${host}`.toLowerCase());
     origins.add(`https://${host}`.toLowerCase());

server/src/onboarding-assets/ceo/AGENTS.md

@@ -1,9 +1,39 @@
-You are the CEO.
+You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.
 
 Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
 
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
 
+## Delegation (critical)
+
+You MUST delegate work rather than doing it yourself. When a task is assigned to you:
+
+1. **Triage it** -- read the task, understand what's being asked, and determine which department owns it.
+2. **Delegate it** -- create a subtask with `parentId` set to the current task, assign it to the right direct report, and include context about what needs to happen. Use these routing rules:
+   - **Code, bugs, features, infra, devtools, technical tasks** → CTO
+   - **Marketing, content, social media, growth, devrel** → CMO
+   - **UX, design, user research, design-system** → UXDesigner
+   - **Cross-functional or unclear** → break into separate subtasks for each department, or assign to the CTO if it's primarily technical with a design component
+   - If the right report doesn't exist yet, use the `paperclip-create-agent` skill to hire one before delegating.
+3. **Do NOT write code, implement features, or fix bugs yourself.** Your reports exist for this. Even if a task seems small or quick, delegate it.
+4. **Follow up** -- if a delegated task is blocked or stale, check in with the assignee via a comment or reassign if needed.
+
+## What you DO personally
+
+- Set priorities and make product decisions
+- Resolve cross-team conflicts or ambiguity
+- Communicate with the board (human users)
+- Approve or reject proposals from your reports
+- Hire new agents when the team needs capacity
+- Unblock your direct reports when they escalate to you
+
+## Keeping work moving
+
+- Don't let tasks sit idle. If you delegate something, check that it's progressing.
+- If a report is blocked, help unblock them -- escalate to the board if needed.
+- If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.
+- You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).
+
 ## Memory and Planning
 
 You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.

server/src/onboarding-assets/ceo/HEARTBEAT.md

@@ -37,7 +37,7 @@ If `PAPERCLIP_APPROVAL_ID` is set:
 
 ## 6. Delegation
 
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
+- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`. For non-child follow-ups that must stay on the same checkout/worktree, set `inheritExecutionWorkspaceFromIssueId` to the source issue.
 - Use `paperclip-create-agent` skill when hiring new agents.
 - Assign work to the right agent for the job.
 

server/src/routes/access.ts

@@ -14,6 +14,7 @@ import type { Db } from "@paperclipai/db";
 import {
   agentApiKeys,
   authUsers,
+  companies,
   invites,
   joinRequests
 } from "@paperclipai/db";
@@ -856,7 +857,8 @@ export function normalizeAgentDefaultsForJoin(input: {
 function toInviteSummaryResponse(
   req: Request,
   token: string,
-  invite: typeof invites.$inferSelect
+  invite: typeof invites.$inferSelect,
+  companyName: string | null = null
 ) {
   const baseUrl = requestBaseUrl(req);
   const onboardingPath = `/api/invites/${token}/onboarding`;
@@ -865,6 +867,7 @@ function toInviteSummaryResponse(
   return {
     id: invite.id,
     companyId: invite.companyId,
+    companyName,
     inviteType: invite.inviteType,
     allowedJoinTypes: invite.allowedJoinTypes,
     expiresAt: invite.expiresAt,
@@ -993,6 +996,7 @@ function buildInviteOnboardingManifest(
   token: string,
   invite: typeof invites.$inferSelect,
   opts: {
+    companyName?: string | null;
     deploymentMode: DeploymentMode;
     deploymentExposure: DeploymentExposure;
     bindHost: string;
@@ -1024,7 +1028,12 @@ function buildInviteOnboardingManifest(
   });
 
   return {
-    invite: toInviteSummaryResponse(req, token, invite),
+    invite: toInviteSummaryResponse(
+      req,
+      token,
+      invite,
+      opts.companyName ?? null
+    ),
     onboarding: {
       instructions:
         "Join as an OpenClaw Gateway agent, save your one-time claim secret, wait for board approval, then claim your API key. Save the claim response token to ~/.openclaw/workspace/paperclip-claimed-api-key.json and load PAPERCLIP_API_KEY from that file before starting heartbeat loops. You MUST submit adapterType='openclaw_gateway', set agentDefaultsPayload.url to your ws:// or wss:// OpenClaw gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token (or legacy x-openclaw-auth).",
@@ -1084,6 +1093,7 @@ export function buildInviteOnboardingTextDocument(
   token: string,
   invite: typeof invites.$inferSelect,
   opts: {
+    companyName?: string | null;
     deploymentMode: DeploymentMode;
     deploymentExposure: DeploymentExposure;
     bindHost: string;
@@ -1133,6 +1143,10 @@ export function buildInviteOnboardingTextDocument(
     - expiresAt: ${invite.expiresAt.toISOString()}
   `);
 
+  if (manifest.invite.companyName) {
+    lines.push(`- companyName: ${manifest.invite.companyName}`);
+  }
+
   if (onboarding.inviteMessage) {
     appendBlock(`
       ## Message from inviter
@@ -1882,6 +1896,16 @@ export function accessRoutes(
     return { token, created, normalizedAgentMessage };
   }
 
+  async function getInviteCompanyName(companyId: string | null) {
+    if (!companyId) return null;
+    const company = await db
+      .select({ name: companies.name })
+      .from(companies)
+      .where(eq(companies.id, companyId))
+      .then((rows) => rows[0] ?? null);
+    return company?.name ?? null;
+  }
+
   router.get("/skills/available", (_req, res) => {
     res.json({ skills: listAvailableSkills() });
   });
@@ -1942,11 +1966,18 @@ export function accessRoutes(
         }
       });
 
-      const inviteSummary = toInviteSummaryResponse(req, token, created);
+      const companyName = await getInviteCompanyName(created.companyId);
+      const inviteSummary = toInviteSummaryResponse(
+        req,
+        token,
+        created,
+        companyName
+      );
       res.status(201).json({
         ...created,
         token,
         inviteUrl: `/invite/${token}`,
+        companyName,
         onboardingTextPath: inviteSummary.onboardingTextPath,
         onboardingTextUrl: inviteSummary.onboardingTextUrl,
         inviteMessage: inviteSummary.inviteMessage
@@ -1987,11 +2018,18 @@ export function accessRoutes(
         }
       });
 
-      const inviteSummary = toInviteSummaryResponse(req, token, created);
+      const companyName = await getInviteCompanyName(created.companyId);
+      const inviteSummary = toInviteSummaryResponse(
+        req,
+        token,
+        created,
+        companyName
+      );
       res.status(201).json({
         ...created,
         token,
         inviteUrl: `/invite/${token}`,
+        companyName,
         onboardingTextPath: inviteSummary.onboardingTextPath,
         onboardingTextUrl: inviteSummary.onboardingTextUrl,
         inviteMessage: inviteSummary.inviteMessage
@@ -2016,7 +2054,8 @@ export function accessRoutes(
       throw notFound("Invite not found");
     }
 
-    res.json(toInviteSummaryResponse(req, token, invite));
+    const companyName = await getInviteCompanyName(invite.companyId);
+    res.json(toInviteSummaryResponse(req, token, invite, companyName));
   });
 
   router.get("/invites/:token/onboarding", async (req, res) => {
@@ -2031,7 +2070,11 @@ export function accessRoutes(
       throw notFound("Invite not found");
     }
 
-    res.json(buildInviteOnboardingManifest(req, token, invite, opts));
+    const companyName = await getInviteCompanyName(invite.companyId);
+    res.json(buildInviteOnboardingManifest(req, token, invite, {
+      ...opts,
+      companyName
+    }));
   });
 
   router.get("/invites/:token/onboarding.txt", async (req, res) => {
@@ -2046,9 +2089,15 @@ export function accessRoutes(
       throw notFound("Invite not found");
     }
 
+    const companyName = await getInviteCompanyName(invite.companyId);
     res
       .type("text/plain; charset=utf-8")
-      .send(buildInviteOnboardingTextDocument(req, token, invite, opts));
+      .send(
+        buildInviteOnboardingTextDocument(req, token, invite, {
+          ...opts,
+          companyName
+        })
+      );
   });
 
   router.get("/invites/:token/test-resolution", async (req, res) => {
@@ -2458,11 +2507,15 @@ export function accessRoutes(
 
       const response = toJoinRequestResponse(created);
       if (claimSecret) {
+        const companyName = await getInviteCompanyName(invite.companyId);
         const onboardingManifest = buildInviteOnboardingManifest(
           req,
           token,
           invite,
-          opts
+          {
+            ...opts,
+            companyName
+          }
         );
         res.status(202).json({
           ...response,

server/src/routes/agents.ts

@@ -6,6 +6,7 @@ import { agents as agentsTable, companies, heartbeatRuns } from "@paperclipai/db
 import { and, desc, eq, inArray, not, sql } from "drizzle-orm";
 import {
   agentSkillSyncSchema,
+  agentMineInboxQuerySchema,
   createAgentKeySchema,
   createAgentHireSchema,
   createAgentSchema,
@@ -44,7 +45,7 @@ import {
 } from "../services/index.js";
 import { conflict, forbidden, notFound, unprocessable } from "../errors.js";
 import { assertBoard, assertCompanyAccess, assertInstanceAdmin, getActorInfo } from "./authz.js";
-import { findServerAdapter, listAdapterModels } from "../adapters/index.js";
+import { findServerAdapter, listAdapterModels, detectAdapterModel } from "../adapters/index.js";
 import { redactEventPayload } from "../redaction.js";
 import { redactCurrentUserValue } from "../log-redaction.js";
 import { renderOrgChartSvg, renderOrgChartPng, type OrgNode, type OrgChartStyle, ORG_CHART_STYLES } from "./org-chart-svg.js";
@@ -671,6 +672,15 @@ export function agentRoutes(db: Db) {
     res.json(models);
   });
 
+  router.get("/companies/:companyId/adapters/:type/detect-model", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const type = req.params.type as string;
+
+    const detected = await detectAdapterModel(type);
+    res.json(detected);
+  });
+
   router.post(
     "/companies/:companyId/adapters/:type/test-environment",
     validate(testAdapterEnvironmentSchema),
@@ -997,6 +1007,23 @@ export function agentRoutes(db: Db) {
     );
   });
 
+  router.get("/agents/me/inbox/mine", async (req, res) => {
+    if (req.actor.type !== "agent" || !req.actor.agentId || !req.actor.companyId) {
+      res.status(401).json({ error: "Agent authentication required" });
+      return;
+    }
+
+    const query = agentMineInboxQuerySchema.parse(req.query);
+    const issuesSvc = issueService(db);
+    const rows = await issuesSvc.list(req.actor.companyId, {
+      touchedByUserId: query.userId,
+      inboxArchivedByUserId: query.userId,
+      status: query.status,
+    });
+
+    res.json(rows);
+  });
+
   router.get("/agents/:id", async (req, res) => {
     const id = req.params.id as string;
     const agent = await svc.getById(id);

server/src/routes/execution-workspaces.ts

@@ -5,15 +5,16 @@ import { issues, projects, projectWorkspaces } from "@paperclipai/db";
 import { updateExecutionWorkspaceSchema } from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
 import { executionWorkspaceService, logActivity, workspaceOperationService } from "../services/index.js";
+import { mergeExecutionWorkspaceConfig, readExecutionWorkspaceConfig } from "../services/execution-workspaces.js";
 import { parseProjectExecutionWorkspacePolicy } from "../services/execution-workspace-policy.js";
+import { readProjectWorkspaceRuntimeConfig } from "../services/project-workspace-runtime-config.js";
 import {
   cleanupExecutionWorkspaceArtifacts,
+  startRuntimeServicesForWorkspaceControl,
   stopRuntimeServicesForExecutionWorkspace,
 } 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);
@@ -43,6 +44,202 @@ 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.get("/execution-workspaces/:id/workspace-operations", 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 operations = await workspaceOperationsSvc.listForExecutionWorkspace(id);
+    res.json(operations);
+  });
+
+  router.post("/execution-workspaces/:id/runtime-services/:action", async (req, res) => {
+    const id = req.params.id as string;
+    const action = String(req.params.action ?? "").trim().toLowerCase();
+    if (action !== "start" && action !== "stop" && action !== "restart") {
+      res.status(404).json({ error: "Runtime service action not found" });
+      return;
+    }
+
+    const existing = await svc.getById(id);
+    if (!existing) {
+      res.status(404).json({ error: "Execution workspace not found" });
+      return;
+    }
+    assertCompanyAccess(req, existing.companyId);
+
+    const workspaceCwd = existing.cwd;
+    if (!workspaceCwd) {
+      res.status(422).json({ error: "Execution workspace needs a local path before Paperclip can manage local runtime services" });
+      return;
+    }
+
+    const projectWorkspace = existing.projectWorkspaceId
+      ? await db
+          .select({
+            id: projectWorkspaces.id,
+            cwd: projectWorkspaces.cwd,
+            repoUrl: projectWorkspaces.repoUrl,
+            repoRef: projectWorkspaces.repoRef,
+            defaultRef: projectWorkspaces.defaultRef,
+            metadata: projectWorkspaces.metadata,
+          })
+          .from(projectWorkspaces)
+          .where(
+            and(
+              eq(projectWorkspaces.id, existing.projectWorkspaceId),
+              eq(projectWorkspaces.companyId, existing.companyId),
+            ),
+          )
+          .then((rows) => rows[0] ?? null)
+      : null;
+    const projectWorkspaceRuntime = readProjectWorkspaceRuntimeConfig(
+      (projectWorkspace?.metadata as Record<string, unknown> | null) ?? null,
+    )?.workspaceRuntime ?? null;
+    const effectiveRuntimeConfig = existing.config?.workspaceRuntime ?? projectWorkspaceRuntime ?? null;
+
+    if ((action === "start" || action === "restart") && !effectiveRuntimeConfig) {
+      res.status(422).json({ error: "Execution workspace has no runtime service configuration or inherited project workspace default" });
+      return;
+    }
+
+    const actor = getActorInfo(req);
+    const recorder = workspaceOperationsSvc.createRecorder({
+      companyId: existing.companyId,
+      executionWorkspaceId: existing.id,
+    });
+    let runtimeServiceCount = existing.runtimeServices?.length ?? 0;
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+
+    const operation = await recorder.recordOperation({
+      phase: action === "stop" ? "workspace_teardown" : "workspace_provision",
+      command: `workspace runtime ${action}`,
+      cwd: existing.cwd,
+      metadata: {
+        action,
+        executionWorkspaceId: existing.id,
+      },
+      run: async () => {
+        const onLog = async (stream: "stdout" | "stderr", chunk: string) => {
+          if (stream === "stdout") stdout.push(chunk);
+          else stderr.push(chunk);
+        };
+
+        if (action === "stop" || action === "restart") {
+          await stopRuntimeServicesForExecutionWorkspace({
+            db,
+            executionWorkspaceId: existing.id,
+            workspaceCwd,
+          });
+        }
+
+        if (action === "start" || action === "restart") {
+          const startedServices = await startRuntimeServicesForWorkspaceControl({
+            db,
+            actor: {
+              id: actor.agentId ?? null,
+              name: actor.actorType === "user" ? "Board" : "Agent",
+              companyId: existing.companyId,
+            },
+            issue: existing.sourceIssueId
+              ? {
+                  id: existing.sourceIssueId,
+                  identifier: null,
+                  title: existing.name,
+                }
+              : null,
+            workspace: {
+              baseCwd: workspaceCwd,
+              source: existing.mode === "shared_workspace" ? "project_primary" : "task_session",
+              projectId: existing.projectId,
+              workspaceId: existing.projectWorkspaceId,
+              repoUrl: existing.repoUrl,
+              repoRef: existing.baseRef,
+              strategy: existing.strategyType === "git_worktree" ? "git_worktree" : "project_primary",
+              cwd: workspaceCwd,
+              branchName: existing.branchName,
+              worktreePath: existing.strategyType === "git_worktree" ? workspaceCwd : null,
+              warnings: [],
+              created: false,
+            },
+            executionWorkspaceId: existing.id,
+            config: { workspaceRuntime: effectiveRuntimeConfig },
+            adapterEnv: {},
+            onLog,
+          });
+          runtimeServiceCount = startedServices.length;
+        } else {
+          runtimeServiceCount = 0;
+        }
+
+        const metadata = mergeExecutionWorkspaceConfig(existing.metadata as Record<string, unknown> | null, {
+          desiredState: action === "stop" ? "stopped" : "running",
+        });
+        await svc.update(existing.id, { metadata });
+
+        return {
+          status: "succeeded",
+          stdout: stdout.join(""),
+          stderr: stderr.join(""),
+          system:
+            action === "stop"
+              ? "Stopped execution workspace runtime services.\n"
+              : action === "restart"
+                ? "Restarted execution workspace runtime services.\n"
+                : "Started execution workspace runtime services.\n",
+          metadata: {
+            runtimeServiceCount,
+          },
+        };
+      },
+    });
+
+    const workspace = await svc.getById(id);
+    if (!workspace) {
+      res.status(404).json({ error: "Execution workspace not found" });
+      return;
+    }
+
+    await logActivity(db, {
+      companyId: existing.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: `execution_workspace.runtime_${action}`,
+      entityType: "execution_workspace",
+      entityId: existing.id,
+      details: {
+        runtimeServiceCount,
+      },
+    });
+
+    res.json({
+      workspace,
+      operation,
+    });
+  });
+
   router.patch("/execution-workspaces/:id", validate(updateExecutionWorkspaceSchema), async (req, res) => {
     const id = req.params.id as string;
     const existing = await svc.getById(id);
@@ -52,25 +249,43 @@ export function executionWorkspaceRoutes(db: Db) {
     }
     assertCompanyAccess(req, existing.companyId);
     const patch: Record<string, unknown> = {
-      ...req.body,
-      ...(req.body.cleanupEligibleAt ? { cleanupEligibleAt: new Date(req.body.cleanupEligibleAt) } : {}),
+      ...(req.body.name === undefined ? {} : { name: req.body.name }),
+      ...(req.body.cwd === undefined ? {} : { cwd: req.body.cwd }),
+      ...(req.body.repoUrl === undefined ? {} : { repoUrl: req.body.repoUrl }),
+      ...(req.body.baseRef === undefined ? {} : { baseRef: req.body.baseRef }),
+      ...(req.body.branchName === undefined ? {} : { branchName: req.body.branchName }),
+      ...(req.body.providerRef === undefined ? {} : { providerRef: req.body.providerRef }),
+      ...(req.body.status === undefined ? {} : { status: req.body.status }),
+      ...(req.body.cleanupReason === undefined ? {} : { cleanupReason: req.body.cleanupReason }),
+      ...(req.body.cleanupEligibleAt !== undefined
+        ? { cleanupEligibleAt: req.body.cleanupEligibleAt ? new Date(req.body.cleanupEligibleAt) : null }
+        : {}),
     };
+    if (req.body.metadata !== undefined || req.body.config !== undefined) {
+      const requestedMetadata = req.body.metadata === undefined
+        ? (existing.metadata as Record<string, unknown> | null)
+        : (req.body.metadata as Record<string, unknown> | null);
+      patch.metadata = req.body.config === undefined
+        ? requestedMetadata
+        : mergeExecutionWorkspaceConfig(requestedMetadata, req.body.config ?? null);
+    }
     let workspace = existing;
     let cleanupWarnings: string[] = [];
+    const configForCleanup = readExecutionWorkspaceConfig(
+      ((patch.metadata as Record<string, unknown> | null | undefined) ?? (existing.metadata as Record<string, unknown> | null)) ?? null,
+    );
 
     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;
       }
@@ -88,6 +303,21 @@ export function executionWorkspaceRoutes(db: Db) {
       }
       workspace = archivedWorkspace;
 
+      if (existing.mode === "shared_workspace") {
+        await db
+          .update(issues)
+          .set({
+            executionWorkspaceId: null,
+            updatedAt: new Date(),
+          })
+          .where(
+            and(
+              eq(issues.companyId, existing.companyId),
+              eq(issues.executionWorkspaceId, existing.id),
+            ),
+          );
+      }
+
       try {
         await stopRuntimeServicesForExecutionWorkspace({
           db,
@@ -101,7 +331,7 @@ export function executionWorkspaceRoutes(db: Db) {
                 cleanupCommand: projectWorkspaces.cleanupCommand,
               })
               .from(projectWorkspaces)
-              .where(
+            .where(
                 and(
                   eq(projectWorkspaces.id, existing.projectWorkspaceId),
                   eq(projectWorkspaces.companyId, existing.companyId),
@@ -121,7 +351,8 @@ export function executionWorkspaceRoutes(db: Db) {
         const cleanupResult = await cleanupExecutionWorkspaceArtifacts({
           workspace: existing,
           projectWorkspace,
-          teardownCommand: projectPolicy?.workspaceStrategy?.teardownCommand ?? null,
+          teardownCommand: configForCleanup?.teardownCommand ?? projectPolicy?.workspaceStrategy?.teardownCommand ?? null,
+          cleanupCommand: configForCleanup?.cleanupCommand ?? null,
           recorder: workspaceOperationsSvc.createRecorder({
             companyId: existing.companyId,
             executionWorkspaceId: existing.id,

server/src/routes/health.ts

@@ -29,6 +29,17 @@ export function healthRoutes(
       return;
     }
 
+    try {
+      await db.execute(sql`SELECT 1`);
+    } catch {
+      res.status(503).json({
+        status: "unhealthy",
+        version: serverVersion,
+        error: "database_unreachable",
+      });
+      return;
+    }
+
     let bootstrapStatus: "ready" | "bootstrap_pending" = "ready";
     let bootstrapInviteActive = false;
     if (opts.deploymentMode === "authenticated") {

server/src/routes/issues.ts

@@ -1,5 +1,6 @@
 import { Router, type Request, type Response } from "express";
 import multer from "multer";
+import { z } from "zod";
 import type { Db } from "@paperclipai/db";
 import {
   addIssueCommentSchema,
@@ -39,6 +40,9 @@ import { isAllowedContentType, MAX_ATTACHMENT_BYTES } from "../attachment-types.
 import { queueIssueAssignmentWakeup } from "../services/issue-assignment-wakeup.js";
 
 const MAX_ISSUE_COMMENT_LIMIT = 500;
+const updateIssueRouteSchema = updateIssueSchema.extend({
+  interrupt: z.boolean().optional(),
+});
 
 export function issueRoutes(db: Db, storage: StorageService) {
   const router = Router();
@@ -162,6 +166,30 @@ export function issueRoutes(db: Db, storage: StorageService) {
     return true;
   }
 
+  async function resolveActiveIssueRun(issue: {
+    id: string;
+    assigneeAgentId: string | null;
+    executionRunId?: string | null;
+  }) {
+    let runToInterrupt = issue.executionRunId ? await heartbeat.getRun(issue.executionRunId) : null;
+
+    if ((!runToInterrupt || runToInterrupt.status !== "running") && issue.assigneeAgentId) {
+      const activeRun = await heartbeat.getActiveRunForAgent(issue.assigneeAgentId);
+      const activeIssueId =
+        activeRun &&
+        activeRun.contextSnapshot &&
+        typeof activeRun.contextSnapshot === "object" &&
+        typeof (activeRun.contextSnapshot as Record<string, unknown>).issueId === "string"
+          ? ((activeRun.contextSnapshot as Record<string, unknown>).issueId as string)
+          : null;
+      if (activeRun && activeRun.status === "running" && activeIssueId === issue.id) {
+        runToInterrupt = activeRun;
+      }
+    }
+
+    return runToInterrupt?.status === "running" ? runToInterrupt : null;
+  }
+
   async function normalizeIssueIdentifier(rawId: string): Promise<string> {
     if (/^[A-Z]+-\d+$/i.test(rawId)) {
       const issue = await svc.getByIdentifier(rawId);
@@ -231,6 +259,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
     assertCompanyAccess(req, companyId);
     const assigneeUserFilterRaw = req.query.assigneeUserId as string | undefined;
     const touchedByUserFilterRaw = req.query.touchedByUserId as string | undefined;
+    const inboxArchivedByUserFilterRaw = req.query.inboxArchivedByUserId as string | undefined;
     const unreadForUserFilterRaw = req.query.unreadForUserId as string | undefined;
     const assigneeUserId =
       assigneeUserFilterRaw === "me" && req.actor.type === "board"
@@ -240,6 +269,10 @@ export function issueRoutes(db: Db, storage: StorageService) {
       touchedByUserFilterRaw === "me" && req.actor.type === "board"
         ? req.actor.userId
         : touchedByUserFilterRaw;
+    const inboxArchivedByUserId =
+      inboxArchivedByUserFilterRaw === "me" && req.actor.type === "board"
+        ? req.actor.userId
+        : inboxArchivedByUserFilterRaw;
     const unreadForUserId =
       unreadForUserFilterRaw === "me" && req.actor.type === "board"
         ? req.actor.userId
@@ -253,6 +286,10 @@ export function issueRoutes(db: Db, storage: StorageService) {
       res.status(403).json({ error: "touchedByUserId=me requires board authentication" });
       return;
     }
+    if (inboxArchivedByUserFilterRaw === "me" && (!inboxArchivedByUserId || req.actor.type !== "board")) {
+      res.status(403).json({ error: "inboxArchivedByUserId=me requires board authentication" });
+      return;
+    }
     if (unreadForUserFilterRaw === "me" && (!unreadForUserId || req.actor.type !== "board")) {
       res.status(403).json({ error: "unreadForUserId=me requires board authentication" });
       return;
@@ -264,8 +301,10 @@ export function issueRoutes(db: Db, storage: StorageService) {
       participantAgentId: req.query.participantAgentId as string | undefined,
       assigneeUserId,
       touchedByUserId,
+      inboxArchivedByUserId,
       unreadForUserId,
       projectId: req.query.projectId as string | undefined,
+      executionWorkspaceId: req.query.executionWorkspaceId as string | undefined,
       parentId: req.query.parentId as string | undefined,
       labelId: req.query.labelId as string | undefined,
       originKind: req.query.originKind as string | undefined,
@@ -755,6 +794,102 @@ export function issueRoutes(db: Db, storage: StorageService) {
     res.json(readState);
   });
 
+  router.delete("/issues/:id/read", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+    if (req.actor.type !== "board") {
+      res.status(403).json({ error: "Board authentication required" });
+      return;
+    }
+    if (!req.actor.userId) {
+      res.status(403).json({ error: "Board user context required" });
+      return;
+    }
+    const removed = await svc.markUnread(issue.companyId, issue.id, req.actor.userId);
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: issue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.read_unmarked",
+      entityType: "issue",
+      entityId: issue.id,
+      details: { userId: req.actor.userId },
+    });
+    res.json({ id: issue.id, removed });
+  });
+
+  router.post("/issues/:id/inbox-archive", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+    if (req.actor.type !== "board") {
+      res.status(403).json({ error: "Board authentication required" });
+      return;
+    }
+    if (!req.actor.userId) {
+      res.status(403).json({ error: "Board user context required" });
+      return;
+    }
+    const archiveState = await svc.archiveInbox(issue.companyId, issue.id, req.actor.userId, new Date());
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: issue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.inbox_archived",
+      entityType: "issue",
+      entityId: issue.id,
+      details: { userId: req.actor.userId, archivedAt: archiveState.archivedAt },
+    });
+    res.json(archiveState);
+  });
+
+  router.delete("/issues/:id/inbox-archive", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+    if (req.actor.type !== "board") {
+      res.status(403).json({ error: "Board authentication required" });
+      return;
+    }
+    if (!req.actor.userId) {
+      res.status(403).json({ error: "Board user context required" });
+      return;
+    }
+    const removed = await svc.unarchiveInbox(issue.companyId, issue.id, req.actor.userId);
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: issue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.inbox_unarchived",
+      entityType: "issue",
+      entityId: issue.id,
+      details: { userId: req.actor.userId },
+    });
+    res.json(removed ?? { ok: true });
+  });
+
   router.get("/issues/:id/approvals", async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);
@@ -865,7 +1000,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
     res.status(201).json(issue);
   });
 
-  router.patch("/issues/:id", validate(updateIssueSchema), async (req, res) => {
+  router.patch("/issues/:id", validate(updateIssueRouteSchema), async (req, res) => {
     const id = req.params.id as string;
     const existing = await svc.getById(id);
     if (!existing) {
@@ -895,7 +1030,45 @@ export function issueRoutes(db: Db, storage: StorageService) {
 
     const actor = getActorInfo(req);
     const isClosed = existing.status === "done" || existing.status === "cancelled";
-    const { comment: commentBody, reopen: reopenRequested, hiddenAt: hiddenAtRaw, ...updateFields } = req.body;
+    const {
+      comment: commentBody,
+      reopen: reopenRequested,
+      interrupt: interruptRequested,
+      hiddenAt: hiddenAtRaw,
+      ...updateFields
+    } = req.body;
+    let interruptedRunId: string | null = null;
+
+    if (interruptRequested) {
+      if (!commentBody) {
+        res.status(400).json({ error: "Interrupt is only supported when posting a comment" });
+        return;
+      }
+      if (req.actor.type !== "board") {
+        res.status(403).json({ error: "Only board users can interrupt active runs from issue comments" });
+        return;
+      }
+
+      const runToInterrupt = await resolveActiveIssueRun(existing);
+      if (runToInterrupt) {
+        const cancelled = await heartbeat.cancelRun(runToInterrupt.id);
+        if (cancelled) {
+          interruptedRunId = cancelled.id;
+          await logActivity(db, {
+            companyId: cancelled.companyId,
+            actorType: actor.actorType,
+            actorId: actor.actorId,
+            agentId: actor.agentId,
+            runId: actor.runId,
+            action: "heartbeat.cancelled",
+            entityType: "heartbeat_run",
+            entityId: cancelled.id,
+            details: { agentId: cancelled.agentId, source: "issue_comment_interrupt", issueId: existing.id },
+          });
+        }
+      }
+    }
+
     if (hiddenAtRaw !== undefined) {
       updateFields.hiddenAt = hiddenAtRaw ? new Date(hiddenAtRaw) : null;
     }
@@ -970,6 +1143,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
         identifier: issue.identifier,
         ...(commentBody ? { source: "comment" } : {}),
         ...(reopened ? { reopened: true, reopenedFrom: reopenFromStatus } : {}),
+        ...(interruptedRunId ? { interruptedRunId } : {}),
         _previous: hasFieldChanges ? previous : undefined,
       },
     });
@@ -996,6 +1170,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
           identifier: issue.identifier,
           issueTitle: issue.title,
           ...(reopened ? { reopened: true, reopenedFrom: reopenFromStatus, source: "comment" } : {}),
+          ...(interruptedRunId ? { interruptedRunId } : {}),
           ...(hasFieldChanges ? { updated: true } : {}),
         },
       });
@@ -1017,10 +1192,18 @@ export function issueRoutes(db: Db, storage: StorageService) {
           source: "assignment",
           triggerDetail: "system",
           reason: "issue_assigned",
-          payload: { issueId: issue.id, mutation: "update" },
+          payload: {
+            issueId: issue.id,
+            mutation: "update",
+            ...(interruptedRunId ? { interruptedRunId } : {}),
+          },
           requestedByActorType: actor.actorType,
           requestedByActorId: actor.actorId,
-          contextSnapshot: { issueId: issue.id, source: "issue.update" },
+          contextSnapshot: {
+            issueId: issue.id,
+            source: "issue.update",
+            ...(interruptedRunId ? { interruptedRunId } : {}),
+          },
         });
       }
 
@@ -1029,10 +1212,18 @@ export function issueRoutes(db: Db, storage: StorageService) {
           source: "automation",
           triggerDetail: "system",
           reason: "issue_status_changed",
-          payload: { issueId: issue.id, mutation: "update" },
+          payload: {
+            issueId: issue.id,
+            mutation: "update",
+            ...(interruptedRunId ? { interruptedRunId } : {}),
+          },
           requestedByActorType: actor.actorType,
           requestedByActorId: actor.actorId,
-          contextSnapshot: { issueId: issue.id, source: "issue.status_change" },
+          contextSnapshot: {
+            issueId: issue.id,
+            source: "issue.status_change",
+            ...(interruptedRunId ? { interruptedRunId } : {}),
+          },
         });
       }
 
@@ -1325,28 +1516,8 @@ export function issueRoutes(db: Db, storage: StorageService) {
         return;
       }
 
-      let runToInterrupt = currentIssue.executionRunId
-        ? await heartbeat.getRun(currentIssue.executionRunId)
-        : null;
-
-      if (
-        (!runToInterrupt || runToInterrupt.status !== "running") &&
-        currentIssue.assigneeAgentId
-      ) {
-        const activeRun = await heartbeat.getActiveRunForAgent(currentIssue.assigneeAgentId);
-        const activeIssueId =
-          activeRun &&
-            activeRun.contextSnapshot &&
-            typeof activeRun.contextSnapshot === "object" &&
-            typeof (activeRun.contextSnapshot as Record<string, unknown>).issueId === "string"
-            ? ((activeRun.contextSnapshot as Record<string, unknown>).issueId as string)
-            : null;
-        if (activeRun && activeRun.status === "running" && activeIssueId === currentIssue.id) {
-          runToInterrupt = activeRun;
-        }
-      }
-
-      if (runToInterrupt && runToInterrupt.status === "running") {
+      const runToInterrupt = await resolveActiveIssueRun(currentIssue);
+      if (runToInterrupt) {
         const cancelled = await heartbeat.cancelRun(runToInterrupt.id);
         if (cancelled) {
           interruptedRunId = cancelled.id;

server/src/routes/projects.ts

@@ -8,13 +8,15 @@ import {
   updateProjectWorkspaceSchema,
 } from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
-import { projectService, logActivity } from "../services/index.js";
+import { projectService, logActivity, workspaceOperationService } from "../services/index.js";
 import { conflict } from "../errors.js";
 import { assertCompanyAccess, getActorInfo } from "./authz.js";
+import { startRuntimeServicesForWorkspaceControl, stopRuntimeServicesForProjectWorkspace } from "../services/workspace-runtime.js";
 
 export function projectRoutes(db: Db) {
   const router = Router();
   const svc = projectService(db);
+  const workspaceOperations = workspaceOperationService(db);
 
   async function resolveCompanyIdForProjectReference(req: Request) {
     const companyIdQuery = req.query.companyId;
@@ -229,6 +231,145 @@ export function projectRoutes(db: Db) {
     },
   );
 
+  router.post("/projects/:id/workspaces/:workspaceId/runtime-services/:action", async (req, res) => {
+    const id = req.params.id as string;
+    const workspaceId = req.params.workspaceId as string;
+    const action = String(req.params.action ?? "").trim().toLowerCase();
+    if (action !== "start" && action !== "stop" && action !== "restart") {
+      res.status(404).json({ error: "Runtime service action not found" });
+      return;
+    }
+
+    const project = await svc.getById(id);
+    if (!project) {
+      res.status(404).json({ error: "Project not found" });
+      return;
+    }
+    assertCompanyAccess(req, project.companyId);
+
+    const workspace = project.workspaces.find((entry) => entry.id === workspaceId) ?? null;
+    if (!workspace) {
+      res.status(404).json({ error: "Project workspace not found" });
+      return;
+    }
+
+    const workspaceCwd = workspace.cwd;
+    if (!workspaceCwd) {
+      res.status(422).json({ error: "Project workspace needs a local path before Paperclip can manage local runtime services" });
+      return;
+    }
+
+    const runtimeConfig = workspace.runtimeConfig?.workspaceRuntime ?? null;
+    if ((action === "start" || action === "restart") && !runtimeConfig) {
+      res.status(422).json({ error: "Project workspace has no runtime service configuration" });
+      return;
+    }
+
+    const actor = getActorInfo(req);
+    const recorder = workspaceOperations.createRecorder({ companyId: project.companyId });
+    let runtimeServiceCount = workspace.runtimeServices?.length ?? 0;
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+
+    const operation = await recorder.recordOperation({
+      phase: action === "stop" ? "workspace_teardown" : "workspace_provision",
+      command: `workspace runtime ${action}`,
+      cwd: workspace.cwd,
+      metadata: {
+        action,
+        projectId: project.id,
+        projectWorkspaceId: workspace.id,
+      },
+      run: async () => {
+        const onLog = async (stream: "stdout" | "stderr", chunk: string) => {
+          if (stream === "stdout") stdout.push(chunk);
+          else stderr.push(chunk);
+        };
+
+        if (action === "stop" || action === "restart") {
+          await stopRuntimeServicesForProjectWorkspace({
+            db,
+            projectWorkspaceId: workspace.id,
+          });
+        }
+
+        if (action === "start" || action === "restart") {
+          const startedServices = await startRuntimeServicesForWorkspaceControl({
+            db,
+            actor: {
+              id: actor.agentId ?? null,
+              name: actor.actorType === "user" ? "Board" : "Agent",
+              companyId: project.companyId,
+            },
+            issue: null,
+            workspace: {
+              baseCwd: workspaceCwd,
+              source: "project_primary",
+              projectId: project.id,
+              workspaceId: workspace.id,
+              repoUrl: workspace.repoUrl,
+              repoRef: workspace.repoRef,
+              strategy: "project_primary",
+              cwd: workspaceCwd,
+              branchName: workspace.defaultRef ?? workspace.repoRef ?? null,
+              worktreePath: null,
+              warnings: [],
+              created: false,
+            },
+            config: { workspaceRuntime: runtimeConfig },
+            adapterEnv: {},
+            onLog,
+          });
+          runtimeServiceCount = startedServices.length;
+        } else {
+          runtimeServiceCount = 0;
+        }
+
+        await svc.updateWorkspace(project.id, workspace.id, {
+          runtimeConfig: {
+            desiredState: action === "stop" ? "stopped" : "running",
+          },
+        });
+
+        return {
+          status: "succeeded",
+          stdout: stdout.join(""),
+          stderr: stderr.join(""),
+          system:
+            action === "stop"
+              ? "Stopped project workspace runtime services.\n"
+              : action === "restart"
+                ? "Restarted project workspace runtime services.\n"
+                : "Started project workspace runtime services.\n",
+          metadata: {
+            runtimeServiceCount,
+          },
+        };
+      },
+    });
+
+    const updatedWorkspace = (await svc.listWorkspaces(project.id)).find((entry) => entry.id === workspace.id) ?? workspace;
+
+    await logActivity(db, {
+      companyId: project.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      action: `project.workspace_runtime_${action}`,
+      entityType: "project",
+      entityId: project.id,
+      details: {
+        projectWorkspaceId: workspace.id,
+        runtimeServiceCount,
+      },
+    });
+
+    res.json({
+      workspace: updatedWorkspace,
+      operation,
+    });
+  });
+
   router.delete("/projects/:id/workspaces/:workspaceId", async (req, res) => {
     const id = req.params.id as string;
     const workspaceId = req.params.workspaceId as string;

server/src/services/agent-instructions.ts

@@ -9,6 +9,7 @@ const ROOT_KEY = "instructionsRootPath";
 const ENTRY_KEY = "instructionsEntryFile";
 const FILE_KEY = "instructionsFilePath";
 const PROMPT_KEY = "promptTemplate";
+/** @deprecated Use the managed instructions bundle system instead. */
 const BOOTSTRAP_PROMPT_KEY = "bootstrapPromptTemplate";
 const LEGACY_PROMPT_TEMPLATE_PATH = "promptTemplate.legacy.md";
 const IGNORED_INSTRUCTIONS_FILE_NAMES = new Set([".DS_Store", "Thumbs.db", "Desktop.ini"]);

server/src/services/company-portability.ts

@@ -1475,7 +1475,7 @@ function normalizePortableConfig(
       key === "instructionsRootPath" ||
       key === "instructionsEntryFile" ||
       key === "promptTemplate" ||
-      key === "bootstrapPromptTemplate" ||
+      key === "bootstrapPromptTemplate" || // deprecated — kept for backward compat
       key === "paperclipSkillSync"
     ) continue;
     if (key === "env") continue;
@@ -3895,7 +3895,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
           desiredSkills,
         );
         delete adapterConfigWithSkills.promptTemplate;
-        delete adapterConfigWithSkills.bootstrapPromptTemplate;
+        delete adapterConfigWithSkills.bootstrapPromptTemplate; // deprecated
         delete adapterConfigWithSkills.instructionsFilePath;
         delete adapterConfigWithSkills.instructionsBundleMode;
         delete adapterConfigWithSkills.instructionsRootPath;

server/src/services/execution-workspaces.ts

@@ -1,11 +1,292 @@
+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 } from "@paperclipai/db";
-import type { ExecutionWorkspace } 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 toExecutionWorkspace(row: ExecutionWorkspaceRow): ExecutionWorkspace {
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readNullableString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function cloneRecord(value: unknown): Record<string, unknown> | null {
+  if (!isRecord(value)) return 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;
+
+  const config: ExecutionWorkspaceConfig = {
+    provisionCommand: readNullableString(raw.provisionCommand),
+    teardownCommand: readNullableString(raw.teardownCommand),
+    cleanupCommand: readNullableString(raw.cleanupCommand),
+    workspaceRuntime: cloneRecord(raw.workspaceRuntime),
+    desiredState: raw.desiredState === "running" || raw.desiredState === "stopped" ? raw.desiredState : null,
+  };
+
+  const hasConfig = Object.values(config).some((value) => {
+    if (value === null) return false;
+    if (typeof value === "object") return Object.keys(value).length > 0;
+    return true;
+  });
+
+  return hasConfig ? config : null;
+}
+
+export function mergeExecutionWorkspaceConfig(
+  metadata: Record<string, unknown> | null | undefined,
+  patch: Partial<ExecutionWorkspaceConfig> | null,
+): Record<string, unknown> | null {
+  const nextMetadata = isRecord(metadata) ? { ...metadata } : {};
+  const current = readExecutionWorkspaceConfig(metadata) ?? {
+    provisionCommand: null,
+    teardownCommand: null,
+    cleanupCommand: null,
+    workspaceRuntime: null,
+    desiredState: null,
+  };
+
+  if (patch === null) {
+    delete nextMetadata.config;
+    return Object.keys(nextMetadata).length > 0 ? nextMetadata : null;
+  }
+
+  const nextConfig: ExecutionWorkspaceConfig = {
+    provisionCommand: patch.provisionCommand !== undefined ? readNullableString(patch.provisionCommand) : current.provisionCommand,
+    teardownCommand: patch.teardownCommand !== undefined ? readNullableString(patch.teardownCommand) : current.teardownCommand,
+    cleanupCommand: patch.cleanupCommand !== undefined ? readNullableString(patch.cleanupCommand) : current.cleanupCommand,
+    workspaceRuntime: patch.workspaceRuntime !== undefined ? cloneRecord(patch.workspaceRuntime) : current.workspaceRuntime,
+    desiredState:
+      patch.desiredState !== undefined
+        ? patch.desiredState === "running" || patch.desiredState === "stopped"
+          ? patch.desiredState
+          : null
+        : current.desiredState,
+  };
+
+  const hasConfig = Object.values(nextConfig).some((value) => {
+    if (value === null) return false;
+    if (typeof value === "object") return Object.keys(value).length > 0;
+    return true;
+  });
+
+  if (hasConfig) {
+    nextMetadata.config = {
+      provisionCommand: nextConfig.provisionCommand,
+      teardownCommand: nextConfig.teardownCommand,
+      cleanupCommand: nextConfig.cleanupCommand,
+      workspaceRuntime: nextConfig.workspaceRuntime,
+      desiredState: nextConfig.desiredState,
+    };
+  } else {
+    delete nextMetadata.config;
+  }
+
+  return Object.keys(nextMetadata).length > 0 ? nextMetadata : null;
+}
+
+function toRuntimeService(row: WorkspaceRuntimeServiceRow): WorkspaceRuntimeService {
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    projectId: row.projectId ?? null,
+    projectWorkspaceId: row.projectWorkspaceId ?? null,
+    executionWorkspaceId: row.executionWorkspaceId ?? null,
+    issueId: row.issueId ?? null,
+    scopeType: row.scopeType as WorkspaceRuntimeService["scopeType"],
+    scopeId: row.scopeId ?? null,
+    serviceName: row.serviceName,
+    status: row.status as WorkspaceRuntimeService["status"],
+    lifecycle: row.lifecycle as WorkspaceRuntimeService["lifecycle"],
+    reuseKey: row.reuseKey ?? null,
+    command: row.command ?? null,
+    cwd: row.cwd ?? null,
+    port: row.port ?? null,
+    url: row.url ?? null,
+    provider: row.provider as WorkspaceRuntimeService["provider"],
+    providerRef: row.providerRef ?? null,
+    ownerAgentId: row.ownerAgentId ?? null,
+    startedByRunId: row.startedByRunId ?? null,
+    lastUsedAt: row.lastUsedAt,
+    startedAt: row.startedAt,
+    stoppedAt: row.stoppedAt ?? null,
+    stopPolicy: (row.stopPolicy as Record<string, unknown> | null) ?? null,
+    healthStatus: row.healthStatus as WorkspaceRuntimeService["healthStatus"],
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function toExecutionWorkspace(
+  row: ExecutionWorkspaceRow,
+  runtimeServices: WorkspaceRuntimeService[] = [],
+): ExecutionWorkspace {
   return {
     id: row.id,
     companyId: row.companyId,
@@ -28,7 +309,9 @@ function toExecutionWorkspace(row: ExecutionWorkspaceRow): ExecutionWorkspace {
     closedAt: row.closedAt ?? null,
     cleanupEligibleAt: row.cleanupEligibleAt ?? null,
     cleanupReason: row.cleanupReason ?? null,
+    config: readExecutionWorkspaceConfig((row.metadata as Record<string, unknown> | null) ?? null),
     metadata: (row.metadata as Record<string, unknown> | null) ?? null,
+    runtimeServices,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -63,7 +346,7 @@ export function executionWorkspaceService(db: Db) {
         .from(executionWorkspaces)
         .where(and(...conditions))
         .orderBy(desc(executionWorkspaces.lastUsedAt), desc(executionWorkspaces.createdAt));
-      return rows.map(toExecutionWorkspace);
+      return rows.map((row) => toExecutionWorkspace(row));
     },
 
     getById: async (id: string) => {
@@ -72,7 +355,268 @@ export function executionWorkspaceService(db: Db) {
         .from(executionWorkspaces)
         .where(eq(executionWorkspaces.id, id))
         .then((rows) => rows[0] ?? null);
-      return row ? toExecutionWorkspace(row) : null;
+      if (!row) return null;
+      const runtimeServiceRows = await db
+        .select()
+        .from(workspaceRuntimeServices)
+        .where(eq(workspaceRuntimeServices.executionWorkspaceId, row.id))
+        .orderBy(desc(workspaceRuntimeServices.updatedAt), desc(workspaceRuntimeServices.createdAt));
+      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 workspacePath = readNullableString(executionWorkspace.providerRef) ?? readNullableString(executionWorkspace.cwd);
+      const resolvedWorkspacePath = workspacePath ? path.resolve(workspacePath) : null;
+      const resolvedPrimaryWorkspacePath = projectWorkspace?.cwd ? path.resolve(projectWorkspace.cwd) : null;
+      const isProjectPrimaryWorkspace =
+        workspace.projectWorkspaceId != null
+        && workspace.projectWorkspaceId === primaryProjectWorkspace?.id
+        && resolvedWorkspacePath != null
+        && resolvedPrimaryWorkspacePath != null
+        && resolvedWorkspacePath === resolvedPrimaryWorkspacePath;
+
+      const linkedIssueSummaries = linkedIssues.map((issue) => ({
+        ...issue,
+        isTerminal: TERMINAL_ISSUE_STATUSES.has(issue.status),
+      }));
+
+      const blockingIssues = linkedIssueSummaries.filter((issue) => !issue.isTerminal);
+      if (blockingIssues.length > 0) {
+        const linkedIssueMessage =
+          blockingIssues.length === 1
+            ? "This workspace is still linked to an open issue."
+            : `This workspace is still linked to ${blockingIssues.length} open issues.`;
+        if (isSharedWorkspace) {
+          warnings.push(`${linkedIssueMessage} Archiving it will detach this shared workspace session from those issues, but keep the underlying project workspace available.`);
+        } else {
+          blockingReasons.push(linkedIssueMessage);
+        }
+      }
+
+      if (isSharedWorkspace) {
+        warnings.push("This shared workspace session points at project workspace infrastructure. Archiving it only removes the session record.");
+      }
+
+      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,
+        });
+      }
+
+      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) => {

server/src/services/heartbeat.ts

@@ -4,7 +4,7 @@ import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
 import { and, asc, desc, eq, gt, inArray, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import type { BillingType } from "@paperclipai/shared";
+import type { BillingType, ExecutionWorkspace, ExecutionWorkspaceConfig } from "@paperclipai/shared";
 import {
   agents,
   agentRuntimeState,
@@ -37,10 +37,12 @@ import {
   persistAdapterManagedRuntimeServices,
   realizeExecutionWorkspace,
   releaseRuntimeServicesForRun,
+  type ExecutionWorkspaceInput,
+  type RealizedExecutionWorkspace,
   sanitizeRuntimeServiceBaseEnv,
 } from "./workspace-runtime.js";
 import { issueService } from "./issues.js";
-import { executionWorkspaceService } from "./execution-workspaces.js";
+import { executionWorkspaceService, mergeExecutionWorkspaceConfig } from "./execution-workspaces.js";
 import { workspaceOperationService } from "./workspace-operations.js";
 import {
   buildExecutionWorkspaceAdapterConfig,
@@ -76,6 +78,87 @@ const SESSIONED_LOCAL_ADAPTERS = new Set([
   "pi_local",
 ]);
 
+export function applyPersistedExecutionWorkspaceConfig(input: {
+  config: Record<string, unknown>;
+  workspaceConfig: ExecutionWorkspaceConfig | null;
+  mode: ReturnType<typeof resolveExecutionWorkspaceMode>;
+}) {
+  const nextConfig = { ...input.config };
+
+  if (input.mode !== "agent_default") {
+    if (input.workspaceConfig?.workspaceRuntime === null) {
+      delete nextConfig.workspaceRuntime;
+    } else if (input.workspaceConfig?.workspaceRuntime) {
+      nextConfig.workspaceRuntime = { ...input.workspaceConfig.workspaceRuntime };
+    }
+  }
+
+  if (input.workspaceConfig && input.mode === "isolated_workspace") {
+    const nextStrategy = parseObject(nextConfig.workspaceStrategy);
+    if (input.workspaceConfig.provisionCommand === null) delete nextStrategy.provisionCommand;
+    else nextStrategy.provisionCommand = input.workspaceConfig.provisionCommand;
+    if (input.workspaceConfig.teardownCommand === null) delete nextStrategy.teardownCommand;
+    else nextStrategy.teardownCommand = input.workspaceConfig.teardownCommand;
+    nextConfig.workspaceStrategy = nextStrategy;
+  }
+
+  return nextConfig;
+}
+
+export function stripWorkspaceRuntimeFromExecutionRunConfig(config: Record<string, unknown>) {
+  const nextConfig = { ...config };
+  delete nextConfig.workspaceRuntime;
+  return nextConfig;
+}
+
+export function buildRealizedExecutionWorkspaceFromPersisted(input: {
+  base: ExecutionWorkspaceInput;
+  workspace: ExecutionWorkspace;
+}): RealizedExecutionWorkspace | null {
+  const cwd = readNonEmptyString(input.workspace.cwd) ?? readNonEmptyString(input.workspace.providerRef);
+  if (!cwd) {
+    return null;
+  }
+
+  const strategy = input.workspace.strategyType === "git_worktree" ? "git_worktree" : "project_primary";
+  return {
+    baseCwd: input.base.baseCwd,
+    source: input.workspace.mode === "shared_workspace" ? "project_primary" : "task_session",
+    projectId: input.workspace.projectId ?? input.base.projectId,
+    workspaceId: input.workspace.projectWorkspaceId ?? input.base.workspaceId,
+    repoUrl: input.workspace.repoUrl ?? input.base.repoUrl,
+    repoRef: input.workspace.baseRef ?? input.base.repoRef,
+    strategy,
+    cwd,
+    branchName: input.workspace.branchName ?? null,
+    worktreePath: strategy === "git_worktree" ? (readNonEmptyString(input.workspace.providerRef) ?? cwd) : null,
+    warnings: [],
+    created: false,
+  };
+}
+
+function buildExecutionWorkspaceConfigSnapshot(config: Record<string, unknown>): Partial<ExecutionWorkspaceConfig> | null {
+  const strategy = parseObject(config.workspaceStrategy);
+  const snapshot: Partial<ExecutionWorkspaceConfig> = {};
+
+  if ("workspaceStrategy" in config) {
+    snapshot.provisionCommand = typeof strategy.provisionCommand === "string" ? strategy.provisionCommand : null;
+    snapshot.teardownCommand = typeof strategy.teardownCommand === "string" ? strategy.teardownCommand : null;
+  }
+
+  if ("workspaceRuntime" in config) {
+    const workspaceRuntime = parseObject(config.workspaceRuntime);
+    snapshot.workspaceRuntime = Object.keys(workspaceRuntime).length > 0 ? workspaceRuntime : null;
+  }
+
+  const hasSnapshot = Object.values(snapshot).some((value) => {
+    if (value === null) return false;
+    if (typeof value === "object") return Object.keys(value).length > 0;
+    return true;
+  });
+  return hasSnapshot ? snapshot : null;
+}
+
 function deriveRepoNameFromRepoUrl(repoUrl: string | null): string | null {
   const trimmed = repoUrl?.trim() ?? "";
   if (!trimmed) return null;
@@ -2030,7 +2113,7 @@ export function heartbeatService(db: Db) {
       (explicitResumeSessionDisplayId ? { sessionId: explicitResumeSessionDisplayId } : null) ??
       normalizeSessionParams(sessionCodec.deserialize(taskSessionForRun?.sessionParamsJson ?? null));
     const config = parseObject(agent.adapterConfig);
-    const executionWorkspaceMode = resolveExecutionWorkspaceMode({
+    const requestedExecutionWorkspaceMode = resolveExecutionWorkspaceMode({
       projectPolicy: projectExecutionWorkspacePolicy,
       issueSettings: issueExecutionWorkspaceSettings,
       legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
@@ -2039,27 +2122,8 @@ export function heartbeatService(db: Db) {
       agent,
       context,
       previousSessionParams,
-      { useProjectWorkspace: executionWorkspaceMode !== "agent_default" },
+      { useProjectWorkspace: requestedExecutionWorkspaceMode !== "agent_default" },
     );
-    const workspaceManagedConfig = buildExecutionWorkspaceAdapterConfig({
-      agentConfig: config,
-      projectPolicy: projectExecutionWorkspacePolicy,
-      issueSettings: issueExecutionWorkspaceSettings,
-      mode: executionWorkspaceMode,
-      legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
-    });
-    const mergedConfig = issueAssigneeOverrides?.adapterConfig
-      ? { ...workspaceManagedConfig, ...issueAssigneeOverrides.adapterConfig }
-      : workspaceManagedConfig;
-    const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(
-      agent.companyId,
-      mergedConfig,
-    );
-    const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
-    const runtimeConfig = {
-      ...resolvedConfig,
-      paperclipRuntimeSkills: runtimeSkillEntries,
-    };
     const issueRef = issueContext
       ? {
           id: issueContext.id,
@@ -2073,36 +2137,90 @@ export function heartbeatService(db: Db) {
       : null;
     const existingExecutionWorkspace =
       issueRef?.executionWorkspaceId ? await executionWorkspacesSvc.getById(issueRef.executionWorkspaceId) : null;
+    const shouldReuseExisting =
+      issueRef?.executionWorkspacePreference === "reuse_existing" &&
+      existingExecutionWorkspace &&
+      existingExecutionWorkspace.status !== "archived";
+    const persistedExecutionWorkspaceMode = shouldReuseExisting && existingExecutionWorkspace
+      ? issueExecutionWorkspaceModeForPersistedWorkspace(existingExecutionWorkspace.mode)
+      : null;
+    const effectiveExecutionWorkspaceMode: ReturnType<typeof resolveExecutionWorkspaceMode> =
+      persistedExecutionWorkspaceMode === "isolated_workspace" ||
+      persistedExecutionWorkspaceMode === "operator_branch" ||
+      persistedExecutionWorkspaceMode === "agent_default"
+        ? persistedExecutionWorkspaceMode
+        : requestedExecutionWorkspaceMode;
+    const workspaceManagedConfig = shouldReuseExisting
+      ? { ...config }
+      : buildExecutionWorkspaceAdapterConfig({
+          agentConfig: config,
+          projectPolicy: projectExecutionWorkspacePolicy,
+          issueSettings: issueExecutionWorkspaceSettings,
+          mode: requestedExecutionWorkspaceMode,
+          legacyUseProjectWorkspace: issueAssigneeOverrides?.useProjectWorkspace ?? null,
+        });
+    const persistedWorkspaceManagedConfig = applyPersistedExecutionWorkspaceConfig({
+      config: workspaceManagedConfig,
+      workspaceConfig: existingExecutionWorkspace?.config ?? null,
+      mode: effectiveExecutionWorkspaceMode,
+    });
+    const mergedConfig = issueAssigneeOverrides?.adapterConfig
+      ? { ...persistedWorkspaceManagedConfig, ...issueAssigneeOverrides.adapterConfig }
+      : persistedWorkspaceManagedConfig;
+    const configSnapshot = buildExecutionWorkspaceConfigSnapshot(mergedConfig);
+    const executionRunConfig = stripWorkspaceRuntimeFromExecutionRunConfig(mergedConfig);
+    const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(
+      agent.companyId,
+      executionRunConfig,
+    );
+    const runtimeSkillEntries = await companySkills.listRuntimeSkillEntries(agent.companyId);
+    const runtimeConfig = {
+      ...resolvedConfig,
+      paperclipRuntimeSkills: runtimeSkillEntries,
+    };
     const workspaceOperationRecorder = workspaceOperationsSvc.createRecorder({
       companyId: agent.companyId,
       heartbeatRunId: run.id,
       executionWorkspaceId: existingExecutionWorkspace?.id ?? null,
     });
-    const executionWorkspace = await realizeExecutionWorkspace({
-      base: {
-        baseCwd: resolvedWorkspace.cwd,
-        source: resolvedWorkspace.source,
-        projectId: resolvedWorkspace.projectId,
-        workspaceId: resolvedWorkspace.workspaceId,
-        repoUrl: resolvedWorkspace.repoUrl,
-        repoRef: resolvedWorkspace.repoRef,
-      },
-      config: runtimeConfig,
-      issue: issueRef,
-      agent: {
-        id: agent.id,
-        name: agent.name,
-        companyId: agent.companyId,
-      },
-      recorder: workspaceOperationRecorder,
-    });
+    const executionWorkspaceBase = {
+      baseCwd: resolvedWorkspace.cwd,
+      source: resolvedWorkspace.source,
+      projectId: resolvedWorkspace.projectId,
+      workspaceId: resolvedWorkspace.workspaceId,
+      repoUrl: resolvedWorkspace.repoUrl,
+      repoRef: resolvedWorkspace.repoRef,
+    } satisfies ExecutionWorkspaceInput;
+    const reusedExecutionWorkspace = shouldReuseExisting && existingExecutionWorkspace
+      ? buildRealizedExecutionWorkspaceFromPersisted({
+          base: executionWorkspaceBase,
+          workspace: existingExecutionWorkspace,
+        })
+      : null;
+    const executionWorkspace = reusedExecutionWorkspace ?? await realizeExecutionWorkspace({
+          base: executionWorkspaceBase,
+          config: runtimeConfig,
+          issue: issueRef,
+          agent: {
+            id: agent.id,
+            name: agent.name,
+            companyId: agent.companyId,
+          },
+          recorder: workspaceOperationRecorder,
+        });
     const resolvedProjectId = executionWorkspace.projectId ?? issueRef?.projectId ?? executionProjectId ?? null;
     const resolvedProjectWorkspaceId = issueRef?.projectWorkspaceId ?? resolvedWorkspace.workspaceId ?? null;
-    const shouldReuseExisting =
-      issueRef?.executionWorkspacePreference === "reuse_existing" &&
-      existingExecutionWorkspace &&
-      existingExecutionWorkspace.status !== "archived";
     let persistedExecutionWorkspace = null;
+    const nextExecutionWorkspaceMetadataBase = {
+      ...(existingExecutionWorkspace?.metadata ?? {}),
+      source: executionWorkspace.source,
+      createdByRuntime: executionWorkspace.created,
+    } as Record<string, unknown>;
+    const nextExecutionWorkspaceMetadata = shouldReuseExisting
+      ? nextExecutionWorkspaceMetadataBase
+      : configSnapshot
+        ? mergeExecutionWorkspaceConfig(nextExecutionWorkspaceMetadataBase, configSnapshot)
+        : nextExecutionWorkspaceMetadataBase;
     try {
       persistedExecutionWorkspace = shouldReuseExisting && existingExecutionWorkspace
         ? await executionWorkspacesSvc.update(existingExecutionWorkspace.id, {
@@ -2114,11 +2232,7 @@ export function heartbeatService(db: Db) {
             providerRef: executionWorkspace.worktreePath,
             status: "active",
             lastUsedAt: new Date(),
-            metadata: {
-              ...(existingExecutionWorkspace.metadata ?? {}),
-              source: executionWorkspace.source,
-              createdByRuntime: executionWorkspace.created,
-            },
+            metadata: nextExecutionWorkspaceMetadata,
           })
         : resolvedProjectId
           ? await executionWorkspacesSvc.create({
@@ -2127,11 +2241,11 @@ export function heartbeatService(db: Db) {
               projectWorkspaceId: resolvedProjectWorkspaceId,
               sourceIssueId: issueRef?.id ?? null,
               mode:
-                executionWorkspaceMode === "isolated_workspace"
+                requestedExecutionWorkspaceMode === "isolated_workspace"
                   ? "isolated_workspace"
-                  : executionWorkspaceMode === "operator_branch"
+                  : requestedExecutionWorkspaceMode === "operator_branch"
                     ? "operator_branch"
-                    : executionWorkspaceMode === "agent_default"
+                    : requestedExecutionWorkspaceMode === "agent_default"
                       ? "adapter_managed"
                       : "shared_workspace",
               strategyType: executionWorkspace.strategy === "git_worktree" ? "git_worktree" : "project_primary",
@@ -2145,10 +2259,7 @@ export function heartbeatService(db: Db) {
               providerRef: executionWorkspace.worktreePath,
               lastUsedAt: new Date(),
               openedAt: new Date(),
-              metadata: {
-                source: executionWorkspace.source,
-                createdByRuntime: executionWorkspace.created,
-              },
+              metadata: nextExecutionWorkspaceMetadata,
             })
           : null;
     } catch (error) {
@@ -2175,7 +2286,8 @@ export function heartbeatService(db: Db) {
               cwd: resolvedWorkspace.cwd,
               cleanupCommand: null,
             },
-            teardownCommand: projectExecutionWorkspacePolicy?.workspaceStrategy?.teardownCommand ?? null,
+            cleanupCommand: configSnapshot?.cleanupCommand ?? null,
+            teardownCommand: configSnapshot?.teardownCommand ?? projectExecutionWorkspacePolicy?.workspaceStrategy?.teardownCommand ?? null,
             recorder: workspaceOperationRecorder,
           });
         } catch (cleanupError) {
@@ -2208,8 +2320,8 @@ export function heartbeatService(db: Db) {
       const nextIssueWorkspaceMode = issueExecutionWorkspaceModeForPersistedWorkspace(persistedExecutionWorkspace.mode);
       const shouldSwitchIssueToExistingWorkspace =
         issueRef?.executionWorkspacePreference === "reuse_existing" ||
-        executionWorkspaceMode === "isolated_workspace" ||
-        executionWorkspaceMode === "operator_branch";
+        requestedExecutionWorkspaceMode === "isolated_workspace" ||
+        requestedExecutionWorkspaceMode === "operator_branch";
       const nextIssuePatch: Record<string, unknown> = {};
       if (issueRef?.executionWorkspaceId !== persistedExecutionWorkspace.id) {
         nextIssuePatch.executionWorkspaceId = persistedExecutionWorkspace.id;
@@ -2262,7 +2374,7 @@ export function heartbeatService(db: Db) {
     context.paperclipWorkspace = {
       cwd: executionWorkspace.cwd,
       source: executionWorkspace.source,
-      mode: executionWorkspaceMode,
+      mode: effectiveExecutionWorkspaceMode,
       strategy: executionWorkspace.strategy,
       projectId: executionWorkspace.projectId,
       workspaceId: executionWorkspace.workspaceId,

server/src/services/index.ts

@@ -28,5 +28,5 @@ export { workProductService } from "./work-products.js";
 export { logActivity, type LogActivityInput } from "./activity-log.js";
 export { notifyHireApproved, type NotifyHireApprovedInput } from "./hire-hook.js";
 export { publishLiveEvent, subscribeCompanyLiveEvents } from "./live-events.js";
-export { reconcilePersistedRuntimeServicesOnStartup } from "./workspace-runtime.js";
+export { reconcilePersistedRuntimeServicesOnStartup, restartDesiredRuntimeServicesOnStartup } from "./workspace-runtime.js";
 export { createStorageServiceFromConfig, getStorageService } from "../storage/index.js";

server/src/services/issues.ts

@@ -11,6 +11,7 @@ import {
   heartbeatRuns,
   executionWorkspaces,
   issueAttachments,
+  issueInboxArchives,
   issueLabels,
   issueComments,
   issueDocuments,
@@ -25,6 +26,7 @@ import { conflict, notFound, unprocessable } from "../errors.js";
 import {
   defaultIssueExecutionWorkspaceSettingsForProject,
   gateProjectExecutionWorkspacePolicy,
+  issueExecutionWorkspaceModeForPersistedWorkspace,
   parseProjectExecutionWorkspacePolicy,
 } from "./execution-workspace-policy.js";
 import { instanceSettingsService } from "./instance-settings.js";
@@ -66,8 +68,10 @@ export interface IssueFilters {
   participantAgentId?: string;
   assigneeUserId?: string;
   touchedByUserId?: string;
+  inboxArchivedByUserId?: string;
   unreadForUserId?: string;
   projectId?: string;
+  executionWorkspaceId?: string;
   parentId?: string;
   labelId?: string;
   originKind?: string;
@@ -102,6 +106,11 @@ type IssueUserContextInput = {
   updatedAt: Date | string;
 };
 type ProjectGoalReader = Pick<Db, "select">;
+type DbReader = Pick<Db, "select">;
+type IssueCreateInput = Omit<typeof issues.$inferInsert, "companyId"> & {
+  labelIds?: string[];
+  inheritExecutionWorkspaceFromIssueId?: string | null;
+};
 
 function sameRunLock(checkoutRunId: string | null, actorRunId: string | null) {
   if (actorRunId) return checkoutRunId === actorRunId;
@@ -128,6 +137,28 @@ async function getProjectDefaultGoalId(
   return row?.goalId ?? null;
 }
 
+async function getWorkspaceInheritanceIssue(
+  db: DbReader,
+  companyId: string,
+  issueId: string,
+) {
+  const issue = await db
+    .select({
+      id: issues.id,
+      projectId: issues.projectId,
+      projectWorkspaceId: issues.projectWorkspaceId,
+      executionWorkspaceId: issues.executionWorkspaceId,
+      executionWorkspaceSettings: issues.executionWorkspaceSettings,
+    })
+    .from(issues)
+    .where(and(eq(issues.id, issueId), eq(issues.companyId, companyId)))
+    .then((rows) => rows[0] ?? null);
+  if (!issue) {
+    throw notFound("Workspace inheritance issue not found");
+  }
+  return issue;
+}
+
 function touchedByUserCondition(companyId: string, userId: string) {
   return sql<boolean>`
     (
@@ -212,6 +243,36 @@ function myLastTouchAtExpr(companyId: string, userId: string) {
   `;
 }
 
+function lastExternalCommentAtExpr(companyId: string, userId: string) {
+  return sql<Date | null>`
+    (
+      SELECT MAX(${issueComments.createdAt})
+      FROM ${issueComments}
+      WHERE ${issueComments.issueId} = ${issues.id}
+        AND ${issueComments.companyId} = ${companyId}
+        AND (
+          ${issueComments.authorUserId} IS NULL
+          OR ${issueComments.authorUserId} <> ${userId}
+        )
+    )
+  `;
+}
+
+function issueLastActivityAtExpr(companyId: string, userId: string) {
+  const lastExternalCommentAt = lastExternalCommentAtExpr(companyId, userId);
+  const myLastTouchAt = myLastTouchAtExpr(companyId, userId);
+  return sql<Date>`
+    COALESCE(
+      ${lastExternalCommentAt},
+      CASE
+        WHEN ${issues.updatedAt} > COALESCE(${myLastTouchAt}, to_timestamp(0))
+        THEN ${issues.updatedAt}
+        ELSE to_timestamp(0)
+      END
+    )
+  `;
+}
+
 function unreadForUserCondition(companyId: string, userId: string) {
   const touchedCondition = touchedByUserCondition(companyId, userId);
   const myLastTouchAt = myLastTouchAtExpr(companyId, userId);
@@ -233,6 +294,20 @@ function unreadForUserCondition(companyId: string, userId: string) {
   `;
 }
 
+function inboxVisibleForUserCondition(companyId: string, userId: string) {
+  const issueLastActivityAt = issueLastActivityAtExpr(companyId, userId);
+  return sql<boolean>`
+    NOT EXISTS (
+      SELECT 1
+      FROM ${issueInboxArchives}
+      WHERE ${issueInboxArchives.issueId} = ${issues.id}
+        AND ${issueInboxArchives.companyId} = ${companyId}
+        AND ${issueInboxArchives.userId} = ${userId}
+        AND ${issueInboxArchives.archivedAt} >= ${issueLastActivityAt}
+    )
+  `;
+}
+
 /** Named entities commonly emitted in saved issue bodies; unknown `&name;` sequences are left unchanged. */
 const WELL_KNOWN_NAMED_HTML_ENTITIES: Readonly<Record<string, string>> = {
   amp: "&",
@@ -440,8 +515,13 @@ export function issueService(db: Db) {
     }
   }
 
-  async function assertValidProjectWorkspace(companyId: string, projectId: string | null | undefined, projectWorkspaceId: string) {
-    const workspace = await db
+  async function assertValidProjectWorkspace(
+    companyId: string,
+    projectId: string | null | undefined,
+    projectWorkspaceId: string,
+    dbOrTx: DbReader = db,
+  ) {
+    const workspace = await dbOrTx
       .select({
         id: projectWorkspaces.id,
         companyId: projectWorkspaces.companyId,
@@ -457,8 +537,13 @@ export function issueService(db: Db) {
     }
   }
 
-  async function assertValidExecutionWorkspace(companyId: string, projectId: string | null | undefined, executionWorkspaceId: string) {
-    const workspace = await db
+  async function assertValidExecutionWorkspace(
+    companyId: string,
+    projectId: string | null | undefined,
+    executionWorkspaceId: string,
+    dbOrTx: DbReader = db,
+  ) {
+    const workspace = await dbOrTx
       .select({
         id: executionWorkspaces.id,
         companyId: executionWorkspaces.companyId,
@@ -556,8 +641,9 @@ export function issueService(db: Db) {
     list: async (companyId: string, filters?: IssueFilters) => {
       const conditions = [eq(issues.companyId, companyId)];
       const touchedByUserId = filters?.touchedByUserId?.trim() || undefined;
+      const inboxArchivedByUserId = filters?.inboxArchivedByUserId?.trim() || undefined;
       const unreadForUserId = filters?.unreadForUserId?.trim() || undefined;
-      const contextUserId = unreadForUserId ?? touchedByUserId;
+      const contextUserId = unreadForUserId ?? touchedByUserId ?? inboxArchivedByUserId;
       const rawSearch = filters?.q?.trim() ?? "";
       const hasSearch = rawSearch.length > 0;
       const escapedSearch = hasSearch ? escapeLikePattern(rawSearch) : "";
@@ -593,10 +679,16 @@ export function issueService(db: Db) {
       if (touchedByUserId) {
         conditions.push(touchedByUserCondition(companyId, touchedByUserId));
       }
+      if (inboxArchivedByUserId) {
+        conditions.push(inboxVisibleForUserCondition(companyId, inboxArchivedByUserId));
+      }
       if (unreadForUserId) {
         conditions.push(unreadForUserCondition(companyId, unreadForUserId));
       }
       if (filters?.projectId) conditions.push(eq(issues.projectId, filters.projectId));
+      if (filters?.executionWorkspaceId) {
+        conditions.push(eq(issues.executionWorkspaceId, filters.executionWorkspaceId));
+      }
       if (filters?.parentId) conditions.push(eq(issues.parentId, filters.parentId));
       if (filters?.originKind) conditions.push(eq(issues.originKind, filters.originKind));
       if (filters?.originId) conditions.push(eq(issues.originId, filters.originId));
@@ -741,6 +833,56 @@ export function issueService(db: Db) {
       return row;
     },
 
+    markUnread: async (companyId: string, issueId: string, userId: string) => {
+      const deleted = await db
+        .delete(issueReadStates)
+        .where(
+          and(
+            eq(issueReadStates.companyId, companyId),
+            eq(issueReadStates.issueId, issueId),
+            eq(issueReadStates.userId, userId),
+          ),
+        )
+        .returning();
+      return deleted.length > 0;
+    },
+
+    archiveInbox: async (companyId: string, issueId: string, userId: string, archivedAt: Date = new Date()) => {
+      const now = new Date();
+      const [row] = await db
+        .insert(issueInboxArchives)
+        .values({
+          companyId,
+          issueId,
+          userId,
+          archivedAt,
+          updatedAt: now,
+        })
+        .onConflictDoUpdate({
+          target: [issueInboxArchives.companyId, issueInboxArchives.issueId, issueInboxArchives.userId],
+          set: {
+            archivedAt,
+            updatedAt: now,
+          },
+        })
+        .returning();
+      return row;
+    },
+
+    unarchiveInbox: async (companyId: string, issueId: string, userId: string) => {
+      const [row] = await db
+        .delete(issueInboxArchives)
+        .where(
+          and(
+            eq(issueInboxArchives.companyId, companyId),
+            eq(issueInboxArchives.issueId, issueId),
+            eq(issueInboxArchives.userId, userId),
+          ),
+        )
+        .returning();
+      return row ?? null;
+    },
+
     getById: async (id: string) => {
       const row = await db
         .select()
@@ -765,9 +907,9 @@ export function issueService(db: Db) {
 
     create: async (
       companyId: string,
-      data: Omit<typeof issues.$inferInsert, "companyId"> & { labelIds?: string[] },
+      data: IssueCreateInput,
     ) => {
-      const { labelIds: inputLabelIds, ...issueData } = data;
+      const { labelIds: inputLabelIds, inheritExecutionWorkspaceFromIssueId, ...issueData } = data;
       const isolatedWorkspacesEnabled = (await instanceSettings.getExperimental()).enableIsolatedWorkspaces;
       if (!isolatedWorkspacesEnabled) {
         delete issueData.executionWorkspaceId;
@@ -783,21 +925,55 @@ export function issueService(db: Db) {
       if (data.assigneeUserId) {
         await assertAssignableUser(companyId, data.assigneeUserId);
       }
-      if (data.projectWorkspaceId) {
-        await assertValidProjectWorkspace(companyId, data.projectId, data.projectWorkspaceId);
-      }
-      if (data.executionWorkspaceId) {
-        await assertValidExecutionWorkspace(companyId, data.projectId, data.executionWorkspaceId);
-      }
       if (data.status === "in_progress" && !data.assigneeAgentId && !data.assigneeUserId) {
         throw unprocessable("in_progress issues require an assignee");
       }
       return db.transaction(async (tx) => {
         const defaultCompanyGoal = await getDefaultCompanyGoal(tx, companyId);
         const projectGoalId = await getProjectDefaultGoalId(tx, companyId, issueData.projectId);
+        let projectWorkspaceId = issueData.projectWorkspaceId ?? null;
+        let executionWorkspaceId = issueData.executionWorkspaceId ?? null;
+        let executionWorkspacePreference = issueData.executionWorkspacePreference ?? null;
         let executionWorkspaceSettings =
           (issueData.executionWorkspaceSettings as Record<string, unknown> | null | undefined) ?? null;
-        if (executionWorkspaceSettings == null && issueData.projectId) {
+        const workspaceInheritanceIssueId = inheritExecutionWorkspaceFromIssueId ?? issueData.parentId ?? null;
+        const hasExplicitExecutionWorkspaceOverride =
+          issueData.executionWorkspaceId !== undefined ||
+          issueData.executionWorkspacePreference !== undefined ||
+          issueData.executionWorkspaceSettings !== undefined;
+        if (workspaceInheritanceIssueId) {
+          const workspaceSource = await getWorkspaceInheritanceIssue(tx, companyId, workspaceInheritanceIssueId);
+          if (projectWorkspaceId == null && workspaceSource.projectWorkspaceId) {
+            projectWorkspaceId = workspaceSource.projectWorkspaceId;
+          }
+          if (
+            isolatedWorkspacesEnabled &&
+            !hasExplicitExecutionWorkspaceOverride &&
+            workspaceSource.executionWorkspaceId
+          ) {
+            const sourceWorkspace = await tx
+              .select({
+                id: executionWorkspaces.id,
+                mode: executionWorkspaces.mode,
+              })
+              .from(executionWorkspaces)
+              .where(eq(executionWorkspaces.id, workspaceSource.executionWorkspaceId))
+              .then((rows) => rows[0] ?? null);
+            if (sourceWorkspace) {
+              executionWorkspaceId = sourceWorkspace.id;
+              executionWorkspacePreference = "reuse_existing";
+              executionWorkspaceSettings = {
+                ...((workspaceSource.executionWorkspaceSettings as Record<string, unknown> | null | undefined) ?? {}),
+                mode: issueExecutionWorkspaceModeForPersistedWorkspace(sourceWorkspace.mode),
+              };
+            }
+          }
+        }
+        if (
+          executionWorkspaceSettings == null &&
+          executionWorkspaceId == null &&
+          issueData.projectId
+        ) {
           const project = await tx
             .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
             .from(projects)
@@ -811,7 +987,6 @@ export function issueService(db: Db) {
               ),
             ) as Record<string, unknown> | null;
         }
-        let projectWorkspaceId = issueData.projectWorkspaceId ?? null;
         if (!projectWorkspaceId && issueData.projectId) {
           const project = await tx
             .select({
@@ -831,6 +1006,12 @@ export function issueService(db: Db) {
               .then((rows) => rows[0]?.id ?? null);
           }
         }
+        if (projectWorkspaceId) {
+          await assertValidProjectWorkspace(companyId, issueData.projectId, projectWorkspaceId, tx);
+        }
+        if (executionWorkspaceId) {
+          await assertValidExecutionWorkspace(companyId, issueData.projectId, executionWorkspaceId, tx);
+        }
         const [company] = await tx
           .update(companies)
           .set({ issueCounter: sql`${companies.issueCounter} + 1` })
@@ -850,6 +1031,8 @@ export function issueService(db: Db) {
             defaultGoalId: defaultCompanyGoal?.id ?? null,
           }),
           ...(projectWorkspaceId ? { projectWorkspaceId } : {}),
+          ...(executionWorkspaceId ? { executionWorkspaceId } : {}),
+          ...(executionWorkspacePreference ? { executionWorkspacePreference } : {}),
           ...(executionWorkspaceSettings ? { executionWorkspaceSettings } : {}),
           companyId,
           issueNumber,

server/src/services/local-service-supervisor.ts

@@ -0,0 +1,302 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { resolvePaperclipInstanceRoot } from "../home-paths.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface LocalServiceRegistryRecord {
+  version: 1;
+  serviceKey: string;
+  profileKind: string;
+  serviceName: string;
+  command: string;
+  cwd: string;
+  envFingerprint: string;
+  port: number | null;
+  url: string | null;
+  pid: number;
+  processGroupId: number | null;
+  provider: "local_process";
+  runtimeServiceId: string | null;
+  reuseKey: string | null;
+  startedAt: string;
+  lastSeenAt: string;
+  metadata: Record<string, unknown> | null;
+}
+
+export interface LocalServiceIdentityInput {
+  profileKind: string;
+  serviceName: string;
+  cwd: string;
+  command: string;
+  envFingerprint: string;
+  port: number | null;
+  scope: Record<string, unknown> | null;
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const rec = value as Record<string, unknown>;
+    return `{${Object.keys(rec).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(rec[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sanitizeServiceKeySegment(value: string, fallback: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || fallback;
+}
+
+function getRuntimeServicesDir() {
+  return path.resolve(resolvePaperclipInstanceRoot(), "runtime-services");
+}
+
+function getRuntimeServiceRegistryPath(serviceKey: string) {
+  return path.resolve(getRuntimeServicesDir(), `${serviceKey}.json`);
+}
+
+function normalizeRegistryRecord(raw: unknown): LocalServiceRegistryRecord | null {
+  if (!raw || typeof raw !== "object") return null;
+  const rec = raw as Record<string, unknown>;
+  if (
+    rec.version !== 1 ||
+    typeof rec.serviceKey !== "string" ||
+    typeof rec.profileKind !== "string" ||
+    typeof rec.serviceName !== "string" ||
+    typeof rec.command !== "string" ||
+    typeof rec.cwd !== "string" ||
+    typeof rec.envFingerprint !== "string" ||
+    typeof rec.pid !== "number"
+  ) {
+    return null;
+  }
+
+  return {
+    version: 1,
+    serviceKey: rec.serviceKey,
+    profileKind: rec.profileKind,
+    serviceName: rec.serviceName,
+    command: rec.command,
+    cwd: rec.cwd,
+    envFingerprint: rec.envFingerprint,
+    port: typeof rec.port === "number" ? rec.port : null,
+    url: typeof rec.url === "string" ? rec.url : null,
+    pid: rec.pid,
+    processGroupId: typeof rec.processGroupId === "number" ? rec.processGroupId : null,
+    provider: "local_process",
+    runtimeServiceId: typeof rec.runtimeServiceId === "string" ? rec.runtimeServiceId : null,
+    reuseKey: typeof rec.reuseKey === "string" ? rec.reuseKey : null,
+    startedAt: typeof rec.startedAt === "string" ? rec.startedAt : new Date().toISOString(),
+    lastSeenAt: typeof rec.lastSeenAt === "string" ? rec.lastSeenAt : new Date().toISOString(),
+    metadata:
+      rec.metadata && typeof rec.metadata === "object" && !Array.isArray(rec.metadata)
+        ? (rec.metadata as Record<string, unknown>)
+        : null,
+  };
+}
+
+async function safeReadRegistryRecord(filePath: string) {
+  try {
+    const raw = JSON.parse(await fs.readFile(filePath, "utf8")) as unknown;
+    return normalizeRegistryRecord(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function createLocalServiceKey(input: LocalServiceIdentityInput) {
+  const digest = createHash("sha256")
+    .update(
+      stableStringify({
+        profileKind: input.profileKind,
+        serviceName: input.serviceName,
+        cwd: path.resolve(input.cwd),
+        command: input.command,
+        envFingerprint: input.envFingerprint,
+        port: input.port,
+        scope: input.scope ?? null,
+      }),
+    )
+    .digest("hex")
+    .slice(0, 24);
+
+  return `${sanitizeServiceKeySegment(input.profileKind, "service")}-${sanitizeServiceKeySegment(input.serviceName, "service")}-${digest}`;
+}
+
+export async function writeLocalServiceRegistryRecord(record: LocalServiceRegistryRecord) {
+  await fs.mkdir(getRuntimeServicesDir(), { recursive: true });
+  await fs.writeFile(
+    getRuntimeServiceRegistryPath(record.serviceKey),
+    `${JSON.stringify(record, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+export async function removeLocalServiceRegistryRecord(serviceKey: string) {
+  await fs.rm(getRuntimeServiceRegistryPath(serviceKey), { force: true });
+}
+
+export async function readLocalServiceRegistryRecord(serviceKey: string) {
+  return await safeReadRegistryRecord(getRuntimeServiceRegistryPath(serviceKey));
+}
+
+export async function listLocalServiceRegistryRecords(filter?: {
+  profileKind?: string;
+  metadata?: Record<string, unknown>;
+}) {
+  try {
+    const entries = await fs.readdir(getRuntimeServicesDir(), { withFileTypes: true });
+    const records = await Promise.all(
+      entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => safeReadRegistryRecord(path.resolve(getRuntimeServicesDir(), entry.name))),
+    );
+
+    return records
+      .filter((record): record is LocalServiceRegistryRecord => record !== null)
+      .filter((record) => {
+        if (filter?.profileKind && record.profileKind !== filter.profileKind) return false;
+        if (!filter?.metadata) return true;
+        return Object.entries(filter.metadata).every(([key, value]) => record.metadata?.[key] === value);
+      })
+      .sort((left, right) => left.serviceKey.localeCompare(right.serviceKey));
+  } catch {
+    return [];
+  }
+}
+
+export async function findLocalServiceRegistryRecordByRuntimeServiceId(input: {
+  runtimeServiceId: string;
+  profileKind?: string;
+}) {
+  const records = await listLocalServiceRegistryRecords(
+    input.profileKind ? { profileKind: input.profileKind } : undefined,
+  );
+  return records.find((record) => record.runtimeServiceId === input.runtimeServiceId) ?? null;
+}
+
+export function isPidAlive(pid: number) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isLikelyMatchingCommand(record: LocalServiceRegistryRecord) {
+  if (process.platform === "win32") return true;
+  try {
+    const { stdout } = await execFileAsync("ps", ["-o", "command=", "-p", String(record.pid)]);
+    const commandLine = stdout.trim();
+    if (!commandLine) return false;
+    return commandLine.includes(record.command) || commandLine.includes(record.serviceName);
+  } catch {
+    return true;
+  }
+}
+
+export async function findAdoptableLocalService(input: {
+  serviceKey: string;
+  command?: string | null;
+  cwd?: string | null;
+  envFingerprint?: string | null;
+  port?: number | null;
+}) {
+  const record = await readLocalServiceRegistryRecord(input.serviceKey);
+  if (!record) return null;
+
+  if (!isPidAlive(record.pid)) {
+    await removeLocalServiceRegistryRecord(input.serviceKey);
+    return null;
+  }
+  if (!(await isLikelyMatchingCommand(record))) {
+    await removeLocalServiceRegistryRecord(input.serviceKey);
+    return null;
+  }
+  if (input.command && record.command !== input.command) return null;
+  if (input.cwd && path.resolve(record.cwd) !== path.resolve(input.cwd)) return null;
+  if (input.envFingerprint && record.envFingerprint !== input.envFingerprint) return null;
+  if (input.port !== undefined && input.port !== null && record.port !== input.port) return null;
+  return record;
+}
+
+export async function touchLocalServiceRegistryRecord(
+  serviceKey: string,
+  patch?: Partial<Omit<LocalServiceRegistryRecord, "serviceKey" | "version">>,
+) {
+  const existing = await readLocalServiceRegistryRecord(serviceKey);
+  if (!existing) return null;
+  const next: LocalServiceRegistryRecord = {
+    ...existing,
+    ...patch,
+    version: 1,
+    serviceKey,
+    lastSeenAt: patch?.lastSeenAt ?? new Date().toISOString(),
+  };
+  await writeLocalServiceRegistryRecord(next);
+  return next;
+}
+
+export async function terminateLocalService(
+  record: Pick<LocalServiceRegistryRecord, "pid" | "processGroupId">,
+  opts?: { signal?: NodeJS.Signals; forceAfterMs?: number },
+) {
+  const signal = opts?.signal ?? "SIGTERM";
+  const targetProcessGroup = process.platform !== "win32" && record.processGroupId && record.processGroupId > 0;
+  try {
+    if (targetProcessGroup) {
+      process.kill(-record.processGroupId!, signal);
+    } else {
+      process.kill(record.pid, signal);
+    }
+  } catch {
+    return;
+  }
+
+  const deadline = Date.now() + (opts?.forceAfterMs ?? 2_000);
+  while (Date.now() < deadline) {
+    if (!isPidAlive(record.pid)) {
+      return;
+    }
+    await delay(100);
+  }
+
+  if (!isPidAlive(record.pid)) return;
+  try {
+    if (targetProcessGroup) {
+      process.kill(-record.processGroupId!, "SIGKILL");
+    } else {
+      process.kill(record.pid, "SIGKILL");
+    }
+  } catch {
+    // Ignore cleanup races.
+  }
+}
+
+export async function readLocalServicePortOwner(port: number) {
+  if (!Number.isInteger(port) || port <= 0 || process.platform === "win32") return null;
+  try {
+    const { stdout } = await execFileAsync("lsof", ["-nPiTCP", `:${port}`, "-sTCP:LISTEN", "-t"]);
+    const firstPid = stdout
+      .split("\n")
+      .map((line) => Number.parseInt(line.trim(), 10))
+      .find((value) => Number.isInteger(value) && value > 0);
+    return firstPid ?? null;
+  } catch {
+    return null;
+  }
+}

server/src/services/project-workspace-runtime-config.ts

@@ -0,0 +1,59 @@
+import type { ProjectWorkspaceRuntimeConfig } from "@paperclipai/shared";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneRecord(value: unknown): Record<string, unknown> | null {
+  return isRecord(value) ? { ...value } : null;
+}
+
+function readDesiredState(value: unknown): ProjectWorkspaceRuntimeConfig["desiredState"] {
+  return value === "running" || value === "stopped" ? value : null;
+}
+
+export function readProjectWorkspaceRuntimeConfig(
+  metadata: Record<string, unknown> | null | undefined,
+): ProjectWorkspaceRuntimeConfig | null {
+  const raw = isRecord(metadata?.runtimeConfig) ? metadata.runtimeConfig : null;
+  if (!raw) return null;
+
+  const config: ProjectWorkspaceRuntimeConfig = {
+    workspaceRuntime: cloneRecord(raw.workspaceRuntime),
+    desiredState: readDesiredState(raw.desiredState),
+  };
+
+  const hasConfig = config.workspaceRuntime !== null || config.desiredState !== null;
+  return hasConfig ? config : null;
+}
+
+export function mergeProjectWorkspaceRuntimeConfig(
+  metadata: Record<string, unknown> | null | undefined,
+  patch: Partial<ProjectWorkspaceRuntimeConfig> | null,
+): Record<string, unknown> | null {
+  const nextMetadata = isRecord(metadata) ? { ...metadata } : {};
+  const current = readProjectWorkspaceRuntimeConfig(metadata) ?? {
+    workspaceRuntime: null,
+    desiredState: null,
+  };
+
+  if (patch === null) {
+    delete nextMetadata.runtimeConfig;
+    return Object.keys(nextMetadata).length > 0 ? nextMetadata : null;
+  }
+
+  const nextConfig: ProjectWorkspaceRuntimeConfig = {
+    workspaceRuntime:
+      patch.workspaceRuntime !== undefined ? cloneRecord(patch.workspaceRuntime) : current.workspaceRuntime,
+    desiredState:
+      patch.desiredState !== undefined ? readDesiredState(patch.desiredState) : current.desiredState,
+  };
+
+  if (nextConfig.workspaceRuntime === null && nextConfig.desiredState === null) {
+    delete nextMetadata.runtimeConfig;
+  } else {
+    nextMetadata.runtimeConfig = nextConfig;
+  }
+
+  return Object.keys(nextMetadata).length > 0 ? nextMetadata : null;
+}

server/src/services/projects.ts

@@ -9,11 +9,13 @@ import {
   type ProjectCodebase,
   type ProjectExecutionWorkspacePolicy,
   type ProjectGoalRef,
+  type ProjectWorkspaceRuntimeConfig,
   type ProjectWorkspace,
   type WorkspaceRuntimeService,
 } from "@paperclipai/shared";
 import { listWorkspaceRuntimeServicesForProjectWorkspaces } from "./workspace-runtime.js";
 import { parseProjectExecutionWorkspacePolicy } from "./execution-workspace-policy.js";
+import { mergeProjectWorkspaceRuntimeConfig, readProjectWorkspaceRuntimeConfig } from "./project-workspace-runtime-config.js";
 import { resolveManagedProjectWorkspaceDir } from "../home-paths.js";
 
 type ProjectRow = typeof projects.$inferSelect;
@@ -34,6 +36,7 @@ type CreateWorkspaceInput = {
   remoteWorkspaceRef?: string | null;
   sharedWorkspaceKey?: string | null;
   metadata?: Record<string, unknown> | null;
+  runtimeConfig?: Partial<ProjectWorkspaceRuntimeConfig> | null;
   isPrimary?: boolean;
 };
 type UpdateWorkspaceInput = Partial<CreateWorkspaceInput>;
@@ -149,6 +152,7 @@ function toWorkspace(
     remoteWorkspaceRef: row.remoteWorkspaceRef ?? null,
     sharedWorkspaceKey: row.sharedWorkspaceKey ?? null,
     metadata: (row.metadata as Record<string, unknown> | null) ?? null,
+    runtimeConfig: readProjectWorkspaceRuntimeConfig((row.metadata as Record<string, unknown> | null) ?? null),
     isPrimary: row.isPrimary,
     runtimeServices,
     createdAt: row.createdAt,
@@ -611,7 +615,13 @@ export function projectService(db: Db) {
             remoteProvider: readNonEmptyString(data.remoteProvider),
             remoteWorkspaceRef,
             sharedWorkspaceKey: readNonEmptyString(data.sharedWorkspaceKey),
-            metadata: (data.metadata as Record<string, unknown> | null | undefined) ?? null,
+            metadata:
+              data.runtimeConfig !== undefined
+                ? mergeProjectWorkspaceRuntimeConfig(
+                    (data.metadata as Record<string, unknown> | null | undefined) ?? null,
+                    data.runtimeConfig ?? null,
+                  )
+                : (data.metadata as Record<string, unknown> | null | undefined) ?? null,
             isPrimary: shouldBePrimary,
           })
           .returning()
@@ -681,7 +691,17 @@ export function projectService(db: Db) {
       if (data.remoteProvider !== undefined) patch.remoteProvider = readNonEmptyString(data.remoteProvider);
       if (data.remoteWorkspaceRef !== undefined) patch.remoteWorkspaceRef = nextRemoteWorkspaceRef;
       if (data.sharedWorkspaceKey !== undefined) patch.sharedWorkspaceKey = readNonEmptyString(data.sharedWorkspaceKey);
-      if (data.metadata !== undefined) patch.metadata = data.metadata;
+      if (data.metadata !== undefined || data.runtimeConfig !== undefined) {
+        patch.metadata =
+          data.runtimeConfig !== undefined
+            ? mergeProjectWorkspaceRuntimeConfig(
+                data.metadata !== undefined
+                  ? (data.metadata as Record<string, unknown> | null | undefined)
+                  : ((existing.metadata as Record<string, unknown> | null | undefined) ?? null),
+                data.runtimeConfig ?? null,
+              )
+            : data.metadata;
+      }
 
       const updated = await db.transaction(async (tx) => {
         if (data.isPrimary === true) {

server/src/services/workspace-runtime.ts

@@ -6,11 +6,23 @@ import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import type { AdapterRuntimeServiceReport } from "@paperclipai/adapter-utils";
 import type { Db } from "@paperclipai/db";
-import { workspaceRuntimeServices } from "@paperclipai/db";
+import { executionWorkspaces, projectWorkspaces, workspaceRuntimeServices } from "@paperclipai/db";
 import { and, desc, eq, inArray } from "drizzle-orm";
 import { asNumber, asString, parseObject, renderTemplate } from "../adapters/utils.js";
 import { resolveHomeAwarePath } from "../home-paths.js";
+import {
+  createLocalServiceKey,
+  findLocalServiceRegistryRecordByRuntimeServiceId,
+  findAdoptableLocalService,
+  readLocalServicePortOwner,
+  removeLocalServiceRegistryRecord,
+  terminateLocalService,
+  touchLocalServiceRegistryRecord,
+  writeLocalServiceRegistryRecord,
+} from "./local-service-supervisor.js";
 import type { WorkspaceOperationRecorder } from "./workspace-operations.js";
+import { readExecutionWorkspaceConfig } from "./execution-workspaces.js";
+import { readProjectWorkspaceRuntimeConfig } from "./project-workspace-runtime-config.js";
 
 export interface ExecutionWorkspaceInput {
   baseCwd: string;
@@ -28,7 +40,7 @@ export interface ExecutionWorkspaceIssueRef {
 }
 
 export interface ExecutionWorkspaceAgentRef {
-  id: string;
+  id: string | null;
   name: string;
   companyId: string;
 }
@@ -77,12 +89,24 @@ interface RuntimeServiceRecord extends RuntimeServiceRef {
   leaseRunIds: Set<string>;
   idleTimer: ReturnType<typeof globalThis.setTimeout> | null;
   envFingerprint: string;
+  serviceKey: string;
+  profileKind: string;
+  processGroupId: number | null;
 }
 
 const runtimeServicesById = new Map<string, RuntimeServiceRecord>();
 const runtimeServicesByReuseKey = new Map<string, string>();
 const runtimeServiceLeasesByRun = new Map<string, string[]>();
 
+export async function resetRuntimeServicesForTests() {
+  for (const record of runtimeServicesById.values()) {
+    clearIdleTimer(record);
+  }
+  runtimeServicesById.clear();
+  runtimeServicesByReuseKey.clear();
+  runtimeServiceLeasesByRun.clear();
+}
+
 function stableStringify(value: unknown): string {
   if (Array.isArray(value)) {
     return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
@@ -102,6 +126,8 @@ export function sanitizeRuntimeServiceBaseEnv(baseEnv: NodeJS.ProcessEnv): NodeJ
     }
   }
   delete env.DATABASE_URL;
+  delete env.npm_config_tailscale_auth;
+  delete env.npm_config_authenticated_private;
   return env;
 }
 
@@ -168,9 +194,9 @@ function toRuntimeServiceRef(record: RuntimeServiceRecord, overrides?: Partial<R
 function sanitizeSlugPart(value: string | null | undefined, fallback: string): string {
   const raw = (value ?? "").trim().toLowerCase();
   const normalized = raw
-    .replace(/[^a-z0-9/_-]+/g, "-")
+    .replace(/[^a-z0-9_-]+/g, "-")
     .replace(/-+/g, "-")
-    .replace(/^[-/]+|[-/]+$/g, "");
+    .replace(/^[-_]+|[-_]+$/g, "");
   return normalized.length > 0 ? normalized : fallback;
 }
 
@@ -189,7 +215,7 @@ function renderWorkspaceTemplate(template: string, input: {
       title: input.issue?.title ?? "",
     },
     agent: {
-      id: input.agent.id,
+      id: input.agent.id ?? "",
       name: input.agent.name,
     },
     project: {
@@ -312,7 +338,7 @@ function buildWorkspaceCommandEnv(input: {
   env.PAPERCLIP_WORKSPACE_CREATED = input.created ? "true" : "false";
   env.PAPERCLIP_PROJECT_ID = input.base.projectId ?? "";
   env.PAPERCLIP_PROJECT_WORKSPACE_ID = input.base.workspaceId ?? "";
-  env.PAPERCLIP_AGENT_ID = input.agent.id;
+  env.PAPERCLIP_AGENT_ID = input.agent.id ?? "";
   env.PAPERCLIP_AGENT_NAME = input.agent.name;
   env.PAPERCLIP_COMPANY_ID = input.agent.companyId;
   env.PAPERCLIP_ISSUE_ID = input.issue?.id ?? "";
@@ -702,6 +728,7 @@ export async function cleanupExecutionWorkspaceArtifacts(input: {
     cwd: string | null;
     cleanupCommand: string | null;
   } | null;
+  cleanupCommand?: string | null;
   teardownCommand?: string | null;
   recorder?: WorkspaceOperationRecorder | null;
 }) {
@@ -713,6 +740,7 @@ export async function cleanupExecutionWorkspaceArtifacts(input: {
   });
   const createdByRuntime = input.workspace.metadata?.createdByRuntime === true;
   const cleanupCommands = [
+    input.cleanupCommand ?? null,
     input.projectWorkspace?.cleanupCommand ?? null,
     input.teardownCommand ?? null,
   ]
@@ -879,13 +907,95 @@ function buildTemplateData(input: {
       title: input.issue?.title ?? "",
     },
     agent: {
-      id: input.agent.id,
+      id: input.agent.id ?? "",
       name: input.agent.name,
     },
     port: input.port ?? "",
   };
 }
 
+function renderRuntimeServiceEnv(input: {
+  envConfig: Record<string, unknown>;
+  templateData: ReturnType<typeof buildTemplateData>;
+}) {
+  const rendered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input.envConfig)) {
+    if (typeof value !== "string") continue;
+    rendered[key] = renderTemplate(value, input.templateData);
+  }
+  return rendered;
+}
+
+function resolveRuntimeServiceReuseIdentity(input: {
+  service: Record<string, unknown>;
+  workspace: RealizedExecutionWorkspace;
+  agent: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  adapterEnv: Record<string, string>;
+  scopeType: RuntimeServiceRef["scopeType"];
+  scopeId: string | null;
+}): {
+  serviceName: string;
+  lifecycle: RuntimeServiceRef["lifecycle"];
+  command: string;
+  serviceCwd: string;
+  envConfig: Record<string, unknown>;
+  envFingerprint: string;
+  explicitPort: number;
+  identityPort: number | null;
+  reuseKey: string | null;
+} {
+  const serviceName = asString(input.service.name, "service");
+  const lifecycle = asString(input.service.lifecycle, "shared") === "ephemeral" ? "ephemeral" : "shared";
+  const command = asString(input.service.command, "");
+  const serviceCwdTemplate = asString(input.service.cwd, ".");
+  const portConfig = parseObject(input.service.port);
+  const envConfig = parseObject(input.service.env);
+  const explicitPort = asNumber(portConfig.value, asNumber(input.service.port, 0));
+  const identityPort = explicitPort > 0 ? explicitPort : null;
+  const templateData = buildTemplateData({
+    workspace: input.workspace,
+    agent: input.agent,
+    issue: input.issue,
+    adapterEnv: input.adapterEnv,
+    port: identityPort,
+  });
+  const serviceCwd = resolveConfiguredPath(renderTemplate(serviceCwdTemplate, templateData), input.workspace.cwd);
+  const renderedEnv = renderRuntimeServiceEnv({
+    envConfig,
+    templateData,
+  });
+  const envFingerprint = createHash("sha256").update(stableStringify(renderedEnv)).digest("hex");
+  const reuseKey =
+    lifecycle === "shared"
+      ? createHash("sha256")
+          .update(
+            stableStringify({
+              scopeType: input.scopeType,
+              scopeId: input.scopeId,
+              serviceName,
+              command,
+              cwd: serviceCwd,
+              port: identityPort,
+              env: renderedEnv,
+            }),
+          )
+          .digest("hex")
+      : null;
+
+  return {
+    serviceName,
+    lifecycle,
+    command,
+    serviceCwd,
+    envConfig,
+    envFingerprint,
+    explicitPort,
+    identityPort,
+    reuseKey,
+  };
+}
+
 function resolveServiceScopeId(input: {
   service: Record<string, unknown>;
   workspace: RealizedExecutionWorkspace;
@@ -1067,7 +1177,7 @@ export function normalizeAdapterManagedRuntimeServices(input: {
       url: report.url ?? null,
       provider: "adapter_managed",
       providerRef: report.providerRef ?? null,
-      ownerAgentId: report.ownerAgentId ?? input.agent.id,
+      ownerAgentId: report.ownerAgentId ?? input.agent.id ?? null,
       startedByRunId: input.runId,
       lastUsedAt: nowIso,
       startedAt: nowIso,
@@ -1082,6 +1192,8 @@ export function normalizeAdapterManagedRuntimeServices(input: {
 async function startLocalRuntimeService(input: {
   db?: Db;
   runId: string;
+  leaseRunId?: string | null;
+  startedByRunId?: string | null;
   agent: ExecutionWorkspaceAgentRef;
   issue: ExecutionWorkspaceIssueRef | null;
   workspace: RealizedExecutionWorkspace;
@@ -1093,14 +1205,33 @@ async function startLocalRuntimeService(input: {
   scopeType: "project_workspace" | "execution_workspace" | "run" | "agent";
   scopeId: string | null;
 }): Promise<RuntimeServiceRecord> {
-  const serviceName = asString(input.service.name, "service");
-  const lifecycle = asString(input.service.lifecycle, "shared") === "ephemeral" ? "ephemeral" : "shared";
-  const command = asString(input.service.command, "");
+  const leaseRunId = input.leaseRunId === undefined ? input.runId : input.leaseRunId;
+  const startedByRunId = input.startedByRunId === undefined ? input.runId : input.startedByRunId;
+  const identity = resolveRuntimeServiceReuseIdentity({
+    service: input.service,
+    workspace: input.workspace,
+    agent: input.agent,
+    issue: input.issue,
+    adapterEnv: input.adapterEnv,
+    scopeType: input.scopeType,
+    scopeId: input.scopeId,
+  });
+  const serviceName = identity.serviceName;
+  const lifecycle = identity.lifecycle;
+  const command = identity.command;
   if (!command) throw new Error(`Runtime service "${serviceName}" is missing command`);
-  const serviceCwdTemplate = asString(input.service.cwd, ".");
   const portConfig = parseObject(input.service.port);
-  const port = asString(portConfig.type, "") === "auto" ? await allocatePort() : null;
-  const envConfig = parseObject(input.service.env);
+  const envConfig = identity.envConfig;
+  const envFingerprint = identity.envFingerprint;
+  const serviceIdentityFingerprint = input.reuseKey ?? envFingerprint;
+  const explicitPort = identity.explicitPort;
+  const identityPort = identity.identityPort;
+  const port =
+    asString(portConfig.type, "") === "auto"
+      ? await allocatePort()
+      : explicitPort > 0
+        ? explicitPort
+        : null;
   const templateData = buildTemplateData({
     workspace: input.workspace,
     agent: input.agent,
@@ -1108,20 +1239,95 @@ async function startLocalRuntimeService(input: {
     adapterEnv: input.adapterEnv,
     port,
   });
-  const serviceCwd = resolveConfiguredPath(renderTemplate(serviceCwdTemplate, templateData), input.workspace.cwd);
+  const serviceCwd =
+    port === identityPort
+      ? identity.serviceCwd
+      : resolveConfiguredPath(renderTemplate(asString(input.service.cwd, "."), templateData), input.workspace.cwd);
   const env: Record<string, string> = {
     ...sanitizeRuntimeServiceBaseEnv(process.env),
     ...input.adapterEnv,
   } as Record<string, string>;
-  for (const [key, value] of Object.entries(envConfig)) {
-    if (typeof value === "string") {
-      env[key] = renderTemplate(value, templateData);
-    }
+  for (const [key, value] of Object.entries(renderRuntimeServiceEnv({ envConfig, templateData }))) {
+    env[key] = value;
   }
   if (port) {
     const portEnvKey = asString(portConfig.envKey, "PORT");
     env[portEnvKey] = String(port);
   }
+  const expose = parseObject(input.service.expose);
+  const readiness = parseObject(input.service.readiness);
+  const urlTemplate =
+    asString(expose.urlTemplate, "") ||
+    asString(readiness.urlTemplate, "");
+  const url = urlTemplate ? renderTemplate(urlTemplate, templateData) : null;
+  const stopPolicy = parseObject(input.service.stopPolicy);
+  const serviceKey = createLocalServiceKey({
+    profileKind: "workspace-runtime",
+    serviceName,
+    cwd: serviceCwd,
+    command,
+    envFingerprint: serviceIdentityFingerprint,
+    port: identityPort,
+    scope: {
+      scopeType: input.scopeType,
+      scopeId: input.scopeId,
+      executionWorkspaceId: input.executionWorkspaceId ?? null,
+      reuseKey: input.reuseKey,
+    },
+  });
+  const adoptedRecord = await findAdoptableLocalService({
+    serviceKey,
+    command,
+    cwd: serviceCwd,
+    envFingerprint: serviceIdentityFingerprint,
+    port: identityPort,
+  });
+  if (adoptedRecord) {
+    return {
+      id: adoptedRecord.runtimeServiceId ?? randomUUID(),
+      companyId: input.agent.companyId,
+      projectId: input.workspace.projectId,
+      projectWorkspaceId: input.workspace.workspaceId,
+      executionWorkspaceId: input.executionWorkspaceId ?? null,
+      issueId: input.issue?.id ?? null,
+      serviceName,
+      status: "running",
+      lifecycle,
+      scopeType: input.scopeType,
+      scopeId: input.scopeId,
+      reuseKey: input.reuseKey,
+      command,
+      cwd: serviceCwd,
+      port: adoptedRecord.port ?? port,
+      url: adoptedRecord.url ?? url,
+      provider: "local_process",
+      providerRef: String(adoptedRecord.pid),
+      ownerAgentId: input.agent.id ?? null,
+      startedByRunId,
+      lastUsedAt: new Date().toISOString(),
+      startedAt: adoptedRecord.startedAt,
+      stoppedAt: null,
+      stopPolicy,
+      healthStatus: "healthy",
+      reused: true,
+      db: input.db,
+      child: null,
+      leaseRunIds: leaseRunId ? new Set([leaseRunId]) : new Set(),
+      idleTimer: null,
+      envFingerprint,
+      serviceKey,
+      profileKind: "workspace-runtime",
+      processGroupId: adoptedRecord.processGroupId ?? null,
+    };
+  }
+  if (identityPort) {
+    const ownerPid = await readLocalServicePortOwner(identityPort);
+    if (ownerPid) {
+      throw new Error(
+        `Runtime service "${serviceName}" could not start because port ${identityPort} is already in use by pid ${ownerPid}`,
+      );
+    }
+  }
   const shell = process.env.SHELL?.trim() || "/bin/sh";
   const child = spawn(shell, ["-lc", command], {
     cwd: serviceCwd,
@@ -1142,13 +1348,6 @@ async function startLocalRuntimeService(input: {
     if (input.onLog) await input.onLog("stderr", `[service:${serviceName}] ${text}`);
   });
 
-  const expose = parseObject(input.service.expose);
-  const readiness = parseObject(input.service.readiness);
-  const urlTemplate =
-    asString(expose.urlTemplate, "") ||
-    asString(readiness.urlTemplate, "");
-  const url = urlTemplate ? renderTemplate(urlTemplate, templateData) : null;
-
   try {
     await waitForReadiness({ service: input.service, url });
   } catch (err) {
@@ -1158,8 +1357,7 @@ async function startLocalRuntimeService(input: {
     );
   }
 
-  const envFingerprint = createHash("sha256").update(stableStringify(envConfig)).digest("hex");
-  return {
+  const record: RuntimeServiceRecord = {
     id: randomUUID(),
     companyId: input.agent.companyId,
     projectId: input.workspace.projectId,
@@ -1178,20 +1376,54 @@ async function startLocalRuntimeService(input: {
     url,
     provider: "local_process",
     providerRef: child.pid ? String(child.pid) : null,
-    ownerAgentId: input.agent.id,
-    startedByRunId: input.runId,
+    ownerAgentId: input.agent.id ?? null,
+    startedByRunId,
     lastUsedAt: new Date().toISOString(),
     startedAt: new Date().toISOString(),
     stoppedAt: null,
-    stopPolicy: parseObject(input.service.stopPolicy),
+    stopPolicy,
     healthStatus: "healthy",
     reused: false,
     db: input.db,
     child,
-    leaseRunIds: new Set([input.runId]),
+    leaseRunIds: leaseRunId ? new Set([leaseRunId]) : new Set(),
     idleTimer: null,
     envFingerprint,
+    serviceKey,
+    profileKind: "workspace-runtime",
+    processGroupId: child.pid ?? null,
   };
+
+  if (child.pid) {
+    await writeLocalServiceRegistryRecord({
+      version: 1,
+      serviceKey,
+      profileKind: "workspace-runtime",
+      serviceName,
+      command,
+      cwd: serviceCwd,
+      envFingerprint: serviceIdentityFingerprint,
+      port,
+      url,
+      pid: child.pid,
+      processGroupId: child.pid,
+      provider: "local_process",
+      runtimeServiceId: record.id,
+      reuseKey: input.reuseKey,
+      startedAt: record.startedAt,
+      lastSeenAt: record.lastUsedAt,
+      metadata: {
+        projectId: record.projectId,
+        projectWorkspaceId: record.projectWorkspaceId,
+        executionWorkspaceId: record.executionWorkspaceId,
+        issueId: record.issueId,
+        scopeType: record.scopeType,
+        scopeId: record.scopeId,
+      },
+    });
+  }
+
+  return record;
 }
 
 function scheduleIdleStop(record: RuntimeServiceRecord) {
@@ -1209,15 +1441,28 @@ async function stopRuntimeService(serviceId: string) {
   if (!record) return;
   clearIdleTimer(record);
   record.status = "stopped";
+  record.healthStatus = "unknown";
   record.lastUsedAt = new Date().toISOString();
   record.stoppedAt = new Date().toISOString();
-  if (record.child && record.child.pid) {
-    terminateChildProcess(record.child);
-  }
   runtimeServicesById.delete(serviceId);
-  if (record.reuseKey) {
+  if (record.reuseKey && runtimeServicesByReuseKey.get(record.reuseKey) === record.id) {
     runtimeServicesByReuseKey.delete(record.reuseKey);
   }
+  if (record.child && record.child.pid) {
+    await terminateLocalService({
+      pid: record.child.pid,
+      processGroupId: record.processGroupId ?? record.child.pid,
+    });
+  } else if (record.providerRef) {
+    const pid = Number.parseInt(record.providerRef, 10);
+    if (Number.isInteger(pid) && pid > 0) {
+      await terminateLocalService({
+        pid,
+        processGroupId: record.processGroupId,
+      });
+    }
+  }
+  await removeLocalServiceRegistryRecord(record.serviceKey);
   await persistRuntimeServiceRecord(record.db, record);
 }
 
@@ -1262,10 +1507,18 @@ function registerRuntimeService(db: Db | undefined, record: RuntimeServiceRecord
     if (current.reuseKey && runtimeServicesByReuseKey.get(current.reuseKey) === current.id) {
       runtimeServicesByReuseKey.delete(current.reuseKey);
     }
+    void removeLocalServiceRegistryRecord(current.serviceKey);
     void persistRuntimeServiceRecord(db, current);
   });
 }
 
+function readRuntimeServiceEntries(config: Record<string, unknown>) {
+  const runtime = parseObject(config.workspaceRuntime);
+  return Array.isArray(runtime.services)
+    ? runtime.services.filter((entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null)
+    : [];
+}
+
 export async function ensureRuntimeServicesForRun(input: {
   db?: Db;
   runId: string;
@@ -1277,17 +1530,13 @@ export async function ensureRuntimeServicesForRun(input: {
   adapterEnv: Record<string, string>;
   onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
 }): Promise<RuntimeServiceRef[]> {
-  const runtime = parseObject(input.config.workspaceRuntime);
-  const rawServices = Array.isArray(runtime.services)
-    ? runtime.services.filter((entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null)
-    : [];
+  const rawServices = readRuntimeServiceEntries(input.config);
   const acquiredServiceIds: string[] = [];
   const refs: RuntimeServiceRef[] = [];
   runtimeServiceLeasesByRun.set(input.runId, acquiredServiceIds);
 
   try {
     for (const service of rawServices) {
-      const lifecycle = asString(service.lifecycle, "shared") === "ephemeral" ? "ephemeral" : "shared";
       const { scopeType, scopeId } = resolveServiceScopeId({
         service,
         workspace: input.workspace,
@@ -1296,13 +1545,15 @@ export async function ensureRuntimeServicesForRun(input: {
         runId: input.runId,
         agent: input.agent,
       });
-      const envConfig = parseObject(service.env);
-      const envFingerprint = createHash("sha256").update(stableStringify(envConfig)).digest("hex");
-      const serviceName = asString(service.name, "service");
-      const reuseKey =
-        lifecycle === "shared"
-          ? [scopeType, scopeId ?? "", serviceName, envFingerprint].join(":")
-          : null;
+      const reuseKey = resolveRuntimeServiceReuseIdentity({
+        service,
+        workspace: input.workspace,
+        agent: input.agent,
+        issue: input.issue,
+        adapterEnv: input.adapterEnv,
+        scopeType,
+        scopeId,
+      }).reuseKey;
 
       if (reuseKey) {
         const existingId = runtimeServicesByReuseKey.get(reuseKey);
@@ -1312,6 +1563,10 @@ export async function ensureRuntimeServicesForRun(input: {
           existing.lastUsedAt = new Date().toISOString();
           existing.stoppedAt = null;
           clearIdleTimer(existing);
+          void touchLocalServiceRegistryRecord(existing.serviceKey, {
+            runtimeServiceId: existing.id,
+            lastSeenAt: existing.lastUsedAt,
+          });
           await persistRuntimeServiceRecord(input.db, existing);
           acquiredServiceIds.push(existing.id);
           refs.push(toRuntimeServiceRef(existing, { reused: true }));
@@ -1346,6 +1601,83 @@ export async function ensureRuntimeServicesForRun(input: {
   return refs;
 }
 
+export async function startRuntimeServicesForWorkspaceControl(input: {
+  db?: Db;
+  invocationId?: string;
+  actor: ExecutionWorkspaceAgentRef;
+  issue: ExecutionWorkspaceIssueRef | null;
+  workspace: RealizedExecutionWorkspace;
+  executionWorkspaceId?: string | null;
+  config: Record<string, unknown>;
+  adapterEnv: Record<string, string>;
+  onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+}): Promise<RuntimeServiceRef[]> {
+  const rawServices = readRuntimeServiceEntries(input.config);
+  const refs: RuntimeServiceRef[] = [];
+  const invocationId = input.invocationId ?? randomUUID();
+
+  for (const service of rawServices) {
+    const { scopeType, scopeId } = resolveServiceScopeId({
+      service,
+      workspace: input.workspace,
+      executionWorkspaceId: input.executionWorkspaceId,
+      issue: input.issue,
+      runId: invocationId,
+      agent: input.actor,
+    });
+    const reuseKey = resolveRuntimeServiceReuseIdentity({
+      service,
+      workspace: input.workspace,
+      agent: input.actor,
+      issue: input.issue,
+      adapterEnv: input.adapterEnv,
+      scopeType,
+      scopeId,
+    }).reuseKey;
+
+    if (reuseKey) {
+      const existingId = runtimeServicesByReuseKey.get(reuseKey);
+      const existing = existingId ? runtimeServicesById.get(existingId) : null;
+      if (existing && existing.status === "running") {
+        existing.lastUsedAt = new Date().toISOString();
+        existing.stoppedAt = null;
+        clearIdleTimer(existing);
+        void touchLocalServiceRegistryRecord(existing.serviceKey, {
+          runtimeServiceId: existing.id,
+          lastSeenAt: existing.lastUsedAt,
+        });
+        await persistRuntimeServiceRecord(input.db, existing);
+        refs.push(toRuntimeServiceRef(existing, { reused: true }));
+        continue;
+      }
+    }
+
+    // Manually controlled services are not tied to a heartbeat run lifecycle, so they do not
+    // retain a run lease and never persist a startedByRunId foreign key.
+    const record = await startLocalRuntimeService({
+      db: input.db,
+      runId: invocationId,
+      leaseRunId: null,
+      startedByRunId: null,
+      agent: input.actor,
+      issue: input.issue,
+      workspace: input.workspace,
+      executionWorkspaceId: input.executionWorkspaceId,
+      adapterEnv: input.adapterEnv,
+      service,
+      onLog: input.onLog,
+      reuseKey,
+      scopeType,
+      scopeId,
+    });
+    registerRuntimeService(input.db, record);
+    await persistRuntimeServiceRecord(input.db, record);
+    refs.push(toRuntimeServiceRef(record));
+  }
+
+  return refs;
+}
+
 export async function releaseRuntimeServicesForRun(runId: string) {
   const acquired = runtimeServiceLeasesByRun.get(runId) ?? [];
   runtimeServiceLeasesByRun.delete(runId);
@@ -1396,6 +1728,39 @@ export async function stopRuntimeServicesForExecutionWorkspace(input: {
   }
 }
 
+export async function stopRuntimeServicesForProjectWorkspace(input: {
+  db?: Db;
+  projectWorkspaceId: string;
+}) {
+  const matchingServiceIds = Array.from(runtimeServicesById.values())
+    .filter((record) => record.projectWorkspaceId === input.projectWorkspaceId && record.scopeType === "project_workspace")
+    .map((record) => record.id);
+
+  for (const serviceId of matchingServiceIds) {
+    await stopRuntimeService(serviceId);
+  }
+
+  if (input.db) {
+    const now = new Date();
+    await input.db
+      .update(workspaceRuntimeServices)
+      .set({
+        status: "stopped",
+        healthStatus: "unknown",
+        stoppedAt: now,
+        lastUsedAt: now,
+        updatedAt: now,
+      })
+      .where(
+        and(
+          eq(workspaceRuntimeServices.projectWorkspaceId, input.projectWorkspaceId),
+          eq(workspaceRuntimeServices.scopeType, "project_workspace"),
+          inArray(workspaceRuntimeServices.status, ["starting", "running"]),
+        ),
+      );
+  }
+}
+
 export async function listWorkspaceRuntimeServicesForProjectWorkspaces(
   db: Db,
   companyId: string,
@@ -1409,6 +1774,7 @@ export async function listWorkspaceRuntimeServicesForProjectWorkspaces(
       and(
         eq(workspaceRuntimeServices.companyId, companyId),
         inArray(workspaceRuntimeServices.projectWorkspaceId, projectWorkspaceIds),
+        eq(workspaceRuntimeServices.scopeType, "project_workspace"),
       ),
     )
     .orderBy(desc(workspaceRuntimeServices.updatedAt), desc(workspaceRuntimeServices.createdAt));
@@ -1424,8 +1790,8 @@ export async function listWorkspaceRuntimeServicesForProjectWorkspaces(
 }
 
 export async function reconcilePersistedRuntimeServicesOnStartup(db: Db) {
-  const staleRows = await db
-    .select({ id: workspaceRuntimeServices.id })
+  const rows = await db
+    .select()
     .from(workspaceRuntimeServices)
     .where(
       and(
@@ -1434,26 +1800,171 @@ export async function reconcilePersistedRuntimeServicesOnStartup(db: Db) {
       ),
     );
 
-  if (staleRows.length === 0) return { reconciled: 0 };
+  if (rows.length === 0) return { reconciled: 0, adopted: 0, stopped: 0 };
 
-  const now = new Date();
-  await db
-    .update(workspaceRuntimeServices)
-    .set({
-      status: "stopped",
-      healthStatus: "unknown",
-      stoppedAt: now,
-      lastUsedAt: now,
-      updatedAt: now,
-    })
-    .where(
-      and(
-        eq(workspaceRuntimeServices.provider, "local_process"),
-        inArray(workspaceRuntimeServices.status, ["starting", "running"]),
-      ),
-    );
+  let adopted = 0;
+  let stopped = 0;
+  for (const row of rows) {
+    const adoptedRecord = await findLocalServiceRegistryRecordByRuntimeServiceId({
+      runtimeServiceId: row.id,
+      profileKind: "workspace-runtime",
+    });
+    if (adoptedRecord) {
+      const record: RuntimeServiceRecord = {
+        id: row.id,
+        companyId: row.companyId,
+        projectId: row.projectId ?? null,
+        projectWorkspaceId: row.projectWorkspaceId ?? null,
+        executionWorkspaceId: row.executionWorkspaceId ?? null,
+        issueId: row.issueId ?? null,
+        serviceName: row.serviceName,
+        status: "running",
+        lifecycle: row.lifecycle as RuntimeServiceRecord["lifecycle"],
+        scopeType: row.scopeType as RuntimeServiceRecord["scopeType"],
+        scopeId: row.scopeId ?? null,
+        reuseKey: row.reuseKey ?? null,
+        command: row.command ?? null,
+        cwd: row.cwd ?? null,
+        port: adoptedRecord.port ?? row.port ?? null,
+        url: adoptedRecord.url ?? row.url ?? null,
+        provider: "local_process",
+        providerRef: String(adoptedRecord.pid),
+        ownerAgentId: row.ownerAgentId ?? null,
+        startedByRunId: row.startedByRunId ?? null,
+        lastUsedAt: new Date().toISOString(),
+        startedAt: row.startedAt.toISOString(),
+        stoppedAt: null,
+        stopPolicy: (row.stopPolicy as Record<string, unknown> | null) ?? null,
+        healthStatus: "healthy",
+        reused: true,
+        db,
+        child: null,
+        leaseRunIds: new Set(),
+        idleTimer: null,
+        envFingerprint: row.reuseKey ?? "",
+        serviceKey: adoptedRecord.serviceKey,
+        profileKind: "workspace-runtime",
+        processGroupId: adoptedRecord.processGroupId ?? null,
+      };
+      registerRuntimeService(db, record);
+      await touchLocalServiceRegistryRecord(adoptedRecord.serviceKey, {
+        runtimeServiceId: row.id,
+        lastSeenAt: record.lastUsedAt,
+      });
+      await persistRuntimeServiceRecord(db, record);
+      adopted += 1;
+      continue;
+    }
 
-  return { reconciled: staleRows.length };
+    const now = new Date();
+    await db
+      .update(workspaceRuntimeServices)
+      .set({
+        status: "stopped",
+        healthStatus: "unknown",
+        stoppedAt: now,
+        lastUsedAt: now,
+        updatedAt: now,
+      })
+      .where(eq(workspaceRuntimeServices.id, row.id));
+    const registryRecord = await findLocalServiceRegistryRecordByRuntimeServiceId({
+      runtimeServiceId: row.id,
+      profileKind: "workspace-runtime",
+    });
+    if (registryRecord) {
+      await removeLocalServiceRegistryRecord(registryRecord.serviceKey);
+    }
+    stopped += 1;
+  }
+
+  return { reconciled: rows.length, adopted, stopped };
+}
+
+export async function restartDesiredRuntimeServicesOnStartup(db: Db) {
+  let restarted = 0;
+  let failed = 0;
+
+  const projectWorkspaceRows = await db
+    .select()
+    .from(projectWorkspaces);
+
+  for (const row of projectWorkspaceRows) {
+    const runtimeConfig = readProjectWorkspaceRuntimeConfig((row.metadata as Record<string, unknown> | null) ?? null);
+    if (runtimeConfig?.desiredState !== "running" || !runtimeConfig.workspaceRuntime || !row.cwd) continue;
+
+    try {
+      const refs = await startRuntimeServicesForWorkspaceControl({
+        db,
+        actor: { id: null, name: "Paperclip", companyId: row.companyId },
+        issue: null,
+        workspace: {
+          baseCwd: row.cwd,
+          source: "project_primary",
+          projectId: row.projectId,
+          workspaceId: row.id,
+          repoUrl: row.repoUrl ?? null,
+          repoRef: row.repoRef ?? null,
+          strategy: "project_primary",
+          cwd: row.cwd,
+          branchName: row.defaultRef ?? row.repoRef ?? null,
+          worktreePath: null,
+          warnings: [],
+          created: false,
+        },
+        config: { workspaceRuntime: runtimeConfig.workspaceRuntime },
+        adapterEnv: {},
+      });
+      if (refs.length > 0) restarted += refs.filter((ref) => !ref.reused).length;
+    } catch {
+      failed += 1;
+    }
+  }
+
+  const executionWorkspaceRows = await db
+    .select()
+    .from(executionWorkspaces)
+    .where(inArray(executionWorkspaces.status, ["active", "idle", "in_review", "cleanup_failed"]));
+
+  for (const row of executionWorkspaceRows) {
+    const config = readExecutionWorkspaceConfig((row.metadata as Record<string, unknown> | null) ?? null);
+    if (config?.desiredState !== "running" || !config.workspaceRuntime || !row.cwd) continue;
+
+    try {
+      const refs = await startRuntimeServicesForWorkspaceControl({
+        db,
+        actor: { id: null, name: "Paperclip", companyId: row.companyId },
+        issue: row.sourceIssueId
+          ? {
+              id: row.sourceIssueId,
+              identifier: null,
+              title: row.name,
+            }
+          : null,
+        workspace: {
+          baseCwd: row.cwd,
+          source: row.mode === "shared_workspace" ? "project_primary" : "task_session",
+          projectId: row.projectId,
+          workspaceId: row.projectWorkspaceId ?? null,
+          repoUrl: row.repoUrl ?? null,
+          repoRef: row.baseRef ?? null,
+          strategy: row.strategyType === "git_worktree" ? "git_worktree" : "project_primary",
+          cwd: row.cwd,
+          branchName: row.branchName ?? null,
+          worktreePath: row.strategyType === "git_worktree" ? row.cwd : null,
+          warnings: [],
+          created: false,
+        },
+        executionWorkspaceId: row.id,
+        config: { workspaceRuntime: config.workspaceRuntime },
+        adapterEnv: {},
+      });
+      if (refs.length > 0) restarted += refs.filter((ref) => !ref.reused).length;
+    } catch {
+      failed += 1;
+    }
+  }
+
+  return { restarted, failed };
 }
 
 export async function persistAdapterManagedRuntimeServices(input: {

server/src/worktree-config.ts

@@ -0,0 +1,467 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { PaperclipConfig } from "@paperclipai/shared";
+import { resolvePaperclipConfigPath, resolvePaperclipEnvPath } from "./paths.js";
+
+function nonEmpty(value: string | null | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolveHomeAwarePath(value: string): string {
+  return path.resolve(expandHomePrefix(value));
+}
+
+function sanitizeWorktreeInstanceId(rawValue: string): string {
+  const trimmed = rawValue.trim().toLowerCase();
+  const normalized = trimmed
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  return normalized || "worktree";
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const value = hostname.trim().toLowerCase();
+  return value === "127.0.0.1" || value === "localhost" || value === "::1";
+}
+
+function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+    parsed.port = String(port);
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function parseEnvFile(contents: string): Record<string, string> {
+  const entries: Record<string, string> = {};
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+    if (!value) {
+      entries[key] = "";
+      continue;
+    }
+
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      entries[key] = value.slice(1, -1);
+      continue;
+    }
+
+    entries[key] = value.replace(/\s+#.*$/, "").trim();
+  }
+
+  return entries;
+}
+
+function readEnvEntries(envPath: string): Record<string, string> {
+  if (!fs.existsSync(envPath)) return {};
+  return parseEnvFile(fs.readFileSync(envPath, "utf8"));
+}
+
+function formatEnvEntries(entries: Record<string, string>): string {
+  return [
+    "# Paperclip environment variables",
+    "# Generated by Paperclip worktree repair",
+    ...Object.entries(entries).map(([key, value]) => `${key}=${JSON.stringify(value)}`),
+    "",
+  ].join("\n");
+}
+
+function isPathInside(candidatePath: string, rootPath: string): boolean {
+  const candidate = path.resolve(candidatePath);
+  const root = path.resolve(rootPath);
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+type WorktreeRuntimeContext = {
+  configPath: string;
+  envPath: string;
+  worktreeName: string;
+  instanceId: string;
+  homeDir: string;
+  instanceRoot: string;
+  contextPath: string;
+  embeddedPostgresDataDir: string;
+  backupDir: string;
+  logDir: string;
+  storageDir: string;
+  secretsKeyFilePath: string;
+};
+
+function resolveWorktreeRuntimeContext(
+  env: NodeJS.ProcessEnv,
+  overrideConfigPath?: string,
+): WorktreeRuntimeContext | null {
+  if (env.PAPERCLIP_IN_WORKTREE !== "true") return null;
+
+  const configPath = resolvePaperclipConfigPath(overrideConfigPath);
+  const envPath = resolvePaperclipEnvPath(configPath);
+  const worktreeRoot = path.resolve(path.dirname(configPath), "..");
+  const worktreeName = nonEmpty(env.PAPERCLIP_WORKTREE_NAME) ?? path.basename(worktreeRoot);
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? sanitizeWorktreeInstanceId(worktreeName);
+  const homeDir = resolveHomeAwarePath(
+    nonEmpty(env.PAPERCLIP_HOME) ??
+      nonEmpty(env.PAPERCLIP_WORKTREES_DIR) ??
+      "~/.paperclip-worktrees",
+  );
+  const instanceRoot = path.resolve(homeDir, "instances", instanceId);
+
+  return {
+    configPath,
+    envPath,
+    worktreeName,
+    instanceId,
+    homeDir,
+    instanceRoot,
+    contextPath: path.resolve(homeDir, "context.json"),
+    embeddedPostgresDataDir: path.resolve(instanceRoot, "db"),
+    backupDir: path.resolve(instanceRoot, "data", "backups"),
+    logDir: path.resolve(instanceRoot, "logs"),
+    storageDir: path.resolve(instanceRoot, "data", "storage"),
+    secretsKeyFilePath: path.resolve(instanceRoot, "secrets", "master.key"),
+  };
+}
+
+function writeConfigFile(configPath: string, config: PaperclipConfig): void {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+function resolveRepoManagedWorktreesRoot(worktreeRoot: string): string | null {
+  const normalized = path.resolve(worktreeRoot);
+  const marker = `${path.sep}.paperclip${path.sep}worktrees${path.sep}`;
+  const index = normalized.indexOf(marker);
+  if (index === -1) return null;
+  const repoRoot = normalized.slice(0, index);
+  return path.resolve(repoRoot, ".paperclip", "worktrees");
+}
+
+function collectSiblingWorktreePorts(context: WorktreeRuntimeContext): {
+  serverPorts: Set<number>;
+  databasePorts: Set<number>;
+} {
+  const serverPorts = new Set<number>();
+  const databasePorts = new Set<number>();
+  const siblingConfigPaths = new Set<string>();
+  const instancesDir = path.resolve(context.homeDir, "instances");
+  if (fs.existsSync(instancesDir)) {
+    for (const entry of fs.readdirSync(instancesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === context.instanceId) continue;
+
+      const siblingConfigPath = path.resolve(instancesDir, entry.name, "config.json");
+      if (fs.existsSync(siblingConfigPath)) {
+        siblingConfigPaths.add(siblingConfigPath);
+      }
+    }
+  }
+
+  const repoManagedWorktreesRoot = resolveRepoManagedWorktreesRoot(path.dirname(context.configPath));
+  if (repoManagedWorktreesRoot && fs.existsSync(repoManagedWorktreesRoot)) {
+    for (const entry of fs.readdirSync(repoManagedWorktreesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const siblingConfigPath = path.resolve(repoManagedWorktreesRoot, entry.name, ".paperclip", "config.json");
+      if (path.resolve(siblingConfigPath) === path.resolve(context.configPath)) continue;
+      if (fs.existsSync(siblingConfigPath)) {
+        siblingConfigPaths.add(siblingConfigPath);
+      }
+    }
+  }
+
+  for (const siblingConfigPath of siblingConfigPaths) {
+    try {
+      const siblingConfig = JSON.parse(fs.readFileSync(siblingConfigPath, "utf8")) as PaperclipConfig;
+      if (Number.isInteger(siblingConfig.server.port) && siblingConfig.server.port > 0) {
+        serverPorts.add(siblingConfig.server.port);
+      }
+      if (
+        siblingConfig.database.mode === "embedded-postgres" &&
+        Number.isInteger(siblingConfig.database.embeddedPostgresPort) &&
+        siblingConfig.database.embeddedPostgresPort > 0
+      ) {
+        databasePorts.add(siblingConfig.database.embeddedPostgresPort);
+      }
+    } catch {
+      // Ignore sibling configs that are missing or malformed.
+    }
+  }
+
+  return { serverPorts, databasePorts };
+}
+
+function findNextUnclaimedPort(preferredPort: number, claimedPorts: Set<number>): number {
+  let port = Math.max(1, Math.trunc(preferredPort));
+  while (claimedPorts.has(port)) {
+    port += 1;
+  }
+  return port;
+}
+
+function buildIsolatedWorktreeConfig(
+  config: PaperclipConfig,
+  context: WorktreeRuntimeContext,
+  portOverrides?: {
+    serverPort?: number;
+    databasePort?: number;
+  },
+): PaperclipConfig {
+  const serverPort = portOverrides?.serverPort ?? config.server.port;
+  const databasePort =
+    config.database.mode === "embedded-postgres"
+      ? portOverrides?.databasePort ?? config.database.embeddedPostgresPort
+      : undefined;
+  const nextConfig: PaperclipConfig = {
+    ...config,
+    database: {
+      ...config.database,
+      ...(config.database.mode === "embedded-postgres"
+        ? {
+            embeddedPostgresDataDir: context.embeddedPostgresDataDir,
+            embeddedPostgresPort: databasePort ?? config.database.embeddedPostgresPort,
+            backup: {
+              ...config.database.backup,
+              dir: context.backupDir,
+            },
+          }
+        : {}),
+    },
+    server: {
+      ...config.server,
+      port: serverPort,
+    },
+    logging: {
+      ...config.logging,
+      logDir: context.logDir,
+    },
+    storage: {
+      ...config.storage,
+      localDisk: {
+        ...config.storage.localDisk,
+        baseDir: context.storageDir,
+      },
+    },
+    secrets: {
+      ...config.secrets,
+      localEncrypted: {
+        ...config.secrets.localEncrypted,
+        keyFilePath: context.secretsKeyFilePath,
+      },
+    },
+  };
+
+  if (config.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {
+    nextConfig.auth = {
+      ...config.auth,
+      publicBaseUrl: rewriteLocalUrlPort(config.auth.publicBaseUrl, serverPort),
+    };
+  }
+
+  return nextConfig;
+}
+
+function needsWorktreeConfigRepair(
+  config: PaperclipConfig,
+  context: WorktreeRuntimeContext,
+): boolean {
+  if (config.database.mode === "embedded-postgres") {
+    if (!isPathInside(config.database.embeddedPostgresDataDir, context.instanceRoot)) {
+      return true;
+    }
+    if (!isPathInside(config.database.backup.dir, context.instanceRoot)) {
+      return true;
+    }
+  }
+
+  if (!isPathInside(config.logging.logDir, context.instanceRoot)) {
+    return true;
+  }
+  if (!isPathInside(config.storage.localDisk.baseDir, context.instanceRoot)) {
+    return true;
+  }
+  if (!isPathInside(config.secrets.localEncrypted.keyFilePath, context.instanceRoot)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function applyRuntimePortSelectionToConfig(
+  config: PaperclipConfig,
+  input: {
+    serverPort: number;
+    databasePort?: number | null;
+    allowServerPortWrite?: boolean;
+    allowDatabasePortWrite?: boolean;
+  },
+): { config: PaperclipConfig; changed: boolean } {
+  let changed = false;
+  let nextConfig = config;
+
+  if (input.allowServerPortWrite !== false && config.server.port !== input.serverPort) {
+    nextConfig = {
+      ...nextConfig,
+      server: {
+        ...nextConfig.server,
+        port: input.serverPort,
+      },
+    };
+    changed = true;
+  }
+
+  if (
+    input.allowDatabasePortWrite !== false &&
+    nextConfig.database.mode === "embedded-postgres" &&
+    typeof input.databasePort === "number" &&
+    nextConfig.database.embeddedPostgresPort !== input.databasePort
+  ) {
+    nextConfig = {
+      ...nextConfig,
+      database: {
+        ...nextConfig.database,
+        embeddedPostgresPort: input.databasePort,
+      },
+    };
+    changed = true;
+  }
+
+  if (nextConfig.auth.baseUrlMode === "explicit" && nextConfig.auth.publicBaseUrl) {
+    const rewritten = rewriteLocalUrlPort(nextConfig.auth.publicBaseUrl, input.serverPort);
+    if (rewritten && rewritten !== nextConfig.auth.publicBaseUrl) {
+      nextConfig = {
+        ...nextConfig,
+        auth: {
+          ...nextConfig.auth,
+          publicBaseUrl: rewritten,
+        },
+      };
+      changed = true;
+    }
+  }
+
+  return { config: nextConfig, changed };
+}
+
+export function maybeRepairLegacyWorktreeConfigAndEnvFiles(): {
+  repairedConfig: boolean;
+  repairedEnv: boolean;
+} {
+  const context = resolveWorktreeRuntimeContext(process.env);
+  if (!context) {
+    return { repairedConfig: false, repairedEnv: false };
+  }
+
+  process.env.PAPERCLIP_HOME = context.homeDir;
+  process.env.PAPERCLIP_INSTANCE_ID = context.instanceId;
+  process.env.PAPERCLIP_CONFIG = context.configPath;
+  process.env.PAPERCLIP_CONTEXT = context.contextPath;
+  process.env.PAPERCLIP_WORKTREE_NAME = context.worktreeName;
+
+  let repairedConfig = false;
+  if (fs.existsSync(context.configPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(context.configPath, "utf8")) as PaperclipConfig;
+      const siblingPorts = collectSiblingWorktreePorts(context);
+      const hasSiblingPortCollision =
+        siblingPorts.serverPorts.has(parsed.server.port) ||
+        (parsed.database.mode === "embedded-postgres" &&
+          siblingPorts.databasePorts.has(parsed.database.embeddedPostgresPort));
+
+      if (needsWorktreeConfigRepair(parsed, context) || hasSiblingPortCollision) {
+        const selectedServerPort = findNextUnclaimedPort(
+          parsed.server.port === 3100 ? 3101 : parsed.server.port,
+          siblingPorts.serverPorts,
+        );
+        const selectedDatabasePort =
+          parsed.database.mode === "embedded-postgres"
+            ? findNextUnclaimedPort(
+                parsed.database.embeddedPostgresPort === 54329
+                  ? 54330
+                  : parsed.database.embeddedPostgresPort,
+                new Set([...siblingPorts.databasePorts, selectedServerPort]),
+              )
+            : undefined;
+
+        writeConfigFile(
+          context.configPath,
+          buildIsolatedWorktreeConfig(parsed, context, {
+            serverPort: selectedServerPort,
+            databasePort: selectedDatabasePort,
+          }),
+        );
+        repairedConfig = true;
+      }
+    } catch {
+      // Leave invalid configs to the normal startup validation path.
+    }
+  }
+
+  const existingEnvEntries = readEnvEntries(context.envPath);
+  const desiredEnvEntries: Record<string, string> = {
+    ...existingEnvEntries,
+    PAPERCLIP_HOME: context.homeDir,
+    PAPERCLIP_INSTANCE_ID: context.instanceId,
+    PAPERCLIP_CONFIG: context.configPath,
+    PAPERCLIP_CONTEXT: context.contextPath,
+    PAPERCLIP_IN_WORKTREE: "true",
+    PAPERCLIP_WORKTREE_NAME: context.worktreeName,
+  };
+
+  const repairedEnv = Object.entries(desiredEnvEntries).some(
+    ([key, value]) => existingEnvEntries[key] !== value,
+  );
+
+  if (repairedEnv) {
+    fs.mkdirSync(path.dirname(context.envPath), { recursive: true });
+    fs.writeFileSync(context.envPath, formatEnvEntries(desiredEnvEntries), { mode: 0o600 });
+  }
+
+  return { repairedConfig, repairedEnv };
+}
+
+export function maybePersistWorktreeRuntimePorts(input: {
+  serverPort: number;
+  databasePort?: number | null;
+}): void {
+  const context = resolveWorktreeRuntimeContext(process.env);
+  if (!context || !fs.existsSync(context.configPath)) return;
+
+  let fileConfig: PaperclipConfig;
+  try {
+    fileConfig = JSON.parse(fs.readFileSync(context.configPath, "utf8")) as PaperclipConfig;
+  } catch {
+    return;
+  }
+
+  const { config, changed } = applyRuntimePortSelectionToConfig(fileConfig, {
+    serverPort: input.serverPort,
+    databasePort: input.databasePort,
+    allowServerPortWrite: !nonEmpty(process.env.PORT),
+    allowDatabasePortWrite: !nonEmpty(process.env.DATABASE_URL),
+  });
+
+  if (changed) {
+    writeConfigFile(context.configPath, config);
+  }
+}