Merge branch 'dev' into local

# Conflicts:
#	packages/db/src/migrations/meta/_journal.json

server/src/__tests__/acpx-local-skill-sync.test.ts

@@ -70,6 +70,7 @@ describe("acpx local skill sync", () => {
     expect(snapshot.mode).toBe("unsupported");
     expect(snapshot.desiredSkills).toContain(paperclipKey);
     expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.desired).toBe(true);
+    expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("available");
     expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("stored in Paperclip only");
     expect(snapshot.warnings).toContain(
       "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",

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

@@ -1,4 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { models as claudeFallbackModels } from "@paperclipai/adapter-claude-local";
+import { resetClaudeModelsCacheForTests } from "@paperclipai/adapter-claude-local/server";
 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";
@@ -17,7 +19,12 @@ vi.mock("acpx/runtime", () => ({
 describe("adapter model listing", () => {
   beforeEach(() => {
     delete process.env.OPENAI_API_KEY;
+    delete process.env.ANTHROPIC_API_KEY;
+    delete process.env.ANTHROPIC_BASE_URL;
+    delete process.env.ANTHROPIC_BEDROCK_BASE_URL;
+    delete process.env.CLAUDE_CODE_USE_BEDROCK;
     delete process.env.PAPERCLIP_OPENCODE_COMMAND;
+    resetClaudeModelsCacheForTests();
     resetCodexModelsCacheForTests();
     resetCursorModelsCacheForTests();
     setCursorModelsRunnerForTests(null);
@@ -45,6 +52,72 @@ describe("adapter model listing", () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 
+  it("returns claude fallback models including the latest Opus alias when no Anthropic key is available", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    const models = await listAdapterModels("claude_local");
+
+    expect(models).toEqual(claudeFallbackModels);
+    expect(models.some((model) => model.id === "claude-opus-4-8")).toBe(true);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("loads claude models dynamically and merges fallback options", async () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        data: [
+          { id: "claude-sonnet-4-20250514", display_name: "Claude Sonnet 4" },
+          { id: "claude-opus-4-8-20260529", display_name: "Claude Opus 4.8" },
+        ],
+      }),
+    } as Response);
+
+    const first = await listAdapterModels("claude_local");
+    const second = await listAdapterModels("claude_local");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(first).toEqual(second);
+    expect(first.some((model) => model.id === "claude-opus-4-8-20260529")).toBe(true);
+    expect(first.some((model) => model.id === "claude-opus-4-8")).toBe(true);
+  });
+
+  it("refreshes cached claude models on demand", async () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+    const fetchSpy = vi.spyOn(globalThis, "fetch")
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: [{ id: "claude-sonnet-4-20250514", display_name: "Claude Sonnet 4" }],
+        }),
+      } as Response)
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: [{ id: "claude-opus-4-8-20260529", display_name: "Claude Opus 4.8" }],
+        }),
+      } as Response);
+
+    const initial = await listAdapterModels("claude_local");
+    const refreshed = await refreshAdapterModels("claude_local");
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(initial.some((model) => model.id === "claude-sonnet-4-20250514")).toBe(true);
+    expect(refreshed.some((model) => model.id === "claude-opus-4-8-20260529")).toBe(true);
+  });
+
+  it("falls back to static claude models when Anthropic model discovery fails", async () => {
+    process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: false,
+      status: 401,
+      json: async () => ({}),
+    } as Response);
+
+    const models = await listAdapterModels("claude_local");
+    expect(models).toEqual(claudeFallbackModels);
+  });
+
   it("loads codex models dynamically and merges fallback options", async () => {
     process.env.OPENAI_API_KEY = "sk-test";
     const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValue({

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

@@ -338,6 +338,9 @@ describe.sequential("agent skill routes", () => {
     );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
+      materializeMissing: false,
+    });
     expect(mockAdapter.listSkills).toHaveBeenCalledWith(
       expect.objectContaining({
         adapterType: "claude_local",
@@ -366,6 +369,9 @@ describe.sequential("agent skill routes", () => {
     );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
+      materializeMissing: false,
+    });
   });
 
   it("passes ACPX Claude config through the agent skill listing route", async () => {
@@ -461,7 +467,7 @@ describe.sequential("agent skill routes", () => {
     );
   });
 
-  it("keeps runtime materialization for persistent skill adapters", async () => {
+  it("skips runtime materialization when listing persistent skill adapters", async () => {
     mockAgentService.getById.mockResolvedValue(makeAgent("cursor"));
     mockAdapter.listSkills.mockResolvedValue({
       adapterType: "cursor",
@@ -479,6 +485,9 @@ describe.sequential("agent skill routes", () => {
     );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockCompanySkillService.listRuntimeSkillEntries).toHaveBeenCalledWith("company-1", {
+      materializeMissing: false,
+    });
   });
 
   it("skips runtime materialization when syncing Claude skills", async () => {

server/src/__tests__/bootstrap-claim-routes.test.ts

@@ -0,0 +1,231 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createHash } from "node:crypto";
+import { accessRoutes } from "../routes/access.js";
+import { boardMutationGuard } from "../middleware/board-mutation-guard.js";
+import { errorHandler } from "../middleware/index.js";
+
+const claimFirstInstanceAdminMock = vi.hoisted(() => vi.fn());
+const accessServiceMock = vi.hoisted(() => ({
+  isInstanceAdmin: vi.fn(),
+  canUser: vi.fn(),
+  hasPermission: vi.fn(),
+  ensureMembership: vi.fn(),
+  setPrincipalGrants: vi.fn(),
+}));
+
+vi.mock("../first-admin-claim.js", () => ({
+  claimFirstInstanceAdmin: claimFirstInstanceAdminMock,
+}));
+
+vi.mock("../services/index.js", () => ({
+  accessService: () => accessServiceMock,
+  agentService: () => ({
+    getById: vi.fn(),
+  }),
+  boardAuthService: () => ({
+    createCliAuthChallenge: vi.fn(),
+    resolveBoardAccess: vi.fn(),
+    assertCurrentBoardKey: vi.fn(),
+    revokeBoardApiKey: vi.fn(),
+  }),
+  deduplicateAgentName: vi.fn(),
+  logActivity: vi.fn(),
+  notifyHireApproved: vi.fn(),
+}));
+
+function hashToken(token: string) {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+function createDb(invite?: Record<string, unknown>) {
+  return {
+    select: vi.fn(() => ({
+      from: vi.fn(() => ({
+        where: vi.fn(() => Promise.resolve(invite ? [invite] : [])),
+      })),
+    })),
+  } as any;
+}
+
+function createApp(input: {
+  actor?: Record<string, unknown>;
+  deploymentMode?: "authenticated" | "local_trusted";
+  deploymentExposure?: "private" | "public";
+  guardMutations?: boolean;
+  db?: Record<string, unknown>;
+}) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = input.actor ?? {
+      type: "board",
+      source: "session",
+      userId: "user-1",
+    };
+    next();
+  });
+  if (input.guardMutations) {
+    app.use(boardMutationGuard());
+  }
+  app.use(
+    "/api",
+    accessRoutes(input.db as any ?? createDb(), {
+      deploymentMode: input.deploymentMode ?? "authenticated",
+      deploymentExposure: input.deploymentExposure ?? "private",
+      bindHost: "127.0.0.1",
+      allowedHostnames: [],
+    }),
+  );
+  app.use(errorHandler);
+  return app;
+}
+
+describe("POST /bootstrap/claim", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    claimFirstInstanceAdminMock.mockResolvedValue({
+      status: "claimed",
+      userId: "user-1",
+      value: null,
+    });
+  });
+
+  it("claims first admin for an authenticated private browser session", async () => {
+    const app = createApp({});
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ claimed: true, userId: "user-1" });
+    expect(claimFirstInstanceAdminMock).toHaveBeenCalledWith(expect.anything(), { userId: "user-1" });
+  });
+
+  it("is not exposed in authenticated public mode", async () => {
+    const app = createApp({ deploymentExposure: "public" });
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(404);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+  });
+
+  it("is not exposed in local trusted mode", async () => {
+    const app = createApp({ deploymentMode: "local_trusted" });
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(404);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    [{ type: "none", source: "none" }, "anonymous caller"],
+    [{ type: "agent", source: "agent_key", agentId: "agent-1" }, "agent key"],
+    [{ type: "board", source: "board_key", userId: "user-1" }, "board API key"],
+    [{ type: "board", source: "local_implicit", userId: "local-board" }, "local implicit board"],
+  ])("rejects %s before opening the first-admin transaction", async (actor) => {
+    const app = createApp({ actor });
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(401);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+  });
+
+  it("returns conflict when first admin has already been claimed", async () => {
+    claimFirstInstanceAdminMock.mockResolvedValueOnce({
+      status: "already_claimed",
+      existingUserId: "user-2",
+      value: null,
+    });
+    const app = createApp({});
+
+    const res = await request(app).post("/api/bootstrap/claim").send({});
+
+    expect(res.status).toBe(409);
+    expect(res.body.error).toContain("already claimed");
+  });
+
+  it("stays behind the board mutation origin guard", async () => {
+    const app = createApp({ guardMutations: true });
+
+    const blocked = await request(app).post("/api/bootstrap/claim").send({});
+    expect(blocked.status).toBe(403);
+    expect(claimFirstInstanceAdminMock).not.toHaveBeenCalled();
+
+    const allowed = await request(app)
+      .post("/api/bootstrap/claim")
+      .set("Host", "paperclip.local")
+      .set("Origin", "http://paperclip.local")
+      .send({});
+    expect(allowed.status).toBe(200);
+    expect(claimFirstInstanceAdminMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("bootstrap invite first-admin acceptance", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function createBootstrapInvite() {
+    return {
+      id: "invite-1",
+      companyId: null,
+      inviteType: "bootstrap_ceo",
+      allowedJoinTypes: "human",
+      tokenHash: hashToken("pcp_invite_test"),
+      defaultsPayload: {},
+      expiresAt: new Date("2027-03-10T00:00:00.000Z"),
+      invitedByUserId: null,
+      revokedAt: null,
+      acceptedAt: null,
+      createdAt: new Date("2026-03-07T00:00:00.000Z"),
+      updatedAt: new Date("2026-03-07T00:00:00.000Z"),
+    };
+  }
+
+  it("uses the shared first-admin helper for bootstrap invite acceptance", async () => {
+    const invite = createBootstrapInvite();
+    claimFirstInstanceAdminMock.mockResolvedValueOnce({
+      status: "claimed",
+      userId: "user-1",
+      value: { ...invite, acceptedAt: new Date("2026-03-07T00:01:00.000Z") },
+    });
+    const app = createApp({ db: createDb(invite) });
+
+    const res = await request(app)
+      .post("/api/invites/pcp_invite_test/accept")
+      .send({ requestType: "human" });
+
+    expect(res.status).toBe(202);
+    expect(res.body).toMatchObject({
+      inviteId: "invite-1",
+      inviteType: "bootstrap_ceo",
+      bootstrapAccepted: true,
+      userId: "user-1",
+    });
+    expect(claimFirstInstanceAdminMock).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ userId: "user-1", onClaim: expect.any(Function) }),
+    );
+  });
+
+  it("conflicts cleanly when browser claim already won before invite acceptance", async () => {
+    claimFirstInstanceAdminMock.mockResolvedValueOnce({
+      status: "already_claimed",
+      existingUserId: "user-2",
+      value: null,
+    });
+    const app = createApp({ db: createDb(createBootstrapInvite()) });
+
+    const res = await request(app)
+      .post("/api/invites/pcp_invite_test/accept")
+      .send({ requestType: "human" });
+
+    expect(res.status).toBe(409);
+    expect(res.body.error).toContain("already claimed");
+  });
+});

server/src/__tests__/company-skills-catalog-service.test.ts

@@ -0,0 +1,455 @@
+import { createHash, randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { and, eq } from "drizzle-orm";
+import { companies, companySkills, createDb } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import type { CatalogSkill, CatalogSkillFile } from "@paperclipai/shared";
+
+function sha256(value: string | Buffer) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function contentHash(files: CatalogSkillFile[]) {
+  const sortedFiles = [...files].sort((left, right) => {
+    if (left.path === "SKILL.md") return -1;
+    if (right.path === "SKILL.md") return 1;
+    return left.path.localeCompare(right.path);
+  });
+  return `sha256:${sha256(Buffer.from(JSON.stringify(sortedFiles.map((file) => ({
+    path: file.path,
+    sha256: file.sha256,
+  })))))}`;
+}
+
+const sampleSkillMarkdown = "---\nname: review\n---\n\n# Review\n";
+const sampleReferenceMarkdown = "# Checklist\n";
+const sampleAssetBytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0xff, 0x10]);
+const sampleFiles: CatalogSkillFile[] = [
+  { path: "SKILL.md", kind: "skill", sizeBytes: Buffer.byteLength(sampleSkillMarkdown), sha256: sha256(sampleSkillMarkdown) },
+  { path: "references/checklist.md", kind: "reference", sizeBytes: Buffer.byteLength(sampleReferenceMarkdown), sha256: sha256(sampleReferenceMarkdown) },
+];
+
+const sampleCatalogSkill: CatalogSkill = {
+  id: "paperclipai:bundled:software-development:review",
+  key: "paperclipai/bundled/software-development/review",
+  kind: "bundled",
+  category: "software-development",
+  slug: "review",
+  name: "review",
+  description: "Review code",
+  path: "catalog/bundled/software-development/review",
+  entrypoint: "SKILL.md",
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  defaultInstall: false,
+  recommendedForRoles: ["engineer"],
+  requires: [],
+  tags: ["review"],
+  files: sampleFiles,
+  contentHash: contentHash(sampleFiles),
+};
+
+const mockCatalogService = vi.hoisted(() => ({
+  getCatalogPackageMetadata: vi.fn(() => ({
+    packageName: "@paperclipai/skills-catalog",
+    packageVersion: "0.3.1",
+  })),
+  getCatalogSkillOrThrow: vi.fn(),
+  resolveCatalogSkillReference: vi.fn(),
+  readCatalogSkillFile: vi.fn(),
+  copyCatalogSkillFile: vi.fn(),
+}));
+
+vi.doMock("../services/skills-catalog.js", () => mockCatalogService);
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres company skill catalog service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("companySkillService.installFromCatalog", () => {
+  let db!: ReturnType<typeof createDb>;
+  let svc!: Awaited<ReturnType<typeof createService>>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+  let oldPaperclipHome: string | undefined;
+  const cleanupDirs = new Set<string>();
+
+  async function createService() {
+    const { companySkillService } = await import("../services/company-skills.js");
+    return companySkillService(db);
+  }
+
+  async function createCompany() {
+    const companyId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    return companyId;
+  }
+
+  beforeAll(async () => {
+    oldPaperclipHome = process.env.PAPERCLIP_HOME;
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-skills-catalog-");
+    db = createDb(tempDb.connectionString);
+    svc = await createService();
+  }, 20_000);
+
+  beforeEach(async () => {
+    const home = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-catalog-home-"));
+    cleanupDirs.add(home);
+    process.env.PAPERCLIP_HOME = home;
+    mockCatalogService.getCatalogSkillOrThrow.mockReturnValue(sampleCatalogSkill);
+    mockCatalogService.resolveCatalogSkillReference.mockReturnValue({
+      skill: sampleCatalogSkill,
+      ambiguous: false,
+    });
+    mockCatalogService.readCatalogSkillFile.mockImplementation(async (_ref: string, filePath: string) => ({
+      catalogSkillId: sampleCatalogSkill.id,
+      path: filePath,
+      kind: filePath === "SKILL.md" ? "skill" : "reference",
+      content: filePath === "SKILL.md" ? sampleSkillMarkdown : sampleReferenceMarkdown,
+      language: "markdown",
+      markdown: true,
+    }));
+    mockCatalogService.copyCatalogSkillFile.mockImplementation(async (_ref: string, filePath: string, targetPath: string) => {
+      const content = filePath === "SKILL.md" ? sampleSkillMarkdown : sampleReferenceMarkdown;
+      await fs.writeFile(targetPath, content, "utf8");
+    });
+  });
+
+  afterEach(async () => {
+    await db.delete(companySkills);
+    await db.delete(companies);
+    await Promise.all(Array.from(cleanupDirs, (dir) => fs.rm(dir, { recursive: true, force: true })));
+    cleanupDirs.clear();
+    vi.clearAllMocks();
+  });
+
+  afterAll(async () => {
+    if (oldPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+    else process.env.PAPERCLIP_HOME = oldPaperclipHome;
+    await tempDb?.cleanup();
+  });
+
+  it("creates a company skill with catalog provenance and materialized files", async () => {
+    const companyId = await createCompany();
+
+    const result = await svc.installFromCatalog(companyId, {
+      catalogSkillId: sampleCatalogSkill.id,
+    });
+
+    expect(result.action).toBe("created");
+    expect(result.skill).toMatchObject({
+      companyId,
+      key: sampleCatalogSkill.key,
+      slug: sampleCatalogSkill.slug,
+      sourceType: "catalog",
+      sourceRef: sampleCatalogSkill.contentHash,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      metadata: expect.objectContaining({
+        sourceKind: "catalog",
+        catalogId: sampleCatalogSkill.id,
+        catalogKey: sampleCatalogSkill.key,
+        catalogKind: "bundled",
+        catalogCategory: "software-development",
+        packageName: "@paperclipai/skills-catalog",
+        originHash: sampleCatalogSkill.contentHash,
+        installedHash: sampleCatalogSkill.contentHash,
+        auditVerdict: "pass",
+        auditScanVersion: "skills-audit-v1",
+      }),
+    });
+    await expect(fs.readFile(path.join(result.skill.sourceLocator!, "SKILL.md"), "utf8")).resolves.toBe(sampleSkillMarkdown);
+    await expect(fs.readFile(path.join(result.skill.sourceLocator!, "references/checklist.md"), "utf8")).resolves.toBe(sampleReferenceMarkdown);
+    const listed = await svc.list(companyId);
+    expect(listed.find((skill) => skill.id === result.skill.id)).toMatchObject({
+      catalogKind: "bundled",
+      originHash: sampleCatalogSkill.contentHash,
+      packageName: "@paperclipai/skills-catalog",
+      packageVersion: "0.3.1",
+    });
+  });
+
+  it("materializes catalog asset files without UTF-8 rewriting", async () => {
+    const assetFiles: CatalogSkillFile[] = [
+      ...sampleFiles,
+      { path: "assets/logo.png", kind: "asset", sizeBytes: sampleAssetBytes.length, sha256: sha256(sampleAssetBytes) },
+    ];
+    const assetCatalogSkill: CatalogSkill = {
+      ...sampleCatalogSkill,
+      trustLevel: "assets",
+      files: assetFiles,
+      contentHash: contentHash(assetFiles),
+    };
+    mockCatalogService.getCatalogSkillOrThrow.mockReturnValue(assetCatalogSkill);
+    mockCatalogService.copyCatalogSkillFile.mockImplementation(async (_ref: string, filePath: string, targetPath: string) => {
+      if (filePath === "assets/logo.png") {
+        await fs.writeFile(targetPath, sampleAssetBytes);
+        return;
+      }
+      const content = filePath === "SKILL.md" ? sampleSkillMarkdown : sampleReferenceMarkdown;
+      await fs.writeFile(targetPath, content, "utf8");
+    });
+    const companyId = await createCompany();
+
+    const result = await svc.installFromCatalog(companyId, {
+      catalogSkillId: assetCatalogSkill.id,
+    });
+
+    await expect(fs.readFile(path.join(result.skill.sourceLocator!, "assets/logo.png"))).resolves.toEqual(sampleAssetBytes);
+    await expect(svc.installUpdate(companyId, result.skill.id)).resolves.toMatchObject({
+      metadata: expect.objectContaining({
+        updateHoldReason: null,
+      }),
+    });
+    await expect(svc.resetSkill(companyId, result.skill.id)).resolves.toMatchObject({
+      metadata: expect.objectContaining({
+        updateHoldReason: null,
+      }),
+    });
+  });
+
+  it("restores portable catalog provenance when importing packaged skills", async () => {
+    const companyId = await createCompany();
+    const importedFiles = {
+      "skills/paperclipai/bundled/software-development/review/SKILL.md": [
+        "---",
+        `key: "${sampleCatalogSkill.key}"`,
+        'slug: "review"',
+        'name: "review"',
+        "metadata:",
+        "  paperclip:",
+        `    skillKey: "${sampleCatalogSkill.key}"`,
+        '    slug: "review"',
+        "    catalog:",
+        `      skillKey: "${sampleCatalogSkill.key}"`,
+        `      sourceRef: "${sampleCatalogSkill.contentHash}"`,
+        `      originHash: "${sampleCatalogSkill.contentHash}"`,
+        `      catalogId: "${sampleCatalogSkill.id}"`,
+        `      catalogKey: "${sampleCatalogSkill.key}"`,
+        '      catalogKind: "bundled"',
+        '      catalogPath: "catalog/bundled/software-development/review"',
+        '      packageName: "@paperclipai/skills-catalog"',
+        '      packageVersion: "0.3.1"',
+        `      installedHash: "${sampleCatalogSkill.contentHash}"`,
+        '      userModifiedAt: "2026-05-01T00:00:00.000Z"',
+        '      updateHoldReason: "local_modifications"',
+        '      auditVerdict: "warning"',
+        "      auditCodes:",
+        '        - "local_modifications"',
+        '      auditScannedAt: "2026-05-02T00:00:00.000Z"',
+        '      auditScanVersion: "skills-audit-v1"',
+        "---",
+        "",
+        "# Review",
+        "",
+      ].join("\n"),
+      "skills/paperclipai/bundled/software-development/review/references/checklist.md": sampleReferenceMarkdown,
+    };
+
+    const [result] = await svc.importPackageFiles(companyId, importedFiles, { onConflict: "replace" });
+
+    expect(result?.action).toBe("created");
+    expect(result?.skill).toMatchObject({
+      companyId,
+      key: sampleCatalogSkill.key,
+      slug: "review",
+      sourceType: "catalog",
+      sourceRef: sampleCatalogSkill.contentHash,
+      metadata: expect.objectContaining({
+        sourceKind: "catalog",
+        skillKey: sampleCatalogSkill.key,
+        originHash: sampleCatalogSkill.contentHash,
+        catalogId: sampleCatalogSkill.id,
+        catalogKey: sampleCatalogSkill.key,
+        catalogKind: "bundled",
+        catalogPath: "catalog/bundled/software-development/review",
+        packageName: "@paperclipai/skills-catalog",
+        packageVersion: "0.3.1",
+        installedHash: sampleCatalogSkill.contentHash,
+        userModifiedAt: "2026-05-01T00:00:00.000Z",
+        updateHoldReason: "local_modifications",
+        auditVerdict: "warning",
+        auditCodes: ["local_modifications"],
+        auditScannedAt: "2026-05-02T00:00:00.000Z",
+        auditScanVersion: "skills-audit-v1",
+      }),
+    });
+    expect(result?.skill.sourceLocator).toEqual(expect.any(String));
+    await expect(fs.readFile(path.join(result!.skill.sourceLocator!, "SKILL.md"), "utf8")).resolves.toContain("# Review");
+  });
+
+  it("returns unchanged for an already-current catalog skill", async () => {
+    const companyId = await createCompany();
+    await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+
+    const result = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+
+    expect(result.action).toBe("unchanged");
+    expect(result.skill.metadata).toEqual(expect.objectContaining({
+      installedHash: sampleCatalogSkill.contentHash,
+      auditVerdict: "pass",
+      auditScanVersion: "skills-audit-v1",
+    }));
+    const rows = await db
+      .select()
+      .from(companySkills)
+      .where(and(eq(companySkills.companyId, companyId), eq(companySkills.key, sampleCatalogSkill.key)));
+    expect(rows).toHaveLength(1);
+  });
+
+  it("detects installed catalog drift during update checks", async () => {
+    const companyId = await createCompany();
+    const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+    await fs.writeFile(path.join(installed.skill.sourceLocator!, "SKILL.md"), `${sampleSkillMarkdown}\nTampered\n`, "utf8");
+
+    const status = await svc.updateStatus(companyId, installed.skill.id);
+
+    expect(status).toMatchObject({
+      supported: true,
+      originHash: sampleCatalogSkill.contentHash,
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+    });
+    expect(status?.installedHash).not.toBe(sampleCatalogSkill.contentHash);
+  });
+
+  it("returns unsupported update status when the catalog entry is no longer shipped", async () => {
+    const companyId = await createCompany();
+    const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+    mockCatalogService.resolveCatalogSkillReference.mockReturnValue({
+      skill: null,
+      ambiguous: false,
+    });
+
+    const status = await svc.updateStatus(companyId, installed.skill.id);
+
+    expect(status).toMatchObject({
+      supported: false,
+      reason: "Catalog entry is no longer available in the shipped manifest.",
+      trackingRef: sampleCatalogSkill.id,
+      latestRef: null,
+      hasUpdate: false,
+    });
+  });
+
+  it("clears stale local modification hold status when catalog files are restored", async () => {
+    const companyId = await createCompany();
+    const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+    const skillPath = path.join(installed.skill.sourceLocator!, "SKILL.md");
+    await fs.writeFile(skillPath, `${sampleSkillMarkdown}\nTampered\n`, "utf8");
+    await svc.auditSkill(companyId, installed.skill.id);
+    await fs.writeFile(skillPath, sampleSkillMarkdown, "utf8");
+
+    const status = await svc.updateStatus(companyId, installed.skill.id);
+
+    expect(status).toMatchObject({
+      updateHoldReason: null,
+      userModifiedAt: null,
+      installedHash: sampleCatalogSkill.contentHash,
+    });
+  });
+
+  it("reports hard-stop audit findings for idempotent catalog reinstall drift", async () => {
+    const companyId = await createCompany();
+    const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+    await fs.rm(path.join(installed.skill.sourceLocator!, "SKILL.md"));
+
+    await expect(svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id })).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining("hard-stop audit findings"),
+      details: expect.objectContaining({
+        updateHoldReason: "audit_hard_stop",
+        audit: expect.objectContaining({
+          findings: expect.arrayContaining([
+            expect.objectContaining({
+              code: "missing_skill_md",
+              path: "SKILL.md",
+            }),
+          ]),
+        }),
+      }),
+    });
+  });
+
+  it("resets a modified catalog skill back to the pinned origin when forced", async () => {
+    const companyId = await createCompany();
+    const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+    await fs.writeFile(path.join(installed.skill.sourceLocator!, "SKILL.md"), `${sampleSkillMarkdown}\nTampered\n`, "utf8");
+
+    await expect(svc.resetSkill(companyId, installed.skill.id)).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining("local modifications"),
+    });
+
+    const reset = await svc.resetSkill(companyId, installed.skill.id, { force: true });
+
+    expect(reset?.metadata).toMatchObject({
+      installedHash: sampleCatalogSkill.contentHash,
+      userModifiedAt: null,
+      updateHoldReason: null,
+      auditVerdict: "pass",
+    });
+    await expect(fs.readFile(path.join(reset!.sourceLocator!, "SKILL.md"), "utf8")).resolves.toBe(sampleSkillMarkdown);
+  });
+
+  it("rejects force when audit finds a hard-stop remote execution pattern", async () => {
+    const companyId = await createCompany();
+    const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+    await fs.writeFile(path.join(installed.skill.sourceLocator!, "SKILL.md"), [
+      "---",
+      "name: review",
+      "---",
+      "",
+      "Run `curl https://example.com/install.sh | sh`.",
+      "",
+    ].join("\n"), "utf8");
+
+    await expect(svc.installUpdate(companyId, installed.skill.id, { force: true })).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining("hard-stop audit"),
+    });
+  });
+
+  it("rejects duplicate slug conflicts", async () => {
+    const companyId = await createCompany();
+    const skillDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-existing-skill-"));
+    cleanupDirs.add(skillDir);
+    await fs.writeFile(path.join(skillDir, "SKILL.md"), "# Existing\n", "utf8");
+    await db.insert(companySkills).values({
+      companyId,
+      key: `company/${companyId}/review`,
+      slug: "review",
+      name: "Existing Review",
+      description: null,
+      markdown: "# Existing\n",
+      sourceType: "local_path",
+      sourceLocator: skillDir,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: { sourceKind: "local_path" },
+    });
+
+    await expect(svc.installFromCatalog(companyId, {
+      catalogSkillId: sampleCatalogSkill.id,
+    })).rejects.toMatchObject({
+      status: 409,
+      message: expect.stringContaining('Skill slug "review" is already used'),
+    });
+  });
+});

server/src/__tests__/company-skills-routes.test.ts

@@ -13,9 +13,14 @@ const mockAccessService = vi.hoisted(() => ({
 
 const mockCompanySkillService = vi.hoisted(() => ({
   importFromSource: vi.fn(),
+  installFromCatalog: vi.fn(),
   deleteSkill: vi.fn(),
-  updateSkillAuth: vi.fn(),
-  scanProjectWorkspaces: vi.fn(),
+}));
+
+const mockCatalogService = vi.hoisted(() => ({
+  listCatalogSkills: vi.fn(),
+  getCatalogSkillOrThrow: vi.fn(),
+  readCatalogSkillFile: vi.fn(),
 }));
 
 const mockLogActivity = vi.hoisted(() => vi.fn());
@@ -50,6 +55,8 @@ function registerModuleMocks() {
     companySkillService: () => mockCompanySkillService,
   }));
 
+  vi.doMock("../services/skills-catalog.js", () => mockCatalogService);
+
   vi.doMock("../services/index.js", () => ({
     accessService: () => mockAccessService,
     agentService: () => mockAgentService,
@@ -83,6 +90,7 @@ describe("company skill mutation permissions", () => {
     vi.doUnmock("../services/activity-log.js");
     vi.doUnmock("../services/agents.js");
     vi.doUnmock("../services/company-skills.js");
+    vi.doUnmock("../services/skills-catalog.js");
     vi.doUnmock("../services/index.js");
     vi.doUnmock("../routes/company-skills.js");
     vi.doUnmock("../routes/authz.js");
@@ -94,19 +102,83 @@ describe("company skill mutation permissions", () => {
       imported: [],
       warnings: [],
     });
+    mockCompanySkillService.installFromCatalog.mockResolvedValue({
+      action: "created",
+      skill: {
+        id: "skill-1",
+        companyId: "company-1",
+        key: "paperclipai/bundled/software-development/review",
+        slug: "review",
+        name: "review",
+        description: "Review code",
+        markdown: "# Review",
+        sourceType: "catalog",
+        sourceLocator: "/tmp/review",
+        sourceRef: "sha256:abc",
+        trustLevel: "markdown_only",
+        compatibility: "compatible",
+        fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+        metadata: {
+          sourceKind: "catalog",
+          catalogId: "paperclipai:bundled:software-development:review",
+          originHash: "sha256:abc",
+        },
+        createdAt: new Date("2026-05-26T00:00:00.000Z"),
+        updatedAt: new Date("2026-05-26T00:00:00.000Z"),
+      },
+      catalogSkill: {
+        id: "paperclipai:bundled:software-development:review",
+        key: "paperclipai/bundled/software-development/review",
+        kind: "bundled",
+        category: "software-development",
+        slug: "review",
+        name: "review",
+        description: "Review code",
+        path: "catalog/bundled/software-development/review",
+        entrypoint: "SKILL.md",
+        trustLevel: "markdown_only",
+        compatibility: "compatible",
+        defaultInstall: false,
+        recommendedForRoles: ["engineer"],
+        requires: [],
+        tags: ["review"],
+        files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
+        contentHash: "sha256:abc",
+      },
+      warnings: [],
+    });
     mockCompanySkillService.deleteSkill.mockResolvedValue({
       id: "skill-1",
       slug: "find-skills",
       name: "Find Skills",
     });
-    mockCompanySkillService.scanProjectWorkspaces.mockResolvedValue({
-      scannedProjects: 1,
-      scannedWorkspaces: 2,
-      discovered: [],
-      imported: [],
-      updated: [],
-      conflicts: [],
-      warnings: [],
+    mockCatalogService.listCatalogSkills.mockReturnValue([]);
+    mockCatalogService.getCatalogSkillOrThrow.mockReturnValue({
+      id: "paperclipai:bundled:software-development:review",
+      key: "paperclipai/bundled/software-development/review",
+      kind: "bundled",
+      category: "software-development",
+      slug: "review",
+      name: "review",
+      description: "Review code",
+      path: "catalog/bundled/software-development/review",
+      entrypoint: "SKILL.md",
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      defaultInstall: false,
+      recommendedForRoles: ["engineer"],
+      requires: [],
+      tags: ["review"],
+      files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
+      contentHash: "sha256:abc",
+    });
+    mockCatalogService.readCatalogSkillFile.mockResolvedValue({
+      catalogSkillId: "paperclipai:bundled:software-development:review",
+      path: "SKILL.md",
+      kind: "skill",
+      content: "# Review",
+      language: "markdown",
+      markdown: true,
     });
     mockLogActivity.mockResolvedValue(undefined);
     mockAccessService.canUser.mockResolvedValue(true);
@@ -131,6 +203,113 @@ describe("company skill mutation permissions", () => {
     });
   });
 
+  it("serves catalog listing without mutating company skills", async () => {
+    mockCatalogService.listCatalogSkills.mockReturnValue([
+      {
+        id: "paperclipai:bundled:software-development:review",
+        key: "paperclipai/bundled/software-development/review",
+        kind: "bundled",
+        category: "software-development",
+        slug: "review",
+        name: "review",
+        description: "Review code",
+        path: "catalog/bundled/software-development/review",
+        entrypoint: "SKILL.md",
+        trustLevel: "markdown_only",
+        compatibility: "compatible",
+        defaultInstall: false,
+        recommendedForRoles: ["engineer"],
+        requires: [],
+        tags: ["review"],
+        files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
+        contentHash: "sha256:abc",
+      },
+    ]);
+
+    const res = await request(await createApp({
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    }))
+      .get("/api/skills/catalog?kind=bundled&q=review");
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(mockCatalogService.listCatalogSkills).toHaveBeenCalledWith({ kind: "bundled", q: "review" });
+    expect(mockCompanySkillService.importFromSource).not.toHaveBeenCalled();
+    expect(mockCompanySkillService.installFromCatalog).not.toHaveBeenCalled();
+    expect(mockLogActivity).not.toHaveBeenCalled();
+  });
+
+  it("requires authentication for catalog read routes", async () => {
+    const app = await createApp({ type: "none" });
+
+    const list = await request(app).get("/api/skills/catalog");
+    const detail = await request(app).get("/api/skills/catalog/review");
+    const file = await request(app).get("/api/skills/catalog/review/files?path=SKILL.md");
+
+    expect(list.status, JSON.stringify(list.body)).toBe(401);
+    expect(detail.status, JSON.stringify(detail.body)).toBe(401);
+    expect(file.status, JSON.stringify(file.body)).toBe(401);
+    expect(mockCatalogService.listCatalogSkills).not.toHaveBeenCalled();
+    expect(mockCatalogService.getCatalogSkillOrThrow).not.toHaveBeenCalled();
+    expect(mockCatalogService.readCatalogSkillFile).not.toHaveBeenCalled();
+  });
+
+  it("serves catalog detail and files by catalog reference", async () => {
+    const app = await createApp({
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    });
+
+    const detail = await request(app)
+      .get("/api/skills/catalog/review");
+    const file = await request(app)
+      .get("/api/skills/catalog/review/files?path=SKILL.md");
+
+    expect(detail.status, JSON.stringify(detail.body)).toBe(200);
+    expect(file.status, JSON.stringify(file.body)).toBe(200);
+    expect(mockCatalogService.getCatalogSkillOrThrow).toHaveBeenCalledWith("review");
+    expect(mockCatalogService.readCatalogSkillFile).toHaveBeenCalledWith("review", "SKILL.md");
+    expect(mockLogActivity).not.toHaveBeenCalled();
+  });
+
+  it("installs catalog skills with mutation permissions and logs provenance", async () => {
+    const res = await request(await createApp({
+      type: "board",
+      userId: "local-board",
+      companyIds: ["company-1"],
+      source: "local_implicit",
+      isInstanceAdmin: false,
+    }))
+      .post("/api/companies/company-1/skills/install-catalog")
+      .send({
+        catalogSkillId: "paperclipai:bundled:software-development:review",
+        slug: "review",
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockCompanySkillService.installFromCatalog).toHaveBeenCalledWith("company-1", {
+      catalogSkillId: "paperclipai:bundled:software-development:review",
+      slug: "review",
+    });
+    expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+      companyId: "company-1",
+      action: "company.skill_catalog_installed",
+      entityType: "company_skill",
+      entityId: "skill-1",
+      details: expect.objectContaining({
+        catalogId: "paperclipai:bundled:software-development:review",
+        catalogKey: "paperclipai/bundled/software-development/review",
+        originHash: "sha256:abc",
+      }),
+    }));
+  });
+
   it("tracks public GitHub skill imports with an explicit skill reference", async () => {
     mockCompanySkillService.importFromSource.mockResolvedValue({
       imported: [
@@ -285,6 +464,26 @@ describe("company skill mutation permissions", () => {
     expect(mockCompanySkillService.importFromSource).not.toHaveBeenCalled();
   });
 
+  it("blocks agent catalog installs for other companies", async () => {
+    mockAgentService.getById.mockResolvedValue({
+      id: "agent-1",
+      companyId: "company-1",
+      permissions: { canCreateAgents: true },
+    });
+
+    const res = await request(await createApp({
+      type: "agent",
+      agentId: "agent-1",
+      companyId: "company-1",
+      runId: "run-1",
+    }))
+      .post("/api/companies/company-2/skills/install-catalog")
+      .send({ catalogSkillId: "paperclipai:bundled:software-development:review" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(403);
+    expect(mockCompanySkillService.installFromCatalog).not.toHaveBeenCalled();
+  });
+
   it("allows agents with canCreateAgents to mutate company skills", async () => {
     mockAgentService.getById.mockResolvedValue({
       id: "agent-1",
@@ -305,120 +504,9 @@ describe("company skill mutation permissions", () => {
     expect(mockCompanySkillService.importFromSource).toHaveBeenCalledWith(
       "company-1",
       "https://github.com/vercel-labs/agent-browser",
-      undefined,
     );
   });
 
-  it("passes a PAT through skill import requests", async () => {
-    const res = await request(await createApp({
-      type: "board",
-      userId: "local-board",
-      companyIds: ["company-1"],
-      source: "local_implicit",
-      isInstanceAdmin: false,
-    }))
-      .post("/api/companies/company-1/skills/import")
-      .send({
-        source: "https://github.com/vercel-labs/agent-browser",
-        authToken: "ghp_private_token",
-      });
-
-    expect(res.status, JSON.stringify(res.body)).toBe(201);
-    expect(mockCompanySkillService.importFromSource).toHaveBeenCalledWith(
-      "company-1",
-      "https://github.com/vercel-labs/agent-browser",
-      "ghp_private_token",
-    );
-  });
-
-  it("updates a skill auth token", async () => {
-    mockCompanySkillService.updateSkillAuth.mockResolvedValue({
-      id: "skill-1",
-      slug: "find-skills",
-    });
-
-    const res = await request(await createApp({
-      type: "board",
-      userId: "local-board",
-      companyIds: ["company-1"],
-      source: "local_implicit",
-      isInstanceAdmin: false,
-    }))
-      .patch("/api/companies/company-1/skills/skill-1/auth")
-      .send({ authToken: "ghp_private_token" });
-
-    expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.updateSkillAuth).toHaveBeenCalledWith(
-      "company-1",
-      "skill-1",
-      "ghp_private_token",
-    );
-    expect(mockLogActivity).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({
-        companyId: "company-1",
-        action: "company.skill_auth_updated",
-        entityType: "company_skill",
-        entityId: "skill-1",
-        details: { slug: "find-skills" },
-      }),
-    );
-  });
-
-  it("clears a skill auth token", async () => {
-    mockCompanySkillService.updateSkillAuth.mockResolvedValue({
-      id: "skill-1",
-      slug: "find-skills",
-    });
-
-    const res = await request(await createApp({
-      type: "board",
-      userId: "local-board",
-      companyIds: ["company-1"],
-      source: "local_implicit",
-      isInstanceAdmin: false,
-    }))
-      .patch("/api/companies/company-1/skills/skill-1/auth")
-      .send({ authToken: null });
-
-    expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.updateSkillAuth).toHaveBeenCalledWith(
-      "company-1",
-      "skill-1",
-      null,
-    );
-    expect(mockLogActivity).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({
-        companyId: "company-1",
-        action: "company.skill_auth_removed",
-        entityType: "company_skill",
-        entityId: "skill-1",
-        details: { slug: "find-skills" },
-      }),
-    );
-  });
-
-  it("allows agents with canCreateAgents to scan project workspaces", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId: "company-1",
-      permissions: { canCreateAgents: true },
-    });
-
-    const res = await request(await createApp({
-      type: "agent",
-      agentId: "agent-1",
-      companyId: "company-1",
-      runId: "run-1",
-    }))
-      .post("/api/companies/company-1/skills/scan-projects")
-      .send({});
-
-    expect(res.status, JSON.stringify(res.body)).toBe(200);
-    expect(mockCompanySkillService.scanProjectWorkspaces).toHaveBeenCalledWith("company-1", {});
-  });
-
   it("returns a blocking error when attempting to delete a skill still used by agents", async () => {
     const { unprocessable } = await import("../errors.js");
     mockCompanySkillService.deleteSkill.mockImplementationOnce(async () => {

server/src/__tests__/company-skills-service.test.ts

@@ -3,7 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { promises as fs } from "node:fs";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
-import { companies, companySkills, createDb } from "@paperclipai/db";
+import { agents, companies, companySkills, createDb } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
   startEmbeddedPostgresTestDatabase,
@@ -23,15 +23,21 @@ describeEmbeddedPostgres("companySkillService.list", () => {
   let db!: ReturnType<typeof createDb>;
   let svc!: ReturnType<typeof companySkillService>;
   let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+  let oldPaperclipHome: string | undefined;
+  let paperclipHome: string | null = null;
   const cleanupDirs = new Set<string>();
 
   beforeAll(async () => {
     tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-skills-service-");
+    oldPaperclipHome = process.env.PAPERCLIP_HOME;
+    paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-company-skills-home-"));
+    process.env.PAPERCLIP_HOME = paperclipHome;
     db = createDb(tempDb.connectionString);
     svc = companySkillService(db);
   }, 20_000);
 
   afterEach(async () => {
+    await db.delete(agents);
     await db.delete(companySkills);
     await db.delete(companies);
     await Promise.all(Array.from(cleanupDirs, (dir) => fs.rm(dir, { recursive: true, force: true })));
@@ -39,6 +45,11 @@ describeEmbeddedPostgres("companySkillService.list", () => {
   });
 
   afterAll(async () => {
+    if (oldPaperclipHome === undefined) delete process.env.PAPERCLIP_HOME;
+    else process.env.PAPERCLIP_HOME = oldPaperclipHome;
+    if (paperclipHome) {
+      await fs.rm(paperclipHome, { recursive: true, force: true });
+    }
     await tempDb?.cleanup();
   });
 
@@ -96,4 +107,291 @@ describeEmbeddedPostgres("companySkillService.list", () => {
       message: "Company not found",
     });
   });
+
+  it("does not persist audit failures for remote-source skills", async () => {
+    const companyId = randomUUID();
+    const skillId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(companySkills).values({
+      id: skillId,
+      companyId,
+      key: "github.com/acme/remote-skill",
+      slug: "remote-skill",
+      name: "Remote Skill",
+      description: null,
+      markdown: "# Remote Skill\n",
+      sourceType: "github",
+      sourceLocator: "https://github.com/acme/remote-skill",
+      sourceRef: "main",
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: { sourceKind: "github", owner: "acme", repo: "remote-skill" },
+    });
+
+    await expect(svc.auditSkill(companyId, skillId)).rejects.toMatchObject({
+      status: 422,
+      message: "Only local-path and catalog-managed company skills support audit.",
+    });
+    await expect(svc.getById(companyId, skillId)).resolves.toMatchObject({
+      metadata: { sourceKind: "github", owner: "acme", repo: "remote-skill" },
+    });
+  });
+
+  it("preserves missing local-path skills that active agents still desire", async () => {
+    const companyId = randomUUID();
+    const skillId = randomUUID();
+    const skillKey = `company/${companyId}/reflection-coach`;
+    const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-missing-used-skill-")), "gone");
+    cleanupDirs.add(path.dirname(missingSkillDir));
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(companySkills).values({
+      id: skillId,
+      companyId,
+      key: skillKey,
+      slug: "reflection-coach",
+      name: "Reflection Coach",
+      description: null,
+      markdown: "# Reflection Coach\n",
+      sourceType: "local_path",
+      sourceLocator: missingSkillDir,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: { sourceKind: "local_path" },
+    });
+    await db.insert(agents).values({
+      id: randomUUID(),
+      companyId,
+      name: "Reviewer",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {
+        paperclipSkillSync: {
+          desiredSkills: [skillKey],
+        },
+      },
+    });
+
+    const listed = await svc.list(companyId);
+    const listedSkill = listed.find((skill) => skill.id === skillId);
+    const detail = await svc.detail(companyId, skillId);
+    const stored = await svc.getById(companyId, skillId);
+    const marker = stored?.metadata?.missingSource;
+
+    expect(listedSkill).toMatchObject({
+      id: skillId,
+      attachedAgentCount: 1,
+    });
+    expect(detail?.usedByAgents).toEqual([
+      expect.objectContaining({
+        name: "Reviewer",
+        desired: true,
+      }),
+    ]);
+    expect(marker).toMatchObject({
+      reason: "local_source_missing",
+      sourceType: "local_path",
+      sourceLocator: missingSkillDir,
+      sourcePath: missingSkillDir,
+    });
+    expect(Number.isNaN(Date.parse(String((marker as Record<string, unknown>).detectedAt)))).toBe(false);
+  });
+
+  it("continues pruning missing local-path skills that no active agent desires", async () => {
+    const companyId = randomUUID();
+    const skillId = randomUUID();
+    const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-missing-unused-skill-")), "gone");
+    cleanupDirs.add(path.dirname(missingSkillDir));
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(companySkills).values({
+      id: skillId,
+      companyId,
+      key: `company/${companyId}/unused-skill`,
+      slug: "unused-skill",
+      name: "Unused Skill",
+      description: null,
+      markdown: "# Unused Skill\n",
+      sourceType: "local_path",
+      sourceLocator: missingSkillDir,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: { sourceKind: "local_path" },
+    });
+
+    const listed = await svc.list(companyId);
+
+    expect(listed.find((skill) => skill.id === skillId)).toBeUndefined();
+    await expect(svc.getById(companyId, skillId)).resolves.toBeNull();
+  });
+
+  it("clears the missing-source marker when a local-path skill source returns", async () => {
+    const companyId = randomUUID();
+    const skillId = randomUUID();
+    const skillDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-restored-skill-"));
+    cleanupDirs.add(skillDir);
+    await fs.writeFile(path.join(skillDir, "SKILL.md"), "# Restored Skill\n", "utf8");
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(companySkills).values({
+      id: skillId,
+      companyId,
+      key: `company/${companyId}/restored-skill`,
+      slug: "restored-skill",
+      name: "Restored Skill",
+      description: null,
+      markdown: "# Restored Skill\n",
+      sourceType: "local_path",
+      sourceLocator: skillDir,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: {
+        sourceKind: "local_path",
+        missingSource: {
+          reason: "local_source_missing",
+          sourceType: "local_path",
+          sourceLocator: skillDir,
+          sourcePath: skillDir,
+          detectedAt: "2026-05-28T00:00:00.000Z",
+        },
+      },
+    });
+
+    await svc.list(companyId);
+    const stored = await svc.getById(companyId, skillId);
+
+    expect(stored?.metadata).toEqual({ sourceKind: "local_path" });
+  });
+
+  it("marks source-missing company skills as unavailable during read-only runtime listing", async () => {
+    const companyId = randomUUID();
+    const skillId = randomUUID();
+    const skillKey = `company/${companyId}/reflection-coach`;
+    const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-readonly-missing-skill-")), "gone");
+    cleanupDirs.add(path.dirname(missingSkillDir));
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(companySkills).values({
+      id: skillId,
+      companyId,
+      key: skillKey,
+      slug: "reflection-coach",
+      name: "Reflection Coach",
+      description: null,
+      markdown: "# Reflection Coach\n",
+      sourceType: "local_path",
+      sourceLocator: missingSkillDir,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: { sourceKind: "local_path" },
+    });
+    await db.insert(agents).values({
+      id: randomUUID(),
+      companyId,
+      name: "Reviewer",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {
+        paperclipSkillSync: {
+          desiredSkills: [skillKey],
+        },
+      },
+    });
+
+    const entries = await svc.listRuntimeSkillEntries(companyId, { materializeMissing: false });
+    const entry = entries.find((candidate) => candidate.key === skillKey);
+
+    expect(entry).toMatchObject({
+      key: skillKey,
+      sourceStatus: "missing",
+      missingDetail: expect.stringContaining(missingSkillDir),
+    });
+    await expect(fs.stat(entry!.source)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("materializes source-missing company skills from the stored markdown during runtime listing", async () => {
+    const companyId = randomUUID();
+    const skillId = randomUUID();
+    const skillKey = `company/${companyId}/runtime-coach`;
+    const missingSkillDir = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-runtime-missing-skill-")), "gone");
+    cleanupDirs.add(path.dirname(missingSkillDir));
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(companySkills).values({
+      id: skillId,
+      companyId,
+      key: skillKey,
+      slug: "runtime-coach",
+      name: "Runtime Coach",
+      description: null,
+      markdown: "# Runtime Coach\n\nRecovered from DB.\n",
+      sourceType: "local_path",
+      sourceLocator: missingSkillDir,
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+      metadata: { sourceKind: "local_path" },
+    });
+    await db.insert(agents).values({
+      id: randomUUID(),
+      companyId,
+      name: "Runner",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {
+        paperclipSkillSync: {
+          desiredSkills: [skillKey],
+        },
+      },
+    });
+
+    const entries = await svc.listRuntimeSkillEntries(companyId);
+    const entry = entries.find((candidate) => candidate.key === skillKey);
+
+    expect(entry).toMatchObject({
+      key: skillKey,
+      sourceStatus: "available",
+    });
+    await expect(fs.readFile(path.join(entry!.source, "SKILL.md"), "utf8")).resolves.toBe(
+      "# Runtime Coach\n\nRecovered from DB.\n",
+    );
+  });
 });

server/src/__tests__/document-annotation-routes.test.ts

@@ -0,0 +1,288 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const issueId = "11111111-1111-4111-8111-111111111111";
+const companyId = "22222222-2222-4222-8222-222222222222";
+const otherCompanyId = "33333333-3333-4333-8333-333333333333";
+
+const mockIssueService = vi.hoisted(() => ({
+  getById: vi.fn(),
+  assertCheckoutOwner: vi.fn(),
+}));
+const mockDocumentService = vi.hoisted(() => ({
+  getIssueDocumentByKey: vi.fn(),
+}));
+const mockAnnotationService = vi.hoisted(() => ({
+  listThreadsForIssueDocument: vi.fn(),
+  getThreadForIssueDocument: vi.fn(),
+  createThread: vi.fn(),
+  addComment: vi.fn(),
+  updateThread: vi.fn(),
+  remapOpenThreadsForDocument: vi.fn(),
+}));
+const mockIssueReferenceService = vi.hoisted(() => ({
+  diffIssueReferenceSummary: vi.fn(() => ({
+    addedReferencedIssues: [],
+    removedReferencedIssues: [],
+    currentReferencedIssues: [],
+  })),
+  emptySummary: vi.fn(() => ({ outbound: [], inbound: [] })),
+  listIssueReferenceSummary: vi.fn(async () => ({ outbound: [], inbound: [] })),
+  syncAnnotationComment: vi.fn(async () => undefined),
+  syncComment: vi.fn(async () => undefined),
+  syncDocument: vi.fn(async () => undefined),
+  syncIssue: vi.fn(async () => undefined),
+}));
+const mockHeartbeatService = vi.hoisted(() => ({
+  wakeup: vi.fn(async () => undefined),
+  reportRunActivity: vi.fn(async () => undefined),
+}));
+const mockLogActivity = vi.hoisted(() => vi.fn(async () => undefined));
+
+const documentPayload = {
+  id: "document-1",
+  companyId,
+  issueId,
+  key: "plan",
+  title: "Plan",
+  format: "markdown",
+  body: "Alpha selected text omega",
+  latestRevisionId: "44444444-4444-4444-8444-444444444444",
+  latestRevisionNumber: 1,
+  createdByAgentId: null,
+  createdByUserId: "board-user",
+  updatedByAgentId: null,
+  updatedByUserId: "board-user",
+  createdAt: new Date("2026-05-14T12:00:00.000Z"),
+  updatedAt: new Date("2026-05-14T12:00:00.000Z"),
+};
+
+const annotationThread = {
+  id: "55555555-5555-4555-8555-555555555555",
+  companyId,
+  issueId,
+  documentId: "document-1",
+  documentKey: "plan",
+  status: "open",
+  anchorState: "active",
+  anchorConfidence: "exact",
+  originalRevisionId: documentPayload.latestRevisionId,
+  originalRevisionNumber: 1,
+  currentRevisionId: documentPayload.latestRevisionId,
+  currentRevisionNumber: 1,
+  selectedText: "selected text",
+  prefixText: "Alpha ",
+  suffixText: " omega",
+  normalizedStart: 6,
+  normalizedEnd: 19,
+  markdownStart: 6,
+  markdownEnd: 19,
+  anchorSelector: {
+    quote: { exact: "selected text", prefix: "Alpha ", suffix: " omega" },
+    position: { normalizedStart: 6, normalizedEnd: 19, markdownStart: 6, markdownEnd: 19 },
+  },
+  createdByAgentId: null,
+  createdByUserId: "board-user",
+  resolvedByAgentId: null,
+  resolvedByUserId: null,
+  resolvedAt: null,
+  createdAt: new Date("2026-05-14T12:01:00.000Z"),
+  updatedAt: new Date("2026-05-14T12:01:00.000Z"),
+};
+
+const annotationComment = {
+  id: "66666666-6666-4666-8666-666666666666",
+  companyId,
+  threadId: annotationThread.id,
+  issueId,
+  documentId: "document-1",
+  body: "Please review PAP-1",
+  authorType: "user",
+  authorAgentId: null,
+  authorUserId: "board-user",
+  createdByRunId: null,
+  createdAt: new Date("2026-05-14T12:01:00.000Z"),
+  updatedAt: new Date("2026-05-14T12:01:00.000Z"),
+};
+
+function registerModuleMocks() {
+  vi.doMock("../services/index.js", () => ({
+    accessService: () => ({ canUser: vi.fn(), hasPermission: vi.fn(async () => false) }),
+    agentService: () => ({ getById: vi.fn(), list: vi.fn(async () => []) }),
+    companyService: () => ({ getById: vi.fn(async () => ({ id: companyId, attachmentMaxBytes: 10_000_000 })) }),
+    documentAnnotationService: () => mockAnnotationService,
+    documentService: () => mockDocumentService,
+    environmentService: () => ({}),
+    executionWorkspaceService: () => ({}),
+    feedbackService: () => ({}),
+    goalService: () => ({}),
+    heartbeatService: () => mockHeartbeatService,
+    instanceSettingsService: () => ({
+      get: vi.fn(async () => ({ id: "settings", general: {} })),
+      getExperimental: vi.fn(async () => ({})),
+      getGeneral: vi.fn(async () => ({})),
+      listCompanyIds: vi.fn(async () => [companyId]),
+    }),
+    issueApprovalService: () => ({}),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
+    issueReferenceService: () => mockIssueReferenceService,
+    issueService: () => mockIssueService,
+    issueThreadInteractionService: () => ({
+      expireRequestConfirmationsSupersededByComment: vi.fn(async () => []),
+      expireStaleRequestConfirmationsForIssueDocument: vi.fn(async () => []),
+    }),
+    logActivity: mockLogActivity,
+    projectService: () => ({}),
+    routineService: () => ({ syncRunStatusForIssue: vi.fn(async () => undefined) }),
+    workProductService: () => ({}),
+  }));
+}
+
+async function createApp(actor: "board" | "agent" = "board", actorCompanyId = companyId) {
+  const [{ issueRoutes }, { errorHandler }] = await Promise.all([
+    vi.importActual<typeof import("../routes/issues.js")>("../routes/issues.js"),
+    vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
+  ]);
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    (req as any).actor = actor === "agent"
+      ? {
+        type: "agent",
+        agentId: "77777777-7777-4777-8777-777777777777",
+        companyId: actorCompanyId,
+        runId: "88888888-8888-4888-8888-888888888888",
+      }
+      : {
+        type: "board",
+        userId: "board-user",
+        companyIds: [actorCompanyId],
+        source: "local_implicit",
+        isInstanceAdmin: false,
+      };
+    next();
+  });
+  app.use("/api", issueRoutes({} as any, {} as any));
+  app.use(errorHandler);
+  return app;
+}
+
+describe("document annotation routes", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.doUnmock("../routes/issues.js");
+    vi.doUnmock("../middleware/index.js");
+    registerModuleMocks();
+    vi.clearAllMocks();
+    mockIssueService.getById.mockResolvedValue({
+      id: issueId,
+      companyId,
+      title: "Annotation API",
+      status: "in_progress",
+      assigneeAgentId: null,
+    });
+    mockIssueService.assertCheckoutOwner.mockResolvedValue({});
+    mockDocumentService.getIssueDocumentByKey.mockResolvedValue(documentPayload);
+    mockAnnotationService.listThreadsForIssueDocument.mockImplementation(async (
+      _issueId: string,
+      _key: string,
+      options?: { includeComments?: boolean },
+    ) => (
+      options?.includeComments
+        ? [{ ...annotationThread, comments: [annotationComment] }]
+        : [annotationThread]
+    ));
+    mockAnnotationService.getThreadForIssueDocument.mockResolvedValue({ ...annotationThread, comments: [annotationComment] });
+    mockAnnotationService.createThread.mockResolvedValue({ ...annotationThread, comments: [annotationComment] });
+    mockAnnotationService.addComment.mockResolvedValue(annotationComment);
+    mockAnnotationService.updateThread.mockResolvedValue({ ...annotationThread, status: "resolved" });
+    mockAnnotationService.remapOpenThreadsForDocument.mockResolvedValue([]);
+  });
+
+  it("includes compact open annotations without comment bodies by default for agent document reads", async () => {
+    const res = await request(await createApp("agent"))
+      .get(`/api/issues/${issueId}/documents/plan`)
+      .expect(200);
+
+    expect(res.body.annotations).toHaveLength(1);
+    expect(res.body.annotations[0].comments).toBeUndefined();
+    expect(mockAnnotationService.listThreadsForIssueDocument).toHaveBeenCalledWith(issueId, "plan", {
+      status: "open",
+      includeComments: false,
+    });
+  });
+
+  it("includes annotation comment bodies on document reads only when explicitly requested", async () => {
+    const res = await request(await createApp("agent"))
+      .get(`/api/issues/${issueId}/documents/plan?includeAnnotationComments=true`)
+      .expect(200);
+
+    expect(res.body.annotations[0].comments[0].body).toBe("Please review PAP-1");
+    expect(mockAnnotationService.listThreadsForIssueDocument).toHaveBeenCalledWith(issueId, "plan", {
+      status: "open",
+      includeComments: true,
+    });
+  });
+
+  it("creates annotation threads, syncs references, logs activity, and wakes the assignee", async () => {
+    mockIssueService.getById.mockResolvedValue({
+      id: issueId,
+      companyId,
+      title: "Annotation API",
+      status: "todo",
+      assigneeAgentId: "99999999-9999-4999-8999-999999999999",
+    });
+
+    const res = await request(await createApp())
+      .post(`/api/issues/${issueId}/documents/plan/annotations`)
+      .send({
+        baseRevisionId: documentPayload.latestRevisionId,
+        baseRevisionNumber: 1,
+        selector: annotationThread.anchorSelector,
+        body: "Please review PAP-1",
+      })
+      .expect(201);
+
+    expect(res.body.id).toBe(annotationThread.id);
+    expect(mockIssueReferenceService.syncAnnotationComment).toHaveBeenCalledWith(annotationComment.id);
+    expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+      action: "issue.document_annotation_thread_created",
+    }));
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
+      "99999999-9999-4999-8999-999999999999",
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          annotationThreadId: annotationThread.id,
+          annotationCommentId: annotationComment.id,
+        }),
+      }),
+    );
+  });
+
+  it("rejects agent cross-company annotation reads", async () => {
+    await request(await createApp("agent", otherCompanyId))
+      .get(`/api/issues/${issueId}/documents/plan/annotations`)
+      .expect(403);
+  });
+
+  it("adds annotation comments and resolves threads", async () => {
+    await request(await createApp())
+      .post(`/api/issues/${issueId}/documents/plan/annotations/${annotationThread.id}/comments`)
+      .send({ body: "Reply with PAP-2" })
+      .expect(201);
+    expect(mockIssueReferenceService.syncAnnotationComment).toHaveBeenCalledWith(annotationComment.id);
+
+    const resolved = await request(await createApp())
+      .patch(`/api/issues/${issueId}/documents/plan/annotations/${annotationThread.id}`)
+      .send({ status: "resolved" })
+      .expect(200);
+    expect(resolved.body.status).toBe("resolved");
+    expect(mockLogActivity).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+      action: "issue.document_annotation_thread_resolved",
+    }));
+  });
+});

server/src/__tests__/document-annotations-service.test.ts

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  companies,
+  createDb,
+  documentAnnotationAnchorSnapshots,
+  documentAnnotationComments,
+  documentAnnotationThreads,
+  documentRevisions,
+  documents,
+  issueDocuments,
+  issues,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { documentAnnotationService } from "../services/document-annotations.js";
+import { documentService } from "../services/documents.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres document annotation service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+function deferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, resolve, reject };
+}
+
+describeEmbeddedPostgres("documentAnnotationService", () => {
+  let db!: ReturnType<typeof createDb>;
+  let annotations!: ReturnType<typeof documentAnnotationService>;
+  let docs!: ReturnType<typeof documentService>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-document-annotations-");
+    db = createDb(tempDb.connectionString);
+    annotations = documentAnnotationService(db);
+    docs = documentService(db);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(documentAnnotationAnchorSnapshots);
+    await db.delete(documentAnnotationComments);
+    await db.delete(documentAnnotationThreads);
+    await db.delete(documentRevisions);
+    await db.delete(issueDocuments);
+    await db.delete(documents);
+    await db.delete(issues);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function createIssueWithDocument() {
+    const companyId = randomUUID();
+    const issueId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(issues).values({
+      id: issueId,
+      companyId,
+      identifier: "PAP-9442",
+      title: "Annotation race",
+      description: "Validate annotation revision guards",
+      status: "in_progress",
+      priority: "high",
+    });
+
+    const created = await docs.upsertIssueDocument({
+      issueId,
+      key: "plan",
+      title: "Plan",
+      format: "markdown",
+      body: "Alpha selected text omega",
+    });
+
+    return { companyId, issueId, document: created.document };
+  }
+
+  it("fails closed when a concurrent document update wins before annotation thread creation commits", async () => {
+    const { companyId, issueId, document } = await createIssueWithDocument();
+    const concurrentUpdateCanCommit = deferred<void>();
+    const concurrentUpdateHasWritten = deferred<void>();
+
+    const concurrentUpdate = db.transaction(async (tx) => {
+      const now = new Date();
+      const [revision] = await tx
+        .insert(documentRevisions)
+        .values({
+          companyId,
+          documentId: document.id,
+          revisionNumber: document.latestRevisionNumber + 1,
+          title: "Plan",
+          format: "markdown",
+          body: "Alpha changed text omega",
+          changeSummary: "Concurrent edit",
+          createdAt: now,
+        })
+        .returning();
+
+      await tx
+        .update(documents)
+        .set({
+          latestBody: "Alpha changed text omega",
+          latestRevisionId: revision.id,
+          latestRevisionNumber: document.latestRevisionNumber + 1,
+          updatedAt: now,
+        })
+        .where(eq(documents.id, document.id));
+
+      concurrentUpdateHasWritten.resolve();
+      await concurrentUpdateCanCommit.promise;
+    });
+
+    await concurrentUpdateHasWritten.promise;
+
+    let annotationSettled = false;
+    const annotationResult = annotations
+      .createThread(
+        issueId,
+        "plan",
+        {
+          baseRevisionId: document.latestRevisionId!,
+          baseRevisionNumber: document.latestRevisionNumber,
+          selector: {
+            quote: { exact: "selected text", prefix: "Alpha ", suffix: " omega" },
+            position: { normalizedStart: 6, normalizedEnd: 19, markdownStart: 6, markdownEnd: 19 },
+          },
+          body: "Please review this text",
+        },
+        { actorType: "user", actorId: "board-user", userId: "board-user" },
+      )
+      .then(
+        () => ({ status: "fulfilled" as const }),
+        (error: unknown) => ({ status: "rejected" as const, error }),
+      )
+      .finally(() => {
+        annotationSettled = true;
+      });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(annotationSettled).toBe(false);
+
+    concurrentUpdateCanCommit.resolve();
+    await concurrentUpdate;
+
+    const result = await annotationResult;
+    expect(result.status).toBe("rejected");
+    if (result.status === "rejected") {
+      expect(result.error).toMatchObject({
+        status: 409,
+        message: "Annotation anchor requires the current document revision",
+        details: {
+          currentRevisionNumber: 2,
+        },
+      });
+    }
+
+    const threads = await db.select().from(documentAnnotationThreads);
+    expect(threads).toHaveLength(0);
+  });
+});

server/src/__tests__/environment-selection-route-guards.test.ts

@@ -90,6 +90,7 @@ vi.mock("../services/index.js", () => ({
     expireStaleRequestConfirmationsForIssueDocument: vi.fn(async () => []),
   }),
   documentService: () => ({}),
+  documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
   routineService: () => ({}),
   workProductService: () => ({}),
 }));

server/src/__tests__/execution-workspace-policy.test.ts

@@ -148,16 +148,117 @@ describe("execution workspace policy helpers", () => {
     });
   });
 
-  it("prefers persisted environment selection over issue and project defaults", () => {
+  it("reuses persisted workspace environment when it agrees with the assignee's identity", () => {
+    expect(
+      resolveExecutionWorkspaceEnvironmentId({
+        projectPolicy: { enabled: true, environmentId: "agent-env" },
+        issueSettings: { environmentId: "agent-env" },
+        workspaceConfig: { environmentId: "agent-env" },
+        agentDefaultEnvironmentId: "agent-env",
+        defaultEnvironmentId: "default-env",
+      }),
+    ).toEqual({
+      environmentId: "agent-env",
+      source: "workspace",
+      conflict: null,
+    });
+  });
+
+  it("refuses silent reuse when the persisted workspace env disagrees with the assignee (PAPA-380: sandbox agent on local workspace)", () => {
+    // Claude E2B was assigned to a child issue whose parent had already
+    // realized a `Local` workspace. The persisted workspace env must not
+    // shadow the agent's intended sandbox env.
+    expect(
+      resolveExecutionWorkspaceEnvironmentId({
+        projectPolicy: { enabled: true, environmentId: null },
+        issueSettings: { environmentId: "sandbox-env", mode: "shared_workspace" },
+        workspaceConfig: { environmentId: "local-env" },
+        agentDefaultEnvironmentId: "sandbox-env",
+        defaultEnvironmentId: "local-env",
+      }),
+    ).toEqual({
+      environmentId: "sandbox-env",
+      source: "issue",
+      conflict: {
+        reason: "reused_workspace_environment_mismatch",
+        workspaceEnvironmentId: "local-env",
+        assigneeIntendedEnvironmentId: "sandbox-env",
+        assigneeIntendedSource: "issue",
+      },
+    });
+  });
+
+  it("refuses silent reuse when a null-default (local) agent inherits a non-local workspace env (PAPA-431: Manual QA on engineer SSH workspace)", () => {
+    // Manual QA agent has defaultEnvironmentId: null. When a sibling issue's
+    // SSH workspace is inherited via inheritExecutionWorkspaceFromIssueId,
+    // the persisted SSH env must NOT shadow the agent's deliberate local
+    // identity. The inherited issueSettings.environmentId is treated as a
+    // promoted artifact, not an explicit operator choice.
+    expect(
+      resolveExecutionWorkspaceEnvironmentId({
+        projectPolicy: { enabled: true, environmentId: null },
+        issueSettings: { environmentId: "ssh-env", mode: "isolated_workspace" },
+        workspaceConfig: { environmentId: "ssh-env" },
+        agentDefaultEnvironmentId: null,
+        defaultEnvironmentId: "local-env",
+      }),
+    ).toEqual({
+      environmentId: "local-env",
+      source: "default",
+      conflict: {
+        reason: "reused_workspace_environment_mismatch",
+        workspaceEnvironmentId: "ssh-env",
+        assigneeIntendedEnvironmentId: "local-env",
+        assigneeIntendedSource: "default",
+      },
+    });
+  });
+
+  it("honors an explicit issue env override for null-default agents when no workspace is being reused", () => {
+    // Operator explicitly chose an env on this issue via PATCH (see the
+    // issues-service contract at issues-service.test.ts:1924). For null-default
+    // agents, this is a deliberate choice — only inherited issue env (which
+    // matches a reused workspace env) should be discarded.
     expect(
       resolveExecutionWorkspaceEnvironmentId({
         projectPolicy: { enabled: true, environmentId: "project-env" },
         issueSettings: { environmentId: "issue-env" },
-        workspaceConfig: { environmentId: "workspace-env" },
-        agentDefaultEnvironmentId: "agent-env",
-        defaultEnvironmentId: "default-env",
+        workspaceConfig: null,
+        agentDefaultEnvironmentId: null,
+        defaultEnvironmentId: "local-env",
       }),
-    ).toBe("workspace-env");
+    ).toEqual({
+      environmentId: "issue-env",
+      source: "issue",
+      conflict: null,
+    });
+  });
+
+  it("honors an explicit issue env override for null-default agents even against a disagreeing reused workspace", () => {
+    // Operator picked sandbox-env explicitly while the previously-realized
+    // workspace was on local-env. The mismatch is genuine — surface a conflict
+    // so the heartbeat forces a fresh realization on the operator's chosen env.
+    expect(
+      resolveExecutionWorkspaceEnvironmentId({
+        projectPolicy: { enabled: true, environmentId: null },
+        issueSettings: { environmentId: "sandbox-env", mode: "shared_workspace" },
+        workspaceConfig: { environmentId: "local-env" },
+        agentDefaultEnvironmentId: null,
+        defaultEnvironmentId: "local-env",
+      }),
+    ).toEqual({
+      environmentId: "sandbox-env",
+      source: "issue",
+      conflict: {
+        reason: "reused_workspace_environment_mismatch",
+        workspaceEnvironmentId: "local-env",
+        assigneeIntendedEnvironmentId: "sandbox-env",
+        assigneeIntendedSource: "issue",
+      },
+    });
+  });
+
+  it("prefers the explicit issue environment over project and agent defaults when no workspace is reused", () => {
     expect(
       resolveExecutionWorkspaceEnvironmentId({
         projectPolicy: { enabled: true, environmentId: "project-env" },
@@ -166,7 +267,11 @@ describe("execution workspace policy helpers", () => {
         agentDefaultEnvironmentId: "agent-env",
         defaultEnvironmentId: "default-env",
       }),
-    ).toBe("issue-env");
+    ).toEqual({
+      environmentId: "issue-env",
+      source: "issue",
+      conflict: null,
+    });
     expect(
       resolveExecutionWorkspaceEnvironmentId({
         projectPolicy: { enabled: true, environmentId: "project-env" },
@@ -175,7 +280,11 @@ describe("execution workspace policy helpers", () => {
         agentDefaultEnvironmentId: "agent-env",
         defaultEnvironmentId: "default-env",
       }),
-    ).toBe("project-env");
+    ).toEqual({
+      environmentId: "project-env",
+      source: "project",
+      conflict: null,
+    });
   });
 
   it("falls back to the agent default environment before the company default", () => {
@@ -187,7 +296,11 @@ describe("execution workspace policy helpers", () => {
         agentDefaultEnvironmentId: "agent-env",
         defaultEnvironmentId: "default-env",
       }),
-    ).toBe("agent-env");
+    ).toEqual({
+      environmentId: "agent-env",
+      source: "agent",
+      conflict: null,
+    });
     expect(
       resolveExecutionWorkspaceEnvironmentId({
         projectPolicy: { enabled: true, environmentId: null },
@@ -196,7 +309,11 @@ describe("execution workspace policy helpers", () => {
         agentDefaultEnvironmentId: "agent-env",
         defaultEnvironmentId: "default-env",
       }),
-    ).toBe("default-env");
+    ).toEqual({
+      environmentId: "default-env",
+      source: "project",
+      conflict: null,
+    });
     expect(
       resolveExecutionWorkspaceEnvironmentId({
         projectPolicy: null,
@@ -205,7 +322,11 @@ describe("execution workspace policy helpers", () => {
         agentDefaultEnvironmentId: null,
         defaultEnvironmentId: "default-env",
       }),
-    ).toBe("default-env");
+    ).toEqual({
+      environmentId: "default-env",
+      source: "default",
+      conflict: null,
+    });
     expect(
       resolveExecutionWorkspaceEnvironmentId({
         projectPolicy: { enabled: true, environmentId: null },
@@ -214,7 +335,11 @@ describe("execution workspace policy helpers", () => {
         agentDefaultEnvironmentId: null,
         defaultEnvironmentId: "default-env",
       }),
-    ).toBe("default-env");
+    ).toEqual({
+      environmentId: "default-env",
+      source: "default",
+      conflict: null,
+    });
   });
 
   it("maps persisted execution workspace modes back to issue settings", () => {

server/src/__tests__/first-admin-claim.test.ts

@@ -0,0 +1,56 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { createDb, instanceUserRoles } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { claimFirstInstanceAdmin } from "../first-admin-claim.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+describeEmbeddedPostgres("claimFirstInstanceAdmin", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-first-admin-claim-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(instanceUserRoles);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("inserts exactly one first admin and reports later claims as conflicts", async () => {
+    const firstUserId = `user-${randomUUID()}`;
+    const first = await claimFirstInstanceAdmin(db, { userId: firstUserId });
+
+    expect(first).toMatchObject({ status: "claimed", userId: firstUserId });
+
+    const second = await claimFirstInstanceAdmin(db, { userId: `user-${randomUUID()}` });
+    expect(second).toMatchObject({ status: "already_claimed", existingUserId: firstUserId });
+
+    const roles = await db.select().from(instanceUserRoles);
+    expect(roles).toHaveLength(1);
+    expect(roles[0]).toMatchObject({ userId: firstUserId, role: "instance_admin" });
+  });
+
+  it("runs onClaim inside the winning transaction", async () => {
+    const userId = `user-${randomUUID()}`;
+    const result = await claimFirstInstanceAdmin(db, {
+      userId,
+      onClaim: async (tx) => {
+        const roles = await tx.select().from(instanceUserRoles);
+        return roles.map((role) => role.userId);
+      },
+    });
+
+    expect(result).toMatchObject({ status: "claimed", userId, value: [userId] });
+  });
+});

server/src/__tests__/grok-local-skill-sync.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import {
+  listGrokSkills,
+  syncGrokSkills,
+} from "@paperclipai/adapter-grok-local/server";
+
+describe("grok local skill sync", () => {
+  const paperclipKey = "paperclipai/paperclip/paperclip";
+  const createAgentKey = "paperclipai/paperclip/paperclip-create-agent";
+
+  it("reports Grok skills as ephemeral workspace-mounted state", async () => {
+    const snapshot = await listGrokSkills({
+      agentId: "agent-1",
+      companyId: "company-1",
+      adapterType: "grok_local",
+      config: {
+        paperclipSkillSync: {
+          desiredSkills: [paperclipKey],
+        },
+      },
+    });
+
+    expect(snapshot.adapterType).toBe("grok_local");
+    expect(snapshot.supported).toBe(true);
+    expect(snapshot.mode).toBe("ephemeral");
+    expect(snapshot.desiredSkills).toContain(paperclipKey);
+    expect(snapshot.desiredSkills).toContain(createAgentKey);
+    expect(snapshot.entries.find((entry) => entry.key === paperclipKey)).toMatchObject({
+      required: true,
+      state: "configured",
+      detail: "Will be copied into `.claude/skills` in the execution workspace on the next run.",
+    });
+  });
+
+  it("tracks unavailable desired Grok skills as missing without persistent install state", async () => {
+    const snapshot = await syncGrokSkills({
+      agentId: "agent-2",
+      companyId: "company-1",
+      adapterType: "grok_local",
+      config: {
+        paperclipRuntimeSkills: [],
+        paperclipSkillSync: {
+          desiredSkills: ["unknown-skill"],
+        },
+      },
+    }, ["unknown-skill"]);
+
+    expect(snapshot.mode).toBe("ephemeral");
+    expect(snapshot.warnings).toContain(
+      'Desired skill "unknown-skill" is not available from the Paperclip skills directory.',
+    );
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "unknown-skill",
+      state: "missing",
+      origin: "external_unknown",
+      targetPath: null,
+    }));
+  });
+});

server/src/__tests__/health-dev-server-token.test.ts

@@ -96,6 +96,7 @@ describe("GET /health dev-server supervisor access", () => {
       expect(res.body).toEqual({
         status: "ok",
         deploymentMode: "authenticated",
+        deploymentExposure: "private",
         bootstrapStatus: "ready",
         bootstrapInviteActive: false,
         devServer: {

server/src/__tests__/health.test.ts

@@ -97,6 +97,7 @@ describe("GET /health", () => {
     expect(res.body).toEqual({
       status: "ok",
       deploymentMode: "authenticated",
+      deploymentExposure: "public",
       bootstrapStatus: "ready",
       bootstrapInviteActive: false,
     });
@@ -131,6 +132,7 @@ describe("GET /health", () => {
     expect(res.body).toEqual({
       status: "ok",
       deploymentMode: "authenticated",
+      deploymentExposure: "public",
       bootstrapStatus: "ready",
       bootstrapInviteActive: false,
     });

server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts

@@ -7,15 +7,26 @@ import { promisify } from "node:util";
 import { eq, ne } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import {
+  activityLog,
+  agentRuntimeState,
   agentTaskSessions,
+  agentWakeupRequests,
   agents,
   companies,
+  companySkills,
   createDb,
+  documentRevisions,
+  documents,
   executionWorkspaces,
+  heartbeatRunEvents,
   heartbeatRuns,
+  issueComments,
+  issueDocuments,
+  issuePlanDecompositions,
   issues,
   projects,
   projectWorkspaces,
+  workspaceOperations,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -97,6 +108,25 @@ describeEmbeddedPostgres("accepted plan workspace refresh", () => {
       const root = tempRoots.pop();
       if (root) await rm(root, { recursive: true, force: true }).catch(() => undefined);
     }
+    await db.delete(issuePlanDecompositions);
+    await db.delete(issueDocuments);
+    await db.delete(documentRevisions);
+    await db.delete(documents);
+    await db.delete(agentTaskSessions);
+    await db.delete(executionWorkspaces);
+    await db.delete(activityLog);
+    await db.delete(heartbeatRunEvents);
+    await db.delete(heartbeatRuns);
+    await db.delete(issueComments);
+    await db.delete(issues);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
+    await db.delete(agentWakeupRequests);
+    await db.delete(agentRuntimeState);
+    await db.delete(agents);
+    await db.delete(workspaceOperations);
+    await db.delete(companySkills);
+    await db.delete(companies);
   });
 
   afterAll(async () => {
@@ -104,6 +134,57 @@ describeEmbeddedPostgres("accepted plan workspace refresh", () => {
     await tempDb?.cleanup();
   });
 
+  async function seedAcceptedPlanClaim(args: {
+    companyId: string;
+    issueId: string;
+    ownerAgentId: string;
+    status?: "in_flight" | "completed";
+  }) {
+    const documentId = randomUUID();
+    const revisionId = randomUUID();
+
+    await db.insert(documents).values({
+      id: documentId,
+      companyId: args.companyId,
+      title: "Plan",
+      format: "markdown",
+      latestBody: "Plan body",
+      latestRevisionId: revisionId,
+      latestRevisionNumber: 1,
+      createdByAgentId: args.ownerAgentId,
+      updatedByAgentId: args.ownerAgentId,
+    });
+    await db.insert(documentRevisions).values({
+      id: revisionId,
+      companyId: args.companyId,
+      documentId,
+      revisionNumber: 1,
+      title: "Plan",
+      format: "markdown",
+      body: "Plan body",
+      createdByAgentId: args.ownerAgentId,
+    });
+    await db.insert(issueDocuments).values({
+      companyId: args.companyId,
+      issueId: args.issueId,
+      documentId,
+      key: "plan",
+    });
+    await db.insert(issuePlanDecompositions).values({
+      companyId: args.companyId,
+      sourceIssueId: args.issueId,
+      acceptedPlanRevisionId: revisionId,
+      status: args.status ?? "in_flight",
+      requestFingerprint: `claim:${args.issueId}`,
+      requestedChildCount: 1,
+      requestedChildren: [{ title: "child-1" }],
+      childIssueIds: [],
+      ownerAgentId: args.ownerAgentId,
+      updatedAt: new Date(),
+      ...(args.status === "completed" ? { completedAt: new Date() } : {}),
+    });
+  }
+
   it("realizes an isolated workspace and drops stale shared task-session params before executing", async () => {
     const companyId = randomUUID();
     const projectId = randomUUID();
@@ -276,4 +357,451 @@ describeEmbeddedPostgres("accepted plan workspace refresh", () => {
     });
     expect(isolatedRows[0]?.cwd).not.toBe(repoRoot);
   }, 20_000);
+
+  it("forces a fresh session and suppresses accepted-plan continuation when another issue owns the in-flight claim", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const issueId = randomUUID();
+    const otherPlanningIssueId = randomUUID();
+    const agentId = randomUUID();
+    const repoRoot = await createGitRepo();
+    tempRoots.push(repoRoot);
+
+    await instanceSettingsService(db).updateExperimental({
+      enableIsolatedWorkspaces: false,
+    });
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Accepted Plan Routing",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      cwd: repoRoot,
+      isPrimary: true,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(issues).values([
+      {
+        id: issueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Later planning wake",
+        status: "in_progress",
+        workMode: "planning",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9301",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: otherPlanningIssueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Earlier accepted plan",
+        status: "in_progress",
+        workMode: "planning",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9302",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ]);
+    await seedAcceptedPlanClaim({
+      companyId,
+      issueId: otherPlanningIssueId,
+      ownerAgentId: agentId,
+      status: "in_flight",
+    });
+    await db.insert(agentTaskSessions).values({
+      companyId,
+      agentId,
+      adapterType: "codex_local",
+      taskKey: issueId,
+      sessionParamsJson: {
+        sessionId: "stale-cross-issue-session",
+        cwd: repoRoot,
+      },
+      sessionDisplayId: "stale-cross-issue-session",
+    });
+    adapterExecute.mockImplementationOnce(async () => {
+      await db.update(issues).set({ status: "done", updatedAt: new Date() }).where(eq(issues.id, issueId));
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        sessionParams: { sessionId: "fresh-session" },
+        sessionDisplayId: "fresh-session",
+        summary: "Suppressed cross-issue accepted-plan continuation.",
+        provider: "test",
+        model: "test-model",
+      };
+    });
+
+    const heartbeat = heartbeatService(db);
+    const run = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_blockers_resolved",
+      payload: {
+        issueId,
+        interactionId: "interaction-cross-issue",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        mutation: "interaction",
+      },
+      contextSnapshot: {
+        issueId,
+        taskId: issueId,
+        wakeReason: "issue_blockers_resolved",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+      },
+    });
+
+    expect(run).not.toBeNull();
+    await vi.waitFor(async () => {
+      const latest = await heartbeat.getRun(run!.id);
+      expect(latest?.status).toBe("succeeded");
+    }, { timeout: 10_000 });
+
+    expect(adapterExecute).toHaveBeenCalledTimes(1);
+    const adapterInput = adapterExecute.mock.calls[0]?.[0] as {
+      runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+      context: Record<string, unknown>;
+    };
+    expect(adapterInput.runtime.sessionId).toBeNull();
+    expect(adapterInput.runtime.sessionParams).toBeNull();
+    expect(adapterInput.context.acceptedPlanWakeRouting).toEqual(expect.objectContaining({
+      reason: "other_issue_claim_in_flight",
+      otherActiveClaimIssueId: otherPlanningIssueId,
+      otherActiveClaimIdentifier: "PAP-9302",
+    }));
+    expect(adapterInput.context.paperclipTaskMarkdown).toContain("Make the plan only.");
+    expect(adapterInput.context.paperclipTaskMarkdown).not.toContain("Create child issues from the approved plan only");
+  }, 20_000);
+
+  it("guards cross-issue accepted-plan retries even when the waking issue is standard work mode", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const issueId = randomUUID();
+    const otherPlanningIssueId = randomUUID();
+    const agentId = randomUUID();
+    const repoRoot = await createGitRepo();
+    tempRoots.push(repoRoot);
+
+    await instanceSettingsService(db).updateExperimental({
+      enableIsolatedWorkspaces: false,
+    });
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Accepted Plan Routing",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      cwd: repoRoot,
+      isPrimary: true,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(issues).values([
+      {
+        id: issueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Implementation wake after accepted plan",
+        status: "in_progress",
+        workMode: "standard",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9401",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      {
+        id: otherPlanningIssueId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        title: "Earlier accepted plan",
+        status: "in_progress",
+        workMode: "planning",
+        priority: "medium",
+        assigneeAgentId: agentId,
+        identifier: "PAP-9402",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ]);
+    await seedAcceptedPlanClaim({
+      companyId,
+      issueId: otherPlanningIssueId,
+      ownerAgentId: agentId,
+      status: "in_flight",
+    });
+    await db.insert(agentTaskSessions).values({
+      companyId,
+      agentId,
+      adapterType: "codex_local",
+      taskKey: issueId,
+      sessionParamsJson: {
+        sessionId: "stale-standard-cross-issue-session",
+        cwd: repoRoot,
+      },
+      sessionDisplayId: "stale-standard-cross-issue-session",
+    });
+    adapterExecute.mockImplementationOnce(async () => {
+      await db.update(issues).set({ status: "done", updatedAt: new Date() }).where(eq(issues.id, issueId));
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        sessionParams: { sessionId: "fresh-session" },
+        sessionDisplayId: "fresh-session",
+        summary: "Suppressed cross-issue accepted-plan continuation for a standard-work wake.",
+        provider: "test",
+        model: "test-model",
+      };
+    });
+
+    const heartbeat = heartbeatService(db);
+    const run = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_commented",
+      payload: {
+        issueId,
+        interactionId: "interaction-standard-cross-issue",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        mutation: "interaction",
+      },
+      contextSnapshot: {
+        issueId,
+        taskId: issueId,
+        wakeReason: "issue_commented",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        forceFreshSession: true,
+        workspaceRefreshReason: "accepted_plan_confirmation",
+      },
+    });
+
+    expect(run).not.toBeNull();
+    await vi.waitFor(async () => {
+      const latest = await heartbeat.getRun(run!.id);
+      expect(latest?.status).toBe("succeeded");
+    }, { timeout: 10_000 });
+
+    expect(adapterExecute).toHaveBeenCalledTimes(1);
+    const adapterInput = adapterExecute.mock.calls[0]?.[0] as {
+      runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+      context: Record<string, unknown>;
+    };
+    expect(adapterInput.runtime.sessionId).toBeNull();
+    expect(adapterInput.runtime.sessionParams).toBeNull();
+    expect(adapterInput.context.acceptedPlanWakeRouting).toEqual(expect.objectContaining({
+      reason: "other_issue_claim_in_flight",
+      otherActiveClaimIssueId: otherPlanningIssueId,
+      otherActiveClaimIdentifier: "PAP-9402",
+    }));
+    expect(adapterInput.context.paperclipTaskMarkdown).toContain("Issue: \"PAP-9401\"");
+    expect(adapterInput.context.paperclipTaskMarkdown).not.toContain("Create child issues from the approved plan only");
+  }, 20_000);
+
+  it("preserves accepted-plan continuation resume state when the wake issue owns the in-flight claim", async () => {
+    const companyId = randomUUID();
+    const projectId = randomUUID();
+    const projectWorkspaceId = randomUUID();
+    const issueId = randomUUID();
+    const agentId = randomUUID();
+    const repoRoot = await createGitRepo();
+    tempRoots.push(repoRoot);
+
+    await instanceSettingsService(db).updateExperimental({
+      enableIsolatedWorkspaces: false,
+    });
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Accepted Plan Retry",
+      status: "active",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Primary",
+      cwd: repoRoot,
+      isPrimary: true,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await db.insert(issues).values({
+      id: issueId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      title: "Accepted plan retry",
+      status: "in_progress",
+      workMode: "planning",
+      priority: "medium",
+      assigneeAgentId: agentId,
+      identifier: "PAP-9303",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+    await seedAcceptedPlanClaim({
+      companyId,
+      issueId,
+      ownerAgentId: agentId,
+      status: "in_flight",
+    });
+    await db.insert(agentTaskSessions).values({
+      companyId,
+      agentId,
+      adapterType: "codex_local",
+      taskKey: issueId,
+      sessionParamsJson: {
+        sessionId: "accepted-plan-retry-session",
+        cwd: repoRoot,
+      },
+      sessionDisplayId: "accepted-plan-retry-session",
+    });
+    adapterExecute.mockImplementationOnce(async () => {
+      await db.update(issues).set({ status: "done", updatedAt: new Date() }).where(eq(issues.id, issueId));
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        sessionParams: { sessionId: "accepted-plan-retry-session" },
+        sessionDisplayId: "accepted-plan-retry-session",
+        summary: "Resumed accepted-plan continuation for the same issue.",
+        provider: "test",
+        model: "test-model",
+      };
+    });
+
+    const heartbeat = heartbeatService(db);
+    const run = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_blockers_resolved",
+      payload: {
+        issueId,
+        interactionId: "interaction-same-issue",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+        mutation: "interaction",
+      },
+      contextSnapshot: {
+        issueId,
+        taskId: issueId,
+        wakeReason: "issue_blockers_resolved",
+        interactionKind: "request_confirmation",
+        interactionStatus: "accepted",
+      },
+    });
+
+    expect(run).not.toBeNull();
+    await vi.waitFor(async () => {
+      const latest = await heartbeat.getRun(run!.id);
+      expect(latest?.status).toBe("succeeded");
+    }, { timeout: 10_000 });
+
+    expect(adapterExecute).toHaveBeenCalledTimes(1);
+    const adapterInput = adapterExecute.mock.calls[0]?.[0] as {
+      runtime: { sessionId: string | null; sessionParams: Record<string, unknown> | null };
+      context: Record<string, unknown>;
+    };
+    expect(adapterInput.runtime.sessionId).toBe("accepted-plan-retry-session");
+    expect(adapterInput.context.acceptedPlanWakeRouting).toBeUndefined();
+    expect(adapterInput.context.paperclipTaskMarkdown).toContain("Create child issues from the approved plan only");
+  }, 20_000);
 });

server/src/__tests__/heartbeat-comment-wake-batching.test.ts

@@ -442,12 +442,18 @@ describe("heartbeat comment wake batching", () => {
       gateway.releaseFirstWait();
 
       await waitFor(() => gateway.getAgentPayloads().length === 2);
+      const secondPayload = gateway.getAgentPayloads()[1] ?? {};
+      const secondRunId = typeof secondPayload.idempotencyKey === "string" ? secondPayload.idempotencyKey : null;
+      if (!secondRunId) {
+        throw new Error("Expected forwarded gateway payload to include an idempotencyKey run id");
+      }
+
       await waitFor(async () => {
         const runs = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId));
-        return runs.length === 2 && runs.every((run) => run.status === "succeeded");
+        const statusesByRunId = new Map(runs.map((run) => [run.id, run.status]));
+        return statusesByRunId.get(firstRun!.id) === "succeeded" && statusesByRunId.get(secondRunId) === "succeeded";
       }, 90_000);
 
-      const secondPayload = gateway.getAgentPayloads()[1] ?? {};
       expect(secondPayload.paperclip).toMatchObject({
         wake: {
           commentIds: [comment2.id, comment3.id],

server/src/__tests__/heartbeat-context-summary.test.ts

@@ -55,6 +55,23 @@ describe("buildPaperclipTaskMarkdown", () => {
     expect(acceptedConfirmation).not.toContain("Make the plan only.");
   });
 
+  it("adds accepted-plan continuation guidance for standard-work issues when the wake is flagged as a plan continuation", () => {
+    const acceptedConfirmation = buildPaperclipTaskMarkdown({
+      issue: {
+        id: "issue-2",
+        identifier: "PAP-415",
+        title: "Implement the fix",
+        workMode: "standard",
+        description: null,
+      },
+      acceptedPlanContinuation: true,
+    });
+
+    expect(acceptedConfirmation).toContain("Accepted plan directive:");
+    expect(acceptedConfirmation).toContain("Create child issues from the approved plan only");
+    expect(acceptedConfirmation).not.toContain("- Work mode: \"planning\"");
+  });
+
   it("prefers ordinary comment planning guidance over stale accepted confirmation state", () => {
     const commentWake = buildPaperclipTaskMarkdown({
       issue: {

server/src/__tests__/heartbeat-dependency-scheduling.test.ts

@@ -13,6 +13,7 @@ import {
   documents,
   environmentLeases,
   environments,
+  executionWorkspaces,
   heartbeatRunEvents,
   heartbeatRuns,
   issueComments,
@@ -20,6 +21,7 @@ import {
   issueRelations,
   issueTreeHolds,
   issues,
+  workspaceOperations,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -142,6 +144,8 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () =
     await db.delete(agents);
     await db.delete(companySkills);
     await db.delete(environments);
+    await db.delete(workspaceOperations);
+    await db.delete(executionWorkspaces);
     await db.delete(companies);
   });
 

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

@@ -11,21 +11,28 @@ import {
   companySkills,
   companies,
   costEvents,
+  documentAnnotationAnchorSnapshots,
+  documentAnnotationComments,
+  documentAnnotationThreads,
   createDb,
   documentRevisions,
   documents,
   environmentLeases,
   environments,
+  executionWorkspaces,
   heartbeatRunEvents,
   heartbeatRuns,
   issueComments,
   issueDocuments,
+  issuePlanDecompositions,
   issueRecoveryActions,
   issueRelations,
+  issueThreadInteractions,
   issueTreeHoldMembers,
   issueTreeHolds,
   issueWorkProducts,
   issues,
+  workspaceOperations,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -321,8 +328,14 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     await db.delete(agentRuntimeState);
     await db.delete(companySkills);
     await db.delete(costEvents);
+    await db.delete(workspaceOperations);
     await db.delete(environmentLeases);
     await db.delete(environments);
+    await db.delete(issuePlanDecompositions);
+    await db.delete(issueThreadInteractions);
+    await db.delete(documentAnnotationComments);
+    await db.delete(documentAnnotationAnchorSnapshots);
+    await db.delete(documentAnnotationThreads);
     await db.delete(issueWorkProducts);
     await db.delete(issueComments);
     await db.delete(issueDocuments);
@@ -368,6 +381,16 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     }
     for (let attempt = 0; attempt < 5; attempt += 1) {
       await db.delete(companySkills);
+      await db.delete(workspaceOperations);
+      await db.delete(executionWorkspaces);
+      await db.delete(issuePlanDecompositions);
+      await db.delete(issueThreadInteractions);
+      await db.delete(documentAnnotationComments);
+      await db.delete(documentAnnotationAnchorSnapshots);
+      await db.delete(documentAnnotationThreads);
+      await db.delete(issueDocuments);
+      await db.delete(documentRevisions);
+      await db.delete(documents);
       try {
         await db.delete(companies);
         break;
@@ -1958,7 +1981,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   });
 
   it("re-enqueues assigned todo work when the last issue run died and no wake remains", async () => {
-    const { agentId, issueId, runId } = await seedStrandedIssueFixture({
+    const { companyId, agentId, issueId, runId } = await seedStrandedIssueFixture({
       status: "todo",
       runStatus: "failed",
     });
@@ -2292,7 +2315,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   });
 
   it("re-enqueues continuation for stranded in-progress work with no active run", async () => {
-    const { agentId, issueId, runId } = await seedStrandedIssueFixture({
+    const { companyId, agentId, issueId, runId } = await seedStrandedIssueFixture({
       status: "in_progress",
       runStatus: "failed",
     });
@@ -2539,6 +2562,272 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(comments[0]?.body).not.toContain("- Failure: none recorded");
   });
 
+  it("keeps retrying transient adapter_failed continuation runs before the cap", async () => {
+    const { agentId, issueId, runId } = await seedStrandedIssueFixture({
+      status: "in_progress",
+      runStatus: "failed",
+      retryReason: "issue_continuation_needed",
+      runErrorCode: "adapter_failed",
+      runError: "ssh: connection reset",
+    });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileStrandedAssignedIssues();
+    expect(result.continuationRequeued).toBe(1);
+    expect(result.escalated).toBe(0);
+    expect(result.issueIds).toEqual([issueId]);
+
+    const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
+    expect(issue?.status).toBe("in_progress");
+
+    const runs = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId));
+    expect(runs).toHaveLength(2);
+    const retryRun = runs.find((row) => row.id !== runId);
+    expect(retryRun?.contextSnapshot as Record<string, unknown> | undefined).toMatchObject({
+      issueId,
+      retryReason: "issue_continuation_needed",
+      source: "issue.continuation_recovery",
+    });
+    if (retryRun) {
+      await waitForRunToSettle(heartbeat, retryRun.id);
+    }
+  });
+
+  it("escalates after repeated adapter_failed continuation retries with the cause in the comment", async () => {
+    const { companyId, agentId, issueId, runId } = await seedStrandedIssueFixture({
+      status: "in_progress",
+      runStatus: "failed",
+      retryReason: "issue_continuation_needed",
+      runErrorCode: "adapter_failed",
+      runError: "ssh: connection reset",
+    });
+    // Backfill two more consecutive failed continuation retries so the cap (3) is reached.
+    const olderTimestamps = [
+      new Date("2026-03-18T23:50:00.000Z"),
+      new Date("2026-03-18T23:55:00.000Z"),
+    ];
+    for (const finishedAt of olderTimestamps) {
+      await db.insert(heartbeatRuns).values({
+        id: randomUUID(),
+        companyId,
+        agentId,
+        invocationSource: "automation",
+        triggerDetail: "system",
+        status: "failed",
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          wakeReason: "issue_continuation_needed",
+          retryReason: "issue_continuation_needed",
+          source: "issue.continuation_recovery",
+        },
+        errorCode: "adapter_failed",
+        error: "ssh: connection reset",
+        startedAt: finishedAt,
+        finishedAt,
+        createdAt: finishedAt,
+        updatedAt: finishedAt,
+      });
+    }
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileStrandedAssignedIssues();
+    expect(result.continuationRequeued).toBe(0);
+    expect(result.escalated).toBe(1);
+    expect(result.issueIds).toEqual([issueId]);
+
+    const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
+    expect(issue?.status).toBe("blocked");
+
+    await expectSourceScopedStrandedRecoveryAction({
+      companyId,
+      agentId,
+      issueId,
+      runId,
+      previousStatus: "in_progress",
+      retryReason: "issue_continuation_needed",
+    });
+
+    const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));
+    expect(comments).toHaveLength(1);
+    expect(comments[0]?.body).toContain("retried continuation");
+    expect(comments[0]?.body).toContain("3× attempts");
+    expect(comments[0]?.body).toContain("Latest cause: `adapter_failed`");
+  });
+
+  it("does not count mixed-cause continuation failures toward the transient cap", async () => {
+    const { companyId, agentId, issueId, runId } = await seedStrandedIssueFixture({
+      status: "in_progress",
+      runStatus: "failed",
+      retryReason: "issue_continuation_needed",
+      runErrorCode: "adapter_failed",
+      runError: "ssh: connection reset",
+    });
+
+    await db.insert(heartbeatRuns).values([
+      {
+        id: randomUUID(),
+        companyId,
+        agentId,
+        invocationSource: "automation",
+        triggerDetail: "system",
+        status: "failed",
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          wakeReason: "issue_continuation_needed",
+          retryReason: "issue_continuation_needed",
+          source: "issue.continuation_recovery",
+        },
+        errorCode: "timeout",
+        error: "request timed out",
+        startedAt: new Date("2026-03-18T23:45:00.000Z"),
+        finishedAt: new Date("2026-03-18T23:45:00.000Z"),
+        createdAt: new Date("2026-03-18T23:45:00.000Z"),
+        updatedAt: new Date("2026-03-18T23:45:00.000Z"),
+      },
+      {
+        id: randomUUID(),
+        companyId,
+        agentId,
+        invocationSource: "automation",
+        triggerDetail: "system",
+        status: "failed",
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          wakeReason: "issue_continuation_needed",
+          retryReason: "issue_continuation_needed",
+          source: "issue.continuation_recovery",
+        },
+        errorCode: "timeout",
+        error: "request timed out",
+        startedAt: new Date("2026-03-18T23:50:00.000Z"),
+        finishedAt: new Date("2026-03-18T23:50:00.000Z"),
+        createdAt: new Date("2026-03-18T23:50:00.000Z"),
+        updatedAt: new Date("2026-03-18T23:50:00.000Z"),
+      },
+      {
+        id: randomUUID(),
+        companyId,
+        agentId,
+        invocationSource: "automation",
+        triggerDetail: "system",
+        status: "failed",
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          wakeReason: "issue_continuation_needed",
+          retryReason: "issue_continuation_needed",
+          source: "issue.continuation_recovery",
+        },
+        errorCode: "adapter_failed",
+        error: "ssh: connection reset",
+        startedAt: new Date("2026-03-18T23:55:00.000Z"),
+        finishedAt: new Date("2026-03-18T23:55:00.000Z"),
+        createdAt: new Date("2026-03-18T23:55:00.000Z"),
+        updatedAt: new Date("2026-03-18T23:55:00.000Z"),
+      },
+    ]);
+
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileStrandedAssignedIssues();
+    expect(result.continuationRequeued).toBe(1);
+    expect(result.escalated).toBe(0);
+    expect(result.issueIds).toEqual([issueId]);
+
+    const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
+    expect(issue?.status).toBe("in_progress");
+
+    const runs = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId));
+    expect(runs).toHaveLength(5);
+    const retryRun = runs.find((row) => {
+      const ctx = row.contextSnapshot as Record<string, unknown> | null;
+      return row.id !== runId &&
+        row.errorCode === null &&
+        ctx?.retryReason === "issue_continuation_needed" &&
+        ctx?.source === "issue.continuation_recovery";
+    });
+    expect(retryRun?.contextSnapshot as Record<string, unknown> | undefined).toMatchObject({
+      issueId,
+      retryReason: "issue_continuation_needed",
+      source: "issue.continuation_recovery",
+    });
+    if (retryRun) {
+      await waitForRunToSettle(heartbeat, retryRun.id);
+    }
+  });
+
+  it("escalates non-retryable continuation failures immediately without enqueuing another retry", async () => {
+    const { companyId, agentId, issueId, runId } = await seedStrandedIssueFixture({
+      status: "in_progress",
+      runStatus: "failed",
+      runErrorCode: "budget_blocked",
+      runError: "Budget exceeded; refusing to dispatch.",
+    });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileStrandedAssignedIssues();
+    expect(result.continuationRequeued).toBe(0);
+    expect(result.escalated).toBe(1);
+    expect(result.issueIds).toEqual([issueId]);
+
+    const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
+    expect(issue?.status).toBe("blocked");
+
+    await expectSourceScopedStrandedRecoveryAction({
+      companyId,
+      agentId,
+      issueId,
+      runId,
+      previousStatus: "in_progress",
+      retryReason: null,
+    });
+
+    const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));
+    expect(comments).toHaveLength(1);
+    expect(comments[0]?.body).toContain("non-retryable failure");
+    expect(comments[0]?.body).toContain("`budget_blocked`");
+
+    const followupRuns = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId));
+    const continuationRetryRun = followupRuns.find((row) => {
+      const ctx = row.contextSnapshot as Record<string, unknown> | null;
+      return ctx?.retryReason === "issue_continuation_needed";
+    });
+    expect(continuationRetryRun).toBeUndefined();
+    for (const row of followupRuns) {
+      if (row.id !== runId) {
+        await waitForRunToSettle(heartbeat, row.id);
+      }
+    }
+  });
+
+  it("leaves the productive-but-stranded continuation path unchanged under the new classifier", async () => {
+    const { agentId, issueId, runId } = await seedStrandedIssueFixture({
+      status: "in_progress",
+      runStatus: "succeeded",
+      livenessState: "advanced",
+    });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileStrandedAssignedIssues();
+    expect(result.continuationRequeued).toBe(1);
+    expect(result.escalated).toBe(0);
+    expect(result.issueIds).toEqual([issueId]);
+
+    const runs = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.agentId, agentId));
+    const retryRun = runs.find((row) => row.id !== runId);
+    expect(retryRun?.contextSnapshot as Record<string, unknown> | undefined).toMatchObject({
+      issueId,
+      retryReason: "issue_continuation_needed",
+      source: "issue.productive_terminal_continuation_recovery",
+    });
+    if (retryRun) {
+      await waitForRunToSettle(heartbeat, retryRun.id);
+    }
+  });
+
   it("reuses the raced stranded recovery issue when duplicate active recovery creation conflicts", async () => {
     const { companyId, issueId } = await seedStrandedIssueFixture({
       status: "in_progress",

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

@@ -170,6 +170,8 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {
         provisionCommand: "bash ./scripts/provision.sh",
       },
       shouldReuseExisting: false,
+      baseRef: null,
+      baseRefSha: null,
     })).toEqual({
       source: "task_session",
       createdByRuntime: true,
@@ -200,6 +202,8 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {
         provisionCommand: "bash ./scripts/new-provision.sh",
       },
       shouldReuseExisting: true,
+      baseRef: null,
+      baseRefSha: null,
     })).toEqual({
       config: {
         environmentId: "env-old",
@@ -209,6 +213,25 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {
       createdByRuntime: false,
     });
   });
+
+  it("records the resolved base ref SHA for newly realized workspaces", () => {
+    expect(mergeExecutionWorkspaceMetadataForPersistence({
+      existingMetadata: null,
+      source: "task_session",
+      createdByRuntime: true,
+      configSnapshot: null,
+      shouldReuseExisting: false,
+      baseRef: "origin/main",
+      baseRefSha: "abc1234567890",
+    })).toEqual({
+      source: "task_session",
+      createdByRuntime: true,
+      baseRefSnapshot: {
+        baseRef: "origin/main",
+        resolvedSha: "abc1234567890",
+      },
+    });
+  });
 });
 
 describe("buildRealizedExecutionWorkspaceFromPersisted", () => {

server/src/__tests__/instance-settings-routes.test.ts

@@ -64,6 +64,7 @@ describe("instance settings routes", () => {
     mockInstanceSettingsService.getExperimental.mockResolvedValue({
       enableEnvironments: false,
       enableIsolatedWorkspaces: false,
+      enableIssuePlanDecompositions: false,
       enableCloudSync: false,
       autoRestartDevServerWhenIdle: false,
       enableIssueGraphLivenessAutoRecovery: true,
@@ -82,6 +83,7 @@ describe("instance settings routes", () => {
       experimental: {
         enableEnvironments: true,
         enableIsolatedWorkspaces: true,
+        enableIssuePlanDecompositions: true,
         enableCloudSync: true,
         autoRestartDevServerWhenIdle: false,
         enableIssueGraphLivenessAutoRecovery: true,
@@ -125,6 +127,7 @@ describe("instance settings routes", () => {
     expect(getRes.body).toEqual({
       enableEnvironments: false,
       enableIsolatedWorkspaces: false,
+      enableIssuePlanDecompositions: false,
       enableCloudSync: false,
       autoRestartDevServerWhenIdle: false,
       enableIssueGraphLivenessAutoRecovery: true,

server/src/__tests__/instance-settings-service.test.ts

@@ -6,6 +6,7 @@ describe("instance settings service", () => {
     expect(normalizeExperimentalSettings({
       enableEnvironments: true,
       enableIsolatedWorkspaces: true,
+      enableIssuePlanDecompositions: true,
       enableCloudSync: true,
       autoRestartDevServerWhenIdle: true,
       enableIssueGraphLivenessAutoRecovery: true,
@@ -14,6 +15,7 @@ describe("instance settings service", () => {
     })).toEqual({
       enableEnvironments: true,
       enableIsolatedWorkspaces: true,
+      enableIssuePlanDecompositions: true,
       enableCloudSync: true,
       autoRestartDevServerWhenIdle: true,
       enableIssueGraphLivenessAutoRecovery: true,

server/src/__tests__/issue-activity-events-routes.test.ts

@@ -82,6 +82,7 @@ function registerModuleMocks() {
     agentService: () => ({
       getById: vi.fn(async () => null),
     }),
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => mockFeedbackService,

server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts

@@ -97,6 +97,7 @@ function registerRouteMocks() {
   }));
 
   vi.doMock("../services/documents.js", () => ({
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => mockDocumentService,
   }));
 
@@ -116,6 +117,7 @@ function registerRouteMocks() {
     accessService: () => mockAccessService,
     agentService: () => mockAgentService,
     companyService: () => mockCompanyService,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => mockDocumentService,
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({

server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts

@@ -36,6 +36,7 @@ vi.mock("../services/index.js", () => ({
   companyService: () => ({
     getById: vi.fn(async () => ({ id: "company-1", attachmentMaxBytes: 10 * 1024 * 1024 })),
   }),
+  documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
   documentService: () => ({
     getIssueDocumentPayload: vi.fn(async () => ({})),
   }),

server/src/__tests__/issue-attachment-routes.test.ts

@@ -43,6 +43,7 @@ function registerRouteMocks() {
       getById: vi.fn(),
     }),
     companyService: () => mockCompanyService,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({

server/src/__tests__/issue-closed-workspace-routes.test.ts

@@ -81,6 +81,7 @@ function registerServiceMocks() {
     agentService: () => ({
       getById: vi.fn(async () => null),
     }),
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => mockExecutionWorkspaceService,
     feedbackService: () => ({

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

@@ -79,6 +79,7 @@ function registerModuleMocks() {
     }),
     accessService: () => mockAccessService,
     agentService: () => ({ getById: vi.fn(async () => null) }),
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => mockFeedbackService,

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

@@ -123,6 +123,7 @@ vi.mock("../services/index.js", () => ({
   }),
   accessService: () => mockAccessService,
   agentService: () => mockAgentService,
+  documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
   documentService: () => ({}),
   executionWorkspaceService: () => ({}),
   feedbackService: () => mockFeedbackService,

server/src/__tests__/issue-dependency-wakeups-routes.test.ts

@@ -27,6 +27,7 @@ vi.mock("../services/index.js", () => ({
   agentService: () => ({
     getById: vi.fn(),
   }),
+  documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
   documentService: () => ({
     getIssueDocumentPayload: vi.fn(async () => ({})),
   }),

server/src/__tests__/issue-document-restore-routes.test.ts

@@ -88,6 +88,7 @@ function registerModuleMocks() {
   }));
 
   vi.doMock("../services/documents.js", () => ({
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => mockDocumentsService,
   }));
 
@@ -113,6 +114,7 @@ function registerModuleMocks() {
     }),
     accessService: () => mockAccessService,
     agentService: () => mockAgentService,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => mockDocumentsService,
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({}),

server/src/__tests__/issue-execution-policy-routes.test.ts

@@ -48,6 +48,7 @@ function registerModuleMocks() {
     agentService: () => ({
       getById: vi.fn(async () => null),
     }),
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({

server/src/__tests__/issue-feedback-routes.test.ts

@@ -87,6 +87,7 @@ function registerModuleMocks() {
     }),
     accessService: () => mockAccessService,
     agentService: () => mockAgentService,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => mockExecutionWorkspaceService,
     goalService: () => ({}),

server/src/__tests__/issue-telemetry-routes.test.ts

@@ -35,6 +35,7 @@ function registerModuleMocks() {
       hasPermission: vi.fn(),
     }),
     agentService: () => mockAgentService,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({}),

server/src/__tests__/issue-thread-interaction-routes.test.ts

@@ -61,6 +61,7 @@ function registerModuleMocks() {
     clampIssueListLimit: (value: number) => value,
     ISSUE_LIST_DEFAULT_LIMIT: 500,
     ISSUE_LIST_MAX_LIMIT: 1000,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({
@@ -536,6 +537,14 @@ describe.sequential("issue thread interaction routes", () => {
         payload: {
           version: 1,
           prompt: "Approve this plan?",
+          target: {
+            type: "issue_document",
+            issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+            documentId: "document-plan",
+            key: "plan",
+            revisionId: "revision-plan",
+            revisionNumber: 1,
+          },
         },
         result: {
           version: 1,
@@ -571,6 +580,65 @@ describe.sequential("issue thread interaction routes", () => {
     );
   });
 
+  it("forces a fresh workspace-aware session when accepting a plan document confirmation on a standard-work issue", async () => {
+    mockIssueService.getById.mockResolvedValueOnce(createIssue({ workMode: "standard" }));
+    mockInteractionService.acceptInteraction.mockResolvedValueOnce({
+      interaction: {
+        id: "interaction-standard-plan",
+        companyId: "company-1",
+        issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+        kind: "request_confirmation",
+        status: "accepted",
+        continuationPolicy: "wake_assignee_on_accept",
+        idempotencyKey: "confirmation:issue:plan:revision-standard",
+        sourceCommentId: null,
+        sourceRunId: "run-standard-plan",
+        payload: {
+          version: 1,
+          prompt: "Approve this plan?",
+          target: {
+            type: "issue_document",
+            issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+            documentId: "document-plan",
+            key: "plan",
+            revisionId: "revision-standard",
+            revisionNumber: 2,
+          },
+        },
+        result: {
+          version: 1,
+          outcome: "accepted",
+        },
+        createdAt: "2026-04-20T12:00:00.000Z",
+        updatedAt: "2026-04-20T12:05:00.000Z",
+        resolvedAt: "2026-04-20T12:05:00.000Z",
+      },
+      createdIssues: [],
+    });
+    const app = await createApp();
+
+    const res = await request(app)
+      .post("/api/issues/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa/interactions/interaction-standard-plan/accept")
+      .send({});
+
+    expect(res.status).toBe(200);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledTimes(1);
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith(
+      ASSIGNEE_AGENT_ID,
+      expect.objectContaining({
+        reason: "issue_commented",
+        contextSnapshot: expect.objectContaining({
+          issueId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
+          interactionId: "interaction-standard-plan",
+          interactionKind: "request_confirmation",
+          interactionStatus: "accepted",
+          forceFreshSession: true,
+          workspaceRefreshReason: "accepted_plan_confirmation",
+        }),
+      }),
+    );
+  });
+
   it("wakes the returned agent when accepting an agent-authored confirmation from a board review assignee", async () => {
     mockIssueService.getById.mockResolvedValueOnce(createIssue({
       status: "in_review",

server/src/__tests__/issue-thread-interactions-service.test.ts

@@ -7,6 +7,7 @@ import {
   createDb,
   documentRevisions,
   documents,
+  executionWorkspaces,
   goals,
   heartbeatRuns,
   issueComments,
@@ -15,6 +16,9 @@ import {
   issueRelations,
   issueThreadInteractions,
   issues,
+  projectWorkspaces,
+  projects,
+  workspaceOperations,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -48,7 +52,11 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
     await db.delete(documents);
     await db.delete(issueRelations);
     await db.delete(heartbeatRuns);
+    await db.delete(workspaceOperations);
     await db.delete(issues);
+    await db.delete(executionWorkspaces);
+    await db.delete(projectWorkspaces);
+    await db.delete(projects);
     await db.delete(goals);
     await db.delete(agents);
     await db.delete(instanceSettings);
@@ -1135,4 +1143,262 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
       },
     });
   });
+
+  describe("workspace_finalize accept gate", () => {
+    async function seedAcceptGateFixture() {
+      const companyId = randomUUID();
+      const projectId = randomUUID();
+      const projectWorkspaceId = randomUUID();
+      const executionWorkspaceId = randomUUID();
+      const issueId = randomUUID();
+      const goalId = 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: false });
+      await db.insert(projects).values({
+        id: projectId,
+        companyId,
+        name: "Project",
+        status: "in_progress",
+      });
+      await db.insert(projectWorkspaces).values({
+        id: projectWorkspaceId,
+        companyId,
+        projectId,
+        name: "Workspace",
+        sourceType: "local_path",
+        visibility: "default",
+        isPrimary: true,
+      });
+      await db.insert(executionWorkspaces).values({
+        id: executionWorkspaceId,
+        companyId,
+        projectId,
+        projectWorkspaceId,
+        mode: "isolated_workspace",
+        strategyType: "git_worktree",
+        name: "exec",
+        status: "active",
+        providerType: "git_worktree",
+      });
+      await db.insert(goals).values({
+        id: goalId,
+        companyId,
+        title: "Accept gate fixture",
+        level: "task",
+        status: "active",
+      });
+      await db.insert(issues).values({
+        id: issueId,
+        companyId,
+        projectId,
+        goalId,
+        title: "Issue with execution workspace",
+        status: "in_progress",
+        priority: "medium",
+        executionWorkspaceId,
+      });
+
+      const created = await interactionsSvc.create({
+        id: issueId,
+        companyId,
+      }, {
+        kind: "request_confirmation",
+        continuationPolicy: "wake_assignee",
+        payload: {
+          version: 1,
+          prompt: "Mark this issue done?",
+        },
+      }, {
+        userId: "local-board",
+      });
+
+      return { companyId, projectId, executionWorkspaceId, issueId, goalId, interactionId: created.id };
+    }
+
+    it("refuses accept when the issue's latest workspace operation is not a successful workspace_finalize", async () => {
+      const { companyId, executionWorkspaceId, issueId, goalId, interactionId } = await seedAcceptGateFixture();
+
+      // A run touched the workspace (prepare) but never recorded workspace_finalize.
+      await db.insert(workspaceOperations).values({
+        companyId,
+        executionWorkspaceId,
+        phase: "worktree_prepare",
+        status: "succeeded",
+        startedAt: new Date("2026-05-23T22:00:00.000Z"),
+      });
+
+      await expect(
+        interactionsSvc.acceptInteraction(
+          { id: issueId, companyId, goalId, projectId: null },
+          interactionId,
+          {},
+          { userId: "local-board" },
+        ),
+      ).rejects.toMatchObject({
+        status: 409,
+        details: { executionWorkspaceId },
+      });
+
+      const row = await db
+        .select()
+        .from(issueThreadInteractions)
+        .where(eq(issueThreadInteractions.id, interactionId))
+        .then((rows) => rows[0]);
+      expect(row?.status).toBe("pending");
+    });
+
+    it("refuses accept when the latest workspace operation is a failed workspace_finalize", async () => {
+      const { companyId, executionWorkspaceId, issueId, goalId, interactionId } = await seedAcceptGateFixture();
+
+      await db.insert(workspaceOperations).values({
+        companyId,
+        executionWorkspaceId,
+        phase: "worktree_prepare",
+        status: "succeeded",
+        startedAt: new Date("2026-05-23T22:00:00.000Z"),
+      });
+      await db.insert(workspaceOperations).values({
+        companyId,
+        executionWorkspaceId,
+        phase: "workspace_finalize",
+        status: "failed",
+        startedAt: new Date("2026-05-23T22:05:00.000Z"),
+      });
+
+      await expect(
+        interactionsSvc.acceptInteraction(
+          { id: issueId, companyId, goalId, projectId: null },
+          interactionId,
+          {},
+          { userId: "local-board" },
+        ),
+      ).rejects.toMatchObject({
+        status: 409,
+        details: { executionWorkspaceId },
+      });
+
+      const row = await db
+        .select()
+        .from(issueThreadInteractions)
+        .where(eq(issueThreadInteractions.id, interactionId))
+        .then((rows) => rows[0]);
+      expect(row?.status).toBe("pending");
+    });
+
+    it("allows accept once a successful workspace_finalize lands as the latest operation", async () => {
+      const { companyId, executionWorkspaceId, issueId, goalId, interactionId } = await seedAcceptGateFixture();
+
+      await db.insert(workspaceOperations).values({
+        companyId,
+        executionWorkspaceId,
+        phase: "workspace_finalize",
+        status: "failed",
+        startedAt: new Date("2026-05-23T22:05:00.000Z"),
+      });
+      await db.insert(workspaceOperations).values({
+        companyId,
+        executionWorkspaceId,
+        phase: "workspace_finalize",
+        status: "succeeded",
+        startedAt: new Date("2026-05-23T22:10:00.000Z"),
+      });
+
+      const accepted = await interactionsSvc.acceptInteraction(
+        { id: issueId, companyId, goalId, projectId: null },
+        interactionId,
+        {},
+        { userId: "local-board" },
+      );
+
+      expect(accepted.interaction).toMatchObject({
+        id: interactionId,
+        status: "accepted",
+      });
+    });
+
+    it("allows accept of suggest_tasks even when no successful workspace_finalize has landed", async () => {
+      // suggest_tasks acceptance only creates follow-up issues; it does not
+      // approve code state or move the source workspace forward, so the
+      // workspace_finalize gate (PAPA-440) must not apply here. Without this
+      // carve-out the board cannot triage suggested tasks on an issue whose
+      // latest workspace op is still worktree_prepare.
+      const { companyId, executionWorkspaceId, issueId, goalId } = await seedAcceptGateFixture();
+
+      await db.insert(workspaceOperations).values({
+        companyId,
+        executionWorkspaceId,
+        phase: "worktree_prepare",
+        status: "succeeded",
+        startedAt: new Date("2026-05-28T22:00:00.000Z"),
+      });
+
+      const created = await interactionsSvc.create({
+        id: issueId,
+        companyId,
+      }, {
+        kind: "suggest_tasks",
+        continuationPolicy: "wake_assignee",
+        payload: {
+          version: 1,
+          tasks: [
+            {
+              clientKey: "follow-up",
+              title: "Created from suggest_tasks accept under prepare-only workspace",
+            },
+          ],
+        },
+      }, {
+        userId: "local-board",
+      });
+
+      const accepted = await interactionsSvc.acceptInteraction(
+        { id: issueId, companyId, goalId, projectId: null },
+        created.id,
+        {},
+        { userId: "local-board" },
+      );
+
+      expect(accepted.interaction).toMatchObject({
+        id: created.id,
+        kind: "suggest_tasks",
+        status: "accepted",
+      });
+    });
+
+    it("allows accept when the issue has no execution workspace attached", async () => {
+      const { companyId, issueId } = await seedConfirmationIssue("No execution workspace accept");
+
+      const created = await interactionsSvc.create({
+        id: issueId,
+        companyId,
+      }, {
+        kind: "request_confirmation",
+        continuationPolicy: "wake_assignee",
+        payload: {
+          version: 1,
+          prompt: "Mark this issue done?",
+        },
+      }, {
+        userId: "local-board",
+      });
+
+      const accepted = await interactionsSvc.acceptInteraction(
+        { id: issueId, companyId, goalId: null, projectId: null },
+        created.id,
+        {},
+        { userId: "local-board" },
+      );
+
+      expect(accepted.interaction).toMatchObject({
+        id: created.id,
+        status: "accepted",
+      });
+    });
+  });
 });

server/src/__tests__/issue-update-comment-wakeup-routes.test.ts

@@ -48,6 +48,7 @@ vi.mock("../services/index.js", () => ({
       agent: { id: raw },
     })),
   }),
+  documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
   documentService: () => ({}),
   executionWorkspaceService: () => ({}),
   feedbackService: () => ({
@@ -116,6 +117,7 @@ function registerModuleMocks() {
         agent: { id: raw },
       })),
     }),
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => ({}),
     feedbackService: () => ({

server/src/__tests__/issue-workspace-command-authz.test.ts

@@ -95,6 +95,7 @@ function registerRouteMocks() {
     }),
     accessService: () => mockAccessService,
     agentService: () => mockAgentService,
+    documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
     documentService: () => ({}),
     executionWorkspaceService: () => mockExecutionWorkspaceService,
     feedbackService: () => mockFeedbackService,

server/src/__tests__/issues-goal-context-routes.test.ts

@@ -103,6 +103,7 @@ vi.mock("../services/index.js", () => ({
   }),
   accessService: () => mockAccessService,
   agentService: () => mockAgentService,
+  documentAnnotationService: () => ({ remapOpenThreadsForDocument: async () => [] }),
   documentService: () => mockDocumentsService,
   environmentService: () => mockEnvironmentService,
   executionWorkspaceService: () => mockExecutionWorkspaceService,

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

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { eq } from "drizzle-orm";
+import { asc, eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { sql } from "drizzle-orm";
 import {
@@ -7,6 +7,8 @@ import {
   agents,
   companies,
   createDb,
+  documentRevisions,
+  documents,
   environments,
   executionWorkspaces,
   goals,
@@ -14,10 +16,14 @@ import {
   instanceSettings,
   issueComments,
   issueInboxArchives,
+  issueDocuments,
+  issuePlanDecompositions,
   issueRelations,
+  issueThreadInteractions,
   issues,
   projectWorkspaces,
   projects,
+  workspaceOperations,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -2278,6 +2284,7 @@ describeEmbeddedPostgres("issueService blockers and dependency wake readiness",
     await db.delete(issueInboxArchives);
     await db.delete(activityLog);
     await db.delete(issues);
+    await db.delete(workspaceOperations);
     await db.delete(executionWorkspaces);
     await db.delete(projectWorkspaces);
     await db.delete(projects);
@@ -2447,6 +2454,179 @@ describeEmbeddedPostgres("issueService blockers and dependency wake readiness",
     ]);
   });
 
+  it("gates dependents on the workspace-finalize barrier when a done blocker's execution workspace has not synced back", async () => {
+    const companyId = randomUUID();
+    const assigneeAgentId = randomUUID();
+    const projectId = 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 db.insert(agents).values({
+      id: assigneeAgentId,
+      companyId,
+      name: "QA",
+      role: "qa",
+      status: "active",
+      adapterType: "claude_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(projects).values({
+      id: projectId,
+      companyId,
+      name: "Shared workspace project",
+      status: "in_progress",
+    });
+    await db.insert(projectWorkspaces).values({
+      id: projectWorkspaceId,
+      companyId,
+      projectId,
+      name: "Shared workspace",
+      sourceType: "local_path",
+      visibility: "default",
+      isPrimary: true,
+    });
+    await db.insert(executionWorkspaces).values({
+      id: executionWorkspaceId,
+      companyId,
+      projectId,
+      projectWorkspaceId,
+      mode: "isolated_workspace",
+      strategyType: "git_worktree",
+      name: "Shared exec workspace",
+      status: "active",
+      providerType: "git_worktree",
+    });
+
+    const blockerId = randomUUID();
+    const dependentId = randomUUID();
+    await db.insert(issues).values([
+      {
+        id: blockerId,
+        companyId,
+        projectId,
+        title: "Predecessor",
+        status: "done",
+        priority: "medium",
+        executionWorkspaceId,
+      },
+      {
+        id: dependentId,
+        companyId,
+        projectId,
+        title: "Dependent",
+        status: "blocked",
+        priority: "medium",
+        assigneeAgentId,
+      },
+    ]);
+    await svc.update(dependentId, { blockedByIssueIds: [blockerId] });
+
+    // A run touched the workspace (prepare phase) but has not yet recorded
+    // workspace_finalize — the dependent must NOT wake.
+    await db.insert(workspaceOperations).values({
+      companyId,
+      executionWorkspaceId,
+      phase: "worktree_prepare",
+      status: "succeeded",
+      startedAt: new Date("2026-05-23T22:00:00.000Z"),
+    });
+
+    expect(await svc.listWakeableBlockedDependents(blockerId)).toEqual([]);
+    await expect(svc.getDependencyReadiness(dependentId)).resolves.toMatchObject({
+      isDependencyReady: false,
+      pendingFinalizeBlockerIssueIds: [blockerId],
+      unresolvedBlockerIssueIds: [blockerId],
+    });
+
+    // A failed finalize must keep the gate closed.
+    await db.insert(workspaceOperations).values({
+      companyId,
+      executionWorkspaceId,
+      phase: "workspace_finalize",
+      status: "failed",
+      startedAt: new Date("2026-05-23T22:05:00.000Z"),
+    });
+    expect(await svc.listWakeableBlockedDependents(blockerId)).toEqual([]);
+
+    // Once a workspace_finalize succeeded row lands AFTER the failed one,
+    // the gate opens and the dependent is wakeable.
+    await db.insert(workspaceOperations).values({
+      companyId,
+      executionWorkspaceId,
+      phase: "workspace_finalize",
+      status: "succeeded",
+      startedAt: new Date("2026-05-23T22:10:00.000Z"),
+    });
+
+    await expect(svc.listWakeableBlockedDependents(blockerId)).resolves.toEqual([
+      expect.objectContaining({
+        id: dependentId,
+        assigneeAgentId,
+        blockerIssueIds: [blockerId],
+      }),
+    ]);
+    await expect(svc.getDependencyReadiness(dependentId)).resolves.toMatchObject({
+      isDependencyReady: true,
+      pendingFinalizeBlockerIssueIds: [],
+    });
+  });
+
+  it("treats blockers with no executionWorkspaceId as not subject to the workspace-finalize barrier", async () => {
+    const companyId = randomUUID();
+    const assigneeAgentId = 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: assigneeAgentId,
+      companyId,
+      name: "QA",
+      role: "qa",
+      status: "active",
+      adapterType: "claude_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    const blockerId = randomUUID();
+    const dependentId = randomUUID();
+    await db.insert(issues).values([
+      // Done blocker with no execution workspace ever attached (e.g. closed manually).
+      { id: blockerId, companyId, title: "Manual done blocker", status: "done", priority: "medium" },
+      {
+        id: dependentId,
+        companyId,
+        title: "Dependent",
+        status: "blocked",
+        priority: "medium",
+        assigneeAgentId,
+      },
+    ]);
+    await svc.update(dependentId, { blockedByIssueIds: [blockerId] });
+
+    // No executionWorkspaceId → no barrier → dependent should be wakeable.
+    await expect(svc.listWakeableBlockedDependents(blockerId)).resolves.toEqual([
+      expect.objectContaining({
+        id: dependentId,
+        assigneeAgentId,
+        blockerIssueIds: [blockerId],
+      }),
+    ]);
+  });
+
   it("reports dependency readiness for blocked issue chains", async () => {
     const companyId = randomUUID();
     await db.insert(companies).values({
@@ -3236,3 +3416,702 @@ describeEmbeddedPostgres("issueService.clearExecutionRunIfTerminal", () => {
     expect(row).toEqual({ executionRunId: null, executionLockedAt: null });
   });
 });
+
+describeEmbeddedPostgres("accepted plan decomposition", () => {
+  let db!: ReturnType<typeof createDb>;
+  let svc!: ReturnType<typeof issueService>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-accepted-plan-decomposition-");
+    db = createDb(tempDb.connectionString);
+    svc = issueService(db);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issuePlanDecompositions);
+    await db.delete(issueThreadInteractions);
+    await db.delete(issueDocuments);
+    await db.delete(documentRevisions);
+    await db.delete(documents);
+    await db.delete(issueComments);
+    await db.delete(issueRelations);
+    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(goals);
+    await db.delete(heartbeatRuns);
+    await db.delete(agents);
+    await db.delete(instanceSettings);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seedAcceptedPlanContext() {
+    const companyId = randomUUID();
+    const goalId = randomUUID();
+    const assigneeAgentId = 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: false });
+    await db.insert(agents).values({
+      id: assigneeAgentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(goals).values({
+      id: goalId,
+      companyId,
+      title: "Accepted plan decomposition",
+      level: "task",
+      status: "active",
+    });
+
+    return { companyId, goalId, assigneeAgentId };
+  }
+
+  async function seedAcceptedPlanIssue(args?: {
+    companyId?: string;
+    goalId?: string;
+    assigneeAgentId?: string;
+    sourceIssueId?: string;
+    issueTitle?: string;
+    workMode?: "planning" | "standard";
+  }) {
+    const companyId = args?.companyId ?? randomUUID();
+    const goalId = args?.goalId ?? randomUUID();
+    const assigneeAgentId = args?.assigneeAgentId ?? randomUUID();
+    const sourceIssueId = args?.sourceIssueId ?? randomUUID();
+    const planDocumentId = randomUUID();
+    const acceptedPlanRevisionId = randomUUID();
+    const acceptedInteractionId = randomUUID();
+
+    if (!args?.companyId || !args?.goalId || !args?.assigneeAgentId) {
+      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: false });
+      await db.insert(agents).values({
+        id: assigneeAgentId,
+        companyId,
+        name: "CodexCoder",
+        role: "engineer",
+        status: "active",
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      });
+      await db.insert(goals).values({
+        id: goalId,
+        companyId,
+        title: "Accepted plan decomposition",
+        level: "task",
+        status: "active",
+      });
+    }
+
+    await db.insert(issues).values({
+      id: sourceIssueId,
+      companyId,
+      goalId,
+      title: args?.issueTitle ?? "Planning issue",
+      status: "in_progress",
+      priority: "medium",
+      workMode: args?.workMode ?? "planning",
+      assigneeAgentId: assigneeAgentId,
+    });
+    await db.insert(documents).values({
+      id: planDocumentId,
+      companyId,
+      title: "Plan",
+      format: "markdown",
+      latestBody: "Plan body",
+      latestRevisionId: acceptedPlanRevisionId,
+      latestRevisionNumber: 1,
+      createdByAgentId: assigneeAgentId,
+      updatedByAgentId: assigneeAgentId,
+    });
+    await db.insert(documentRevisions).values({
+      id: acceptedPlanRevisionId,
+      companyId,
+      documentId: planDocumentId,
+      revisionNumber: 1,
+      title: "Plan",
+      format: "markdown",
+      body: "Plan body",
+      createdByAgentId: assigneeAgentId,
+    });
+    await db.insert(issueDocuments).values({
+      companyId,
+      issueId: sourceIssueId,
+      documentId: planDocumentId,
+      key: "plan",
+    });
+    await db.insert(issueThreadInteractions).values({
+      id: acceptedInteractionId,
+      companyId,
+      issueId: sourceIssueId,
+      kind: "request_confirmation",
+      status: "accepted",
+      continuationPolicy: "wake_assignee",
+      payload: {
+        version: 1,
+        prompt: "Approve this plan?",
+        target: {
+          type: "issue_document",
+          issueId: sourceIssueId,
+          documentId: planDocumentId,
+          key: "plan",
+          revisionId: acceptedPlanRevisionId,
+          revisionNumber: 1,
+        },
+      },
+      result: {
+        version: 1,
+        outcome: "accepted",
+      },
+      resolvedAt: new Date(),
+      createdByUserId: "local-board",
+      resolvedByUserId: "local-board",
+    });
+
+    return { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId };
+  }
+
+  async function getAcceptedPlanClaim(sourceIssueId: string) {
+    return db
+      .select()
+      .from(issuePlanDecompositions)
+      .where(eq(issuePlanDecompositions.sourceIssueId, sourceIssueId))
+      .then((rows) => rows[0] ?? null);
+  }
+
+  it("reuses the same child issue set on repeat decomposition attempts for an accepted plan revision", async () => {
+    const { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+
+    const children = [
+      {
+        title: "Implement the claim table",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+        assigneeAgentId,
+      },
+      {
+        title: "Add decomposition route tests",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const first = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(first.decomposition).not.toHaveProperty("requestedChildren");
+    expect(first.childIssueIds).toHaveLength(2);
+    expect(first.newlyCreatedIssues).toHaveLength(2);
+    expect(first.decomposition.status).toBe("completed");
+
+    const second = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(second.childIssueIds).toEqual(first.childIssueIds);
+    expect(second.newlyCreatedIssues).toHaveLength(0);
+    expect(second.decomposition.status).toBe("completed");
+
+    const persistedClaims = await db
+      .select()
+      .from(issuePlanDecompositions)
+      .where(eq(issuePlanDecompositions.sourceIssueId, sourceIssueId));
+    expect(persistedClaims).toHaveLength(1);
+    expect(persistedClaims[0]?.requestedChildCount).toBe(2);
+    expect(persistedClaims[0]?.childIssueIds).toEqual(first.childIssueIds);
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.map((row) => row.id).sort()).toEqual([...first.childIssueIds].sort());
+
+    const companyIssues = await svc.list(companyId, { parentId: sourceIssueId });
+    expect(companyIssues).toHaveLength(2);
+  });
+
+  it("rejects a different child set for the same accepted plan fingerprint", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+
+    await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Implement the claim table",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    await expect(svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Implement the claim table",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+        {
+          title: "This duplicate should be rejected",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    })).rejects.toMatchObject({
+      status: 409,
+    });
+  });
+
+  it("allows accepted-plan decomposition on a standard-work issue with an accepted plan document", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue({
+      workMode: "standard",
+      issueTitle: "Implement after planning",
+    });
+
+    const result = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Implement the approved first slice",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(result.childIssueIds).toHaveLength(1);
+    expect(result.newlyCreatedIssues).toHaveLength(1);
+    expect(result.decomposition.status).toBe("completed");
+  });
+
+  it("serializes concurrent accepted-plan retries for the same parent issue without duplicate children", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const children = [
+      {
+        title: "Persist exact-once decomposition claim",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+      {
+        title: "Guard concurrent retry callers",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+    expect(claim).not.toBeNull();
+
+    for (const childIssueId of initial.childIssueIds) {
+      await db.delete(issues).where(eq(issues.id, childIssueId));
+    }
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [],
+        completedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const svcA = issueService(db);
+    const svcB = issueService(db);
+    const [first, second] = await Promise.all([
+      svcA.decomposeAcceptedPlan(sourceIssueId, {
+        acceptedPlanRevisionId,
+        children,
+        actorAgentId: assigneeAgentId,
+      }),
+      svcB.decomposeAcceptedPlan(sourceIssueId, {
+        acceptedPlanRevisionId,
+        children,
+        actorAgentId: assigneeAgentId,
+      }),
+    ]);
+
+    expect(first.childIssueIds).toEqual(second.childIssueIds);
+    expect(first.childIssueIds).toHaveLength(2);
+    expect(first.newlyCreatedIssues.length + second.newlyCreatedIssues.length).toBe(2);
+
+    const persistedClaim = await getAcceptedPlanClaim(sourceIssueId);
+    expect(persistedClaim?.status).toBe("completed");
+    expect(persistedClaim?.childIssueIds).toEqual(first.childIssueIds);
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.map((row) => row.id).sort()).toEqual([...first.childIssueIds].sort());
+  });
+
+  it("rejects another planning parent's accepted revision even when both issues share the assignee", async () => {
+    const { companyId, goalId, assigneeAgentId } = await seedAcceptedPlanContext();
+    const firstIssue = await seedAcceptedPlanIssue({
+      companyId,
+      goalId,
+      assigneeAgentId,
+      issueTitle: "Earlier accepted plan",
+    });
+    const secondIssue = await seedAcceptedPlanIssue({
+      companyId,
+      goalId,
+      assigneeAgentId,
+      issueTitle: "Later accepted plan",
+    });
+
+    await svc.decomposeAcceptedPlan(firstIssue.sourceIssueId, {
+      acceptedPlanRevisionId: firstIssue.acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Decompose the first issue only",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    await expect(svc.decomposeAcceptedPlan(secondIssue.sourceIssueId, {
+      acceptedPlanRevisionId: firstIssue.acceptedPlanRevisionId,
+      children: [
+        {
+          title: "This must not land on the second parent",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    })).rejects.toMatchObject({
+      status: 422,
+    });
+
+    const secondIssueChildren = await db
+      .select({ id: issues.id })
+      .from(issues)
+      .where(eq(issues.parentId, secondIssue.sourceIssueId));
+    expect(secondIssueChildren).toHaveLength(0);
+  });
+
+  it("resumes partial child creation under the claimed fingerprint without duplicating completed children", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const children = [
+      {
+        title: "Create the first child once",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+      {
+        title: "Recreate only the missing tail child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+    expect(claim).not.toBeNull();
+
+    const [firstChildId, secondChildId] = initial.childIssueIds;
+    expect(firstChildId).toBeTruthy();
+    expect(secondChildId).toBeTruthy();
+
+    await db.delete(issues).where(eq(issues.id, secondChildId!));
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [firstChildId!],
+        completedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const retried = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+
+    expect(retried.decomposition.status).toBe("completed");
+    expect(retried.childIssueIds[0]).toBe(firstChildId);
+    expect(retried.newlyCreatedIssues).toHaveLength(1);
+    expect(retried.newlyCreatedIssues[0]?.title).toBe("Recreate only the missing tail child");
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.some((row) => row.id === firstChildId)).toBe(true);
+    expect(childrenRows.map((row) => row.title).sort()).toEqual(children.map((child) => child.title).sort());
+  });
+
+  it("resumes a partial decomposition after reassignment when only actor metadata changes", async () => {
+    const { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const reassignedAgentId = randomUUID();
+    await db.insert(agents).values({
+      id: reassignedAgentId,
+      companyId,
+      name: "SecondCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    const children = [
+      {
+        title: "Keep the original child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+        createdByAgentId: assigneeAgentId,
+        actorAgentId: assigneeAgentId,
+      },
+      {
+        title: "Create only the missing child after reassignment",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+        createdByAgentId: assigneeAgentId,
+        actorAgentId: assigneeAgentId,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+    });
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+    const [firstChildId, secondChildId] = initial.childIssueIds;
+
+    expect(claim).not.toBeNull();
+    expect(firstChildId).toBeTruthy();
+    expect(secondChildId).toBeTruthy();
+
+    await db.delete(issues).where(eq(issues.id, secondChildId!));
+    await db
+      .update(issues)
+      .set({ assigneeAgentId: reassignedAgentId, updatedAt: new Date() })
+      .where(eq(issues.id, sourceIssueId));
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [firstChildId!],
+        completedAt: null,
+        ownerAgentId: assigneeAgentId,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const retried = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: children.map((child) => ({
+        ...child,
+        createdByAgentId: reassignedAgentId,
+        actorAgentId: reassignedAgentId,
+      })),
+      actorAgentId: reassignedAgentId,
+    });
+
+    expect(retried.decomposition.status).toBe("completed");
+    expect(retried.decomposition.ownerAgentId).toBe(reassignedAgentId);
+    expect(retried.childIssueIds[0]).toBe(firstChildId);
+    expect(retried.newlyCreatedIssues).toHaveLength(1);
+    expect(retried.newlyCreatedIssues[0]?.title).toBe("Create only the missing child after reassignment");
+
+    const childrenRows = await db
+      .select({ id: issues.id, title: issues.title, createdByAgentId: issues.createdByAgentId })
+      .from(issues)
+      .where(eq(issues.parentId, sourceIssueId))
+      .orderBy(asc(issues.createdAt), asc(issues.id));
+    expect(childrenRows).toHaveLength(2);
+    expect(childrenRows.map((row) => row.id).sort()).toEqual([...retried.childIssueIds].sort());
+    expect(childrenRows.find((row) => row.id !== firstChildId)?.createdByAgentId).toBe(reassignedAgentId);
+  });
+
+  it("preserves the existing live claim owner when another actor resumes the same fingerprint", async () => {
+    const { companyId, sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+    const competingAgentId = randomUUID();
+    const liveOwnerRunId = randomUUID();
+    const competingRunId = randomUUID();
+    await db.insert(agents).values({
+      id: competingAgentId,
+      companyId,
+      name: "SecondCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+    await db.insert(heartbeatRuns).values([
+      {
+        id: liveOwnerRunId,
+        companyId,
+        agentId: assigneeAgentId,
+        status: "running",
+        invocationSource: "manual",
+      },
+      {
+        id: competingRunId,
+        companyId,
+        agentId: competingAgentId,
+        status: "running",
+        invocationSource: "manual",
+      },
+    ]);
+
+    const children = [
+      {
+        title: "Keep the first created child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+      {
+        title: "Create the missing second child",
+        status: "todo" as const,
+        workMode: "standard" as const,
+        priority: "medium" as const,
+      },
+    ];
+
+    const initial = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: assigneeAgentId,
+      actorRunId: liveOwnerRunId,
+    });
+    const [firstChildId, secondChildId] = initial.childIssueIds;
+    const claim = await getAcceptedPlanClaim(sourceIssueId);
+
+    await db.delete(issues).where(eq(issues.id, secondChildId!));
+    await db
+      .update(issuePlanDecompositions)
+      .set({
+        status: "in_flight",
+        childIssueIds: [firstChildId!],
+        completedAt: null,
+        ownerAgentId: assigneeAgentId,
+        ownerRunId: liveOwnerRunId,
+        updatedAt: new Date(),
+      })
+      .where(eq(issuePlanDecompositions.id, claim!.id));
+
+    const retried = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children,
+      actorAgentId: competingAgentId,
+      actorRunId: competingRunId,
+    });
+
+    expect(retried.decomposition.status).toBe("completed");
+    expect(retried.decomposition.ownerAgentId).toBe(assigneeAgentId);
+    expect(retried.decomposition.ownerRunId).toBe(liveOwnerRunId);
+  });
+
+  it("lists persisted decompositions with child issue summaries", async () => {
+    const { sourceIssueId, acceptedPlanRevisionId, assigneeAgentId } = await seedAcceptedPlanIssue();
+
+    const initial = await svc.listAcceptedPlanDecompositions(sourceIssueId);
+    expect(initial).toEqual([]);
+
+    const result = await svc.decomposeAcceptedPlan(sourceIssueId, {
+      acceptedPlanRevisionId,
+      children: [
+        {
+          title: "Surface decomposition status in operator UI",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+        {
+          title: "Add regression coverage",
+          status: "todo",
+          workMode: "standard",
+          priority: "medium",
+        },
+      ],
+      actorAgentId: assigneeAgentId,
+    });
+
+    const decompositions = await svc.listAcceptedPlanDecompositions(sourceIssueId);
+    expect(decompositions).toHaveLength(1);
+    const [record] = decompositions;
+    expect(record?.status).toBe("completed");
+    expect(record?.acceptedPlanRevisionId).toBe(acceptedPlanRevisionId);
+    expect(record?.acceptedPlanRevisionNumber).toBeTypeOf("number");
+    expect(record?.childIssues.map((child) => child.id).sort()).toEqual(
+      [...result.childIssueIds].sort(),
+    );
+    expect(record).not.toHaveProperty("requestedChildren");
+    expect(record?.childIssues.every((child) => typeof child.title === "string")).toBe(true);
+  });
+});

server/src/__tests__/plugin-routes-authz.test.ts

@@ -139,6 +139,27 @@ describe.sequential("plugin install and upgrade authz", () => {
     vi.clearAllMocks();
   });
 
+  it("lists bundled monorepo plugin packages", async () => {
+    const { app } = await createApp(boardActor());
+
+    const res = await request(app).get("/api/plugins/examples");
+
+    expect(res.status).toBe(200);
+    const packageNames = res.body.map((plugin: { packageName: string }) => plugin.packageName);
+    const byPackageName = new Map(
+      res.body.map((plugin: { packageName: string; experimental: boolean }) => [plugin.packageName, plugin]),
+    );
+    expect(packageNames).toContain("@paperclipai/plugin-workspace-diff");
+    expect(packageNames).toContain("@paperclipai/plugin-llm-wiki");
+    expect(packageNames).toContain("@paperclipai/plugin-modal");
+    expect(packageNames).toContain("@paperclipai/plugin-authoring-smoke-example");
+    expect(packageNames).not.toContain("@paperclipai/plugin-sdk");
+    expect(byPackageName.get("@paperclipai/plugin-workspace-diff")?.experimental).toBe(true);
+    expect(byPackageName.get("@paperclipai/plugin-llm-wiki")?.experimental).toBe(true);
+    expect(byPackageName.get("@paperclipai/plugin-modal")?.experimental).toBe(true);
+    expect(byPackageName.get("@paperclipai/plugin-authoring-smoke-example")?.experimental).toBe(false);
+  }, 20_000);
+
   it("rejects plugin installation for non-admin board users", async () => {
     const { app, loader } = await createApp({
       type: "board",

server/src/__tests__/skills-catalog-service.test.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { CatalogSkill } from "@paperclipai/shared";
+
+const mockExistsSync = vi.hoisted(() => vi.fn());
+const mockReadFileSync = vi.hoisted(() => vi.fn());
+const mockStatSync = vi.hoisted(() => vi.fn());
+const mockReadFile = vi.hoisted(() => vi.fn());
+
+vi.doMock("node:fs", async () => {
+  const actual = await vi.importActual<typeof import("node:fs")>("node:fs");
+  return {
+    ...actual,
+    existsSync: mockExistsSync,
+    readFileSync: mockReadFileSync,
+    statSync: mockStatSync,
+    promises: {
+      ...actual.promises,
+      readFile: mockReadFile,
+    },
+  };
+});
+
+function catalogSkill(slug: string, name = slug): CatalogSkill {
+  return {
+    id: `paperclipai:bundled:software-development:${slug}`,
+    key: `paperclipai/bundled/software-development/${slug}`,
+    kind: "bundled",
+    category: "software-development",
+    slug,
+    name,
+    description: `${name} catalog skill used by the reload test.`,
+    path: `catalog/bundled/software-development/${slug}`,
+    entrypoint: "SKILL.md",
+    trustLevel: "markdown_only",
+    compatibility: "compatible",
+    defaultInstall: false,
+    recommendedForRoles: ["engineer"],
+    requires: [],
+    tags: ["test"],
+    files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: `sha256:${slug}` }],
+    contentHash: `sha256:${slug}`,
+  };
+}
+
+function manifest(skills: CatalogSkill[], packageVersion = "0.3.1") {
+  return JSON.stringify({
+    schemaVersion: 1,
+    packageName: "@paperclipai/skills-catalog",
+    packageVersion,
+    generatedAt: "2026-05-28T00:00:00.000Z",
+    skills,
+  });
+}
+
+describe("skills catalog service", () => {
+  let manifestJson: string;
+  let manifestMtimeMs: number;
+
+  beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    manifestJson = manifest([catalogSkill("old-skill", "Old Skill")]);
+    manifestMtimeMs = 1;
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockImplementation(() => manifestJson);
+    mockStatSync.mockImplementation(() => ({
+      mtimeMs: manifestMtimeMs,
+      size: Buffer.byteLength(manifestJson),
+    }));
+    mockReadFile.mockImplementation(async (filePath: string) => `content:${filePath}`);
+  });
+
+  it("caches and reloads the generated catalog manifest when it changes", async () => {
+    const service = await import("../services/skills-catalog.js");
+
+    expect(service.listCatalogSkills().map((skill) => skill.key)).toEqual([
+      "paperclipai/bundled/software-development/old-skill",
+    ]);
+    expect(service.listCatalogSkills().map((skill) => skill.key)).toEqual([
+      "paperclipai/bundled/software-development/old-skill",
+    ]);
+    expect(mockReadFileSync).toHaveBeenCalledTimes(1);
+
+    manifestJson = manifest([catalogSkill("new-skill", "New Skill")], "0.3.2");
+    manifestMtimeMs += 1;
+
+    expect(service.listCatalogSkills().map((skill) => skill.key)).toEqual([
+      "paperclipai/bundled/software-development/new-skill",
+    ]);
+    expect(mockReadFileSync).toHaveBeenCalledTimes(2);
+    expect(() => service.getCatalogSkillOrThrow("old-skill")).toThrow("Catalog skill not found");
+    expect(service.getCatalogPackageMetadata()).toEqual({
+      packageName: "@paperclipai/skills-catalog",
+      packageVersion: "0.3.2",
+    });
+  });
+
+  it("rejects catalog asset previews without decoding bytes as utf8", async () => {
+    const imageSkill = catalogSkill("with-image", "With Image");
+    imageSkill.files = [
+      ...imageSkill.files,
+      { path: "assets/logo.png", kind: "asset", sizeBytes: 4, sha256: "sha256:logo" },
+    ];
+    manifestJson = manifest([imageSkill]);
+    const service = await import("../services/skills-catalog.js");
+
+    await expect(service.readCatalogSkillFile(imageSkill.id, "assets/logo.png")).rejects.toMatchObject({
+      status: 415,
+      message: "Catalog asset previews are not supported.",
+    });
+    expect(mockReadFile).not.toHaveBeenCalled();
+  });
+});

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

@@ -62,6 +62,10 @@ async function runGit(cwd: string, args: string[]) {
   await execFileAsync("git", args, { cwd });
 }
 
+async function readGit(cwd: string, args: string[]) {
+  return (await execFileAsync("git", args, { cwd })).stdout.trim();
+}
+
 async function runPnpm(cwd: string, args: string[]) {
   await execFileAsync("pnpm", args, { cwd });
 }
@@ -304,6 +308,57 @@ describe("ensureServerWorkspaceLinksCurrent", () => {
 });
 
 describe("realizeExecutionWorkspace", () => {
+  it("defaults new git worktrees to freshly fetched origin/master", async () => {
+    const sourceRepo = await createTempRepo("master");
+    const remoteDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-remote-"));
+    const remotePath = path.join(remoteDir, "paperclip.git");
+    await execFileAsync("git", ["clone", "--bare", sourceRepo, remotePath]);
+
+    const cloneRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-clone-"));
+    const repoRoot = path.join(cloneRoot, "paperclip");
+    await execFileAsync("git", ["clone", remotePath, repoRoot]);
+    await runGit(repoRoot, ["config", "user.email", "paperclip@example.com"]);
+    await runGit(repoRoot, ["config", "user.name", "Paperclip Test"]);
+
+    await fs.writeFile(path.join(sourceRepo, "auth-fix.txt"), "cookie fix\n", "utf8");
+    await runGit(sourceRepo, ["add", "auth-fix.txt"]);
+    await runGit(sourceRepo, ["commit", "-m", "Add auth fix"]);
+    await runGit(sourceRepo, ["push", remotePath, "master"]);
+    const expectedRemoteHead = await readGit(sourceRepo, ["rev-parse", "master"]);
+    expect(await readGit(repoRoot, ["rev-parse", "origin/master"])).not.toBe(expectedRemoteHead);
+
+    const workspace = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: null,
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Add Worktree Support",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(workspace.baseRefSha).toBe(expectedRemoteHead);
+    expect(await readGit(repoRoot, ["rev-parse", "origin/master"])).toBe(expectedRemoteHead);
+    expect(await readGit(workspace.cwd, ["rev-parse", "HEAD"])).toBe(expectedRemoteHead);
+  });
+
   it("creates and reuses a git worktree for an issue-scoped branch", async () => {
     const repoRoot = await createTempRepo();
 
@@ -372,6 +427,75 @@ describe("realizeExecutionWorkspace", () => {
     expect(second.branchName).toBe(first.branchName);
   });
 
+  it("warns when reusing a git worktree whose base ref has advanced", async () => {
+    const repoRoot = await createTempRepo();
+
+    const initial = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "main",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Add Worktree Support",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+    expect(initial.baseRefSha).toMatch(/^[0-9a-f]{40}$/);
+
+    await fs.writeFile(path.join(repoRoot, "server-auth-fix.txt"), "cookie fix\n", "utf8");
+    await runGit(repoRoot, ["add", "server-auth-fix.txt"]);
+    await runGit(repoRoot, ["commit", "-m", "Add auth runtime fix"]);
+
+    const reused = await realizeExecutionWorkspace({
+      base: {
+        baseCwd: repoRoot,
+        source: "project_primary",
+        projectId: "project-1",
+        workspaceId: "workspace-1",
+        repoUrl: null,
+        repoRef: "main",
+      },
+      config: {
+        workspaceStrategy: {
+          type: "git_worktree",
+          branchTemplate: "{{issue.identifier}}-{{slug}}",
+        },
+      },
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-447",
+        title: "Add Worktree Support",
+      },
+      agent: {
+        id: "agent-1",
+        name: "Codex Coder",
+        companyId: "company-1",
+      },
+    });
+
+    expect(reused.created).toBe(false);
+    expect(reused.cwd).toBe(initial.cwd);
+    expect(reused.warnings).toEqual([
+      expect.stringContaining("is behind main by 1 commit"),
+    ]);
+  });
+
   it("rejects reusing an empty directory that only looks like a worktree because it sits inside the repo", async () => {
     const repoRoot = await createTempRepo();
     const branchName = "PAP-447-add-worktree-support";
@@ -1773,7 +1897,7 @@ describe("realizeExecutionWorkspace", () => {
       config: {
         workspaceStrategy: {
           type: "git_worktree",
-          // No baseRef configured — should auto-detect "master"
+          // No baseRef configured — should default to origin/master.
         },
       },
       issue: {
@@ -1791,25 +1915,23 @@ describe("realizeExecutionWorkspace", () => {
 
     expect(workspace.strategy).toBe("git_worktree");
     expect(workspace.created).toBe(true);
-    // The worktree should have been created successfully (baseRef resolved to "master")
+    // The worktree should have been created successfully from the canonical remote base.
     const worktreeOp = operations.find(op => op.phase === "worktree_prepare" && op.metadata?.created);
     expect(worktreeOp).toBeDefined();
-    expect(worktreeOp!.metadata!.baseRef).toBe("master");
+    expect(worktreeOp!.metadata!.baseRef).toBe("origin/master");
   }, 10_000);
 
   it("auto-detects the default branch via symbolic-ref when origin/HEAD is set", async () => {
-    // Create a repo with "master" as default branch
-    const repoRoot = await createTempRepo("master");
+    const repoRoot = await createTempRepo("main");
 
-    // Set up a bare remote and push
     const bareRemote = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-bare-symref-"));
     await runGit(bareRemote, ["init", "--bare"]);
     await runGit(repoRoot, ["remote", "add", "origin", bareRemote]);
-    await runGit(repoRoot, ["push", "-u", "origin", "master"]);
+    await runGit(repoRoot, ["push", "-u", "origin", "main", "master"]);
     await runGit(repoRoot, ["fetch", "origin"]);
     // Explicitly set refs/remotes/origin/HEAD to exercise the symbolic-ref path
     // (git remote set-head -a requires the remote to advertise HEAD, so we set it manually)
-    await runGit(repoRoot, ["remote", "set-head", "origin", "master"]);
+    await runGit(repoRoot, ["remote", "set-head", "origin", "main"]);
 
     const { recorder, operations } = createWorkspaceOperationRecorderDouble();
 
@@ -1825,7 +1947,7 @@ describe("realizeExecutionWorkspace", () => {
       config: {
         workspaceStrategy: {
           type: "git_worktree",
-          // No baseRef configured — should auto-detect "master" via symbolic-ref
+          // No baseRef configured — origin/master is preferred over the symbolic-ref.
         },
       },
       issue: {
@@ -1845,7 +1967,7 @@ describe("realizeExecutionWorkspace", () => {
     expect(workspace.created).toBe(true);
     const worktreeOp = operations.find(op => op.phase === "worktree_prepare" && op.metadata?.created);
     expect(worktreeOp).toBeDefined();
-    expect(worktreeOp!.metadata!.baseRef).toBe("master");
+    expect(worktreeOp!.metadata!.baseRef).toBe("origin/master");
   }, 10_000);
 
   it("removes a created git worktree and branch during cleanup", async () => {

server/src/adapters/registry.ts

@@ -25,6 +25,7 @@ import {
   listClaudeSkills,
   syncClaudeSkills,
   listClaudeModels,
+  refreshClaudeModels,
   testEnvironment as claudeTestEnvironment,
   sessionCodec as claudeSessionCodec,
   getQuotaWindows as claudeGetQuotaWindows,
@@ -255,6 +256,7 @@ const claudeLocalAdapter: ServerAdapterModule = {
   models: claudeModels,
   modelProfiles: claudeModelProfiles,
   listModels: listClaudeModels,
+  refreshModels: refreshClaudeModels,
   supportsLocalAgentJwt: true,
   supportsInstructionsBundle: true,
   instructionsPathKey: "instructionsFilePath",

server/src/first-admin-claim.ts

@@ -0,0 +1,55 @@
+import { eq, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { instanceUserRoles } from "@paperclipai/db";
+
+type FirstAdminTransaction = Pick<Db, "execute" | "select" | "insert" | "update">;
+
+export type FirstAdminClaimResult<T = unknown> =
+  | {
+      status: "claimed";
+      userId: string;
+      value: T | null;
+    }
+  | {
+      status: "already_claimed";
+      existingUserId: string | null;
+      value: null;
+    };
+
+export async function claimFirstInstanceAdmin<T = unknown>(
+  db: Db,
+  input: {
+    userId: string;
+    onClaim?: (tx: FirstAdminTransaction) => Promise<T>;
+  },
+): Promise<FirstAdminClaimResult<T>> {
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`lock table ${instanceUserRoles} in share row exclusive mode`);
+
+    const existingAdmin = await tx
+      .select({ userId: instanceUserRoles.userId })
+      .from(instanceUserRoles)
+      .where(eq(instanceUserRoles.role, "instance_admin"))
+      .then((rows) => rows[0] ?? null);
+
+    if (existingAdmin) {
+      return {
+        status: "already_claimed" as const,
+        existingUserId: existingAdmin.userId ?? null,
+        value: null,
+      };
+    }
+
+    await tx.insert(instanceUserRoles).values({
+      userId: input.userId,
+      role: "instance_admin",
+    });
+
+    const value = input.onClaim ? await input.onClaim(tx) : null;
+    return {
+      status: "claimed" as const,
+      userId: input.userId,
+      value,
+    };
+  });
+}

server/src/routes/access.ts

@@ -79,6 +79,7 @@ import {
   claimBoardOwnership,
   inspectBoardClaimChallenge
 } from "../board-claim.js";
+import { claimFirstInstanceAdmin } from "../first-admin-claim.js";
 import { getStorageService } from "../storage/index.js";
 
 function hashToken(token: string) {
@@ -2453,6 +2454,31 @@ export function accessRoutes(
     throw conflict("Board claim challenge is no longer available");
   });
 
+  router.post("/bootstrap/claim", async (req, res) => {
+    if (
+      opts.deploymentMode !== "authenticated" ||
+      opts.deploymentExposure !== "private"
+    ) {
+      throw notFound("Browser first-admin claim is not available");
+    }
+    if (
+      req.actor.type !== "board" ||
+      req.actor.source !== "session" ||
+      !req.actor.userId
+    ) {
+      throw unauthorized("Sign in from a browser session before claiming first admin");
+    }
+
+    const claimed = await claimFirstInstanceAdmin(db, {
+      userId: req.actor.userId,
+    });
+    if (claimed.status === "already_claimed") {
+      throw conflict("Someone else has already claimed this instance");
+    }
+
+    res.json({ claimed: true, userId: claimed.userId });
+  });
+
   router.post(
     "/cli-auth/challenges",
     validate(createCliAuthChallengeSchema),
@@ -3276,16 +3302,31 @@ export function accessRoutes(
           );
         }
         const userId = req.actor.userId ?? "local-board";
-        const existingAdmin = await access.isInstanceAdmin(userId);
-        if (!existingAdmin) {
-          await access.promoteInstanceAdmin(userId);
+        const claimed = await claimFirstInstanceAdmin(db, {
+          userId,
+          onClaim: async (tx) => {
+            const updatedInvite = await tx
+              .update(invites)
+              .set({ acceptedAt: new Date(), updatedAt: new Date() })
+              .where(
+                and(
+                  eq(invites.id, invite.id),
+                  isNull(invites.acceptedAt),
+                  isNull(invites.revokedAt)
+                )
+              )
+              .returning()
+              .then((rows) => rows[0] ?? null);
+            if (!updatedInvite) {
+              throw conflict("Bootstrap invite is no longer available");
+            }
+            return updatedInvite;
+          },
+        });
+        if (claimed.status === "already_claimed") {
+          throw conflict("Someone else has already claimed this instance");
         }
-        const updatedInvite = await db
-          .update(invites)
-          .set({ acceptedAt: new Date(), updatedAt: new Date() })
-          .where(eq(invites.id, invite.id))
-          .returning()
-          .then((rows) => rows[0] ?? invite);
+        const updatedInvite = claimed.value ?? invite;
         res.status(202).json({
           inviteId: updatedInvite.id,
           inviteType: updatedInvite.inviteType,

server/src/routes/execution-workspaces.ts

@@ -250,6 +250,7 @@ export function executionWorkspaceRoutes(db: Db) {
               repoUrl: existing.repoUrl,
               baseRef: existing.baseRef,
               branchName: existing.branchName,
+              metadata: existing.metadata as Record<string, unknown> | null,
               config: {
                 ...existing.config,
                 provisionCommand:

server/src/routes/health.ts

@@ -157,6 +157,7 @@ export function healthRoutes(
       res.json({
         status: "ok",
         deploymentMode: opts.deploymentMode,
+        deploymentExposure: opts.deploymentExposure,
         bootstrapStatus,
         bootstrapInviteActive,
         ...(devServer ? { devServer } : {}),

server/src/routes/issues.ts

@@ -22,7 +22,10 @@ import {
   createIssueThreadInteractionSchema,
   createIssueWorkProductSchema,
   createIssueLabelSchema,
+  createAcceptedPlanDecompositionSchema,
   checkoutIssueSchema,
+  createDocumentAnnotationCommentSchema,
+  createDocumentAnnotationThreadSchema,
   createChildIssueSchema,
   createIssueSchema,
   resolveCreateIssueStatusDefault,
@@ -38,6 +41,7 @@ import {
   restoreIssueDocumentRevisionSchema,
   respondIssueThreadInteractionSchema,
   updateIssueWorkProductSchema,
+  updateDocumentAnnotationThreadSchema,
   upsertIssueDocumentSchema,
   updateIssueSchema,
   getClosedIsolatedExecutionWorkspaceMessage,
@@ -71,6 +75,7 @@ import {
   issueService,
   clampIssueListLimit,
   documentService,
+  documentAnnotationService,
   logActivity,
   projectService,
   routineService,
@@ -95,6 +100,7 @@ import { assertEnvironmentSelectionForCompany } from "./environment-selection.js
 import { executionWorkspaceService as executionWorkspaceServiceDirect } from "../services/execution-workspaces.js";
 import { feedbackService } from "../services/feedback.js";
 import { instanceSettingsService } from "../services/instance-settings.js";
+import { readAcceptedPlanConfirmationTarget } from "../services/issues.js";
 import { environmentService } from "../services/environments.js";
 import { redactSensitiveText } from "../redaction.js";
 import {
@@ -868,6 +874,7 @@ export function issueRoutes(
   const executionWorkspacesSvc = executionWorkspaceServiceDirect(db);
   const workProductsSvc = workProductService(db);
   const documentsSvc = documentService(db);
+  const documentAnnotationsSvc = documentAnnotationService(db);
   const issueReferencesSvc = issueReferenceService(db);
   const issueThreadInteractionsSvc = issueThreadInteractionService(db);
   const routinesSvc = routineService(db, {
@@ -1106,6 +1113,69 @@ export function issueRoutes(
     return value === true || value === "true" || value === "1";
   }
 
+  function shouldIncludeDocumentAnnotations(req: Request) {
+    if (req.query.includeAnnotations === "false" || req.query.includeAnnotations === "0") return false;
+    return req.actor.type === "agent" || parseBooleanQuery(req.query.includeAnnotations);
+  }
+
+  function shouldIncludeDocumentAnnotationComments(req: Request) {
+    return parseBooleanQuery(req.query.includeAnnotationComments);
+  }
+
+  function annotationActorInput(req: Request) {
+    const actor = getActorInfo(req);
+    return {
+      actor,
+      annotationActor: {
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        userId: actor.actorType === "user" ? actor.actorId : null,
+        runId: actor.runId,
+      },
+    };
+  }
+
+  function queueAnnotationCommentWakeup(input: {
+    issue: { id: string; assigneeAgentId: string | null; status: string };
+    actor: { actorType: "user" | "agent"; actorId: string };
+    threadId: string;
+    commentId: string;
+    documentKey: string;
+  }) {
+    const assigneeId = input.issue.assigneeAgentId;
+    const selfComment = input.actor.actorType === "agent" && input.actor.actorId === assigneeId;
+    if (!assigneeId || selfComment || isClosedIssueStatus(input.issue.status)) return;
+    void heartbeat.wakeup(assigneeId, {
+      source: "automation",
+      triggerDetail: "system",
+      reason: "issue_commented",
+      payload: {
+        issueId: input.issue.id,
+        annotationThreadId: input.threadId,
+        annotationCommentId: input.commentId,
+        documentKey: input.documentKey,
+        mutation: "document_annotation_comment",
+      },
+      requestedByActorType: input.actor.actorType,
+      requestedByActorId: input.actor.actorId,
+      contextSnapshot: {
+        issueId: input.issue.id,
+        taskId: input.issue.id,
+        annotationThreadId: input.threadId,
+        annotationCommentId: input.commentId,
+        documentKey: input.documentKey,
+        source: "issue.document.annotation",
+        wakeReason: "issue_commented",
+      },
+    }).catch((err) => logger.warn({
+      err,
+      issueId: input.issue.id,
+      annotationThreadId: input.threadId,
+      annotationCommentId: input.commentId,
+    }, "failed to wake assignee on document annotation comment"));
+  }
+
   async function assertIssueEnvironmentSelection(
     companyId: string,
     environmentId: string | null | undefined,
@@ -2448,9 +2518,239 @@ export function issueRoutes(
       res.status(404).json({ error: "Document not found" });
       return;
     }
-    res.json(doc);
+    if (!shouldIncludeDocumentAnnotations(req)) {
+      res.json(doc);
+      return;
+    }
+    const annotations = await documentAnnotationsSvc.listThreadsForIssueDocument(issue.id, keyParsed.data, {
+      status: "open",
+      includeComments: shouldIncludeDocumentAnnotationComments(req),
+    });
+    res.json({ ...doc, annotations });
   });
 
+  router.get("/issues/:id/documents/:key/annotations", 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);
+    const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
+    if (!keyParsed.success) {
+      res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
+      return;
+    }
+    const status = req.query.status === "resolved" || req.query.status === "all" ? req.query.status : "open";
+    const threads = await documentAnnotationsSvc.listThreadsForIssueDocument(issue.id, keyParsed.data, {
+      status,
+      includeComments: parseBooleanQuery(req.query.includeComments),
+    });
+    res.json(threads);
+  });
+
+  router.post(
+    "/issues/:id/documents/:key/annotations",
+    validate(createDocumentAnnotationThreadSchema),
+    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 (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
+      const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
+      if (!keyParsed.success) {
+        res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
+        return;
+      }
+
+      const { actor, annotationActor } = annotationActorInput(req);
+      const referenceSummaryBefore = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
+      const thread = await documentAnnotationsSvc.createThread(issue.id, keyParsed.data, req.body, annotationActor);
+      const firstComment = thread.comments[0];
+      if (firstComment) await issueReferencesSvc.syncAnnotationComment(firstComment.id);
+      const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
+      const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
+
+      await logActivity(db, {
+        companyId: issue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "issue.document_annotation_thread_created",
+        entityType: "issue",
+        entityId: issue.id,
+        details: {
+          documentKey: thread.documentKey,
+          documentId: thread.documentId,
+          threadId: thread.id,
+          commentId: firstComment?.id ?? null,
+          revisionNumber: thread.currentRevisionNumber,
+          quote: thread.selectedText.slice(0, 240),
+          ...summarizeIssueReferenceActivityDetails({
+            addedReferencedIssues: referenceDiff.addedReferencedIssues.map(summarizeIssueRelationForActivity),
+            removedReferencedIssues: referenceDiff.removedReferencedIssues.map(summarizeIssueRelationForActivity),
+            currentReferencedIssues: referenceDiff.currentReferencedIssues.map(summarizeIssueRelationForActivity),
+          }),
+        },
+      });
+
+      if (firstComment) {
+        queueAnnotationCommentWakeup({
+          issue,
+          actor,
+          threadId: thread.id,
+          commentId: firstComment.id,
+          documentKey: thread.documentKey,
+        });
+      }
+
+      res.status(201).json(thread);
+    },
+  );
+
+  router.get("/issues/:id/documents/:key/annotations/:threadId", 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);
+    const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
+    if (!keyParsed.success) {
+      res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
+      return;
+    }
+    const thread = await documentAnnotationsSvc.getThreadForIssueDocument(
+      issue.id,
+      keyParsed.data,
+      req.params.threadId as string,
+    );
+    if (!thread) {
+      res.status(404).json({ error: "Annotation thread not found" });
+      return;
+    }
+    res.json(thread);
+  });
+
+  router.post(
+    "/issues/:id/documents/:key/annotations/:threadId/comments",
+    validate(createDocumentAnnotationCommentSchema),
+    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 (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
+      const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
+      if (!keyParsed.success) {
+        res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
+        return;
+      }
+
+      const { actor, annotationActor } = annotationActorInput(req);
+      const referenceSummaryBefore = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
+      const comment = await documentAnnotationsSvc.addComment(
+        issue.id,
+        keyParsed.data,
+        req.params.threadId as string,
+        req.body,
+        annotationActor,
+      );
+      await issueReferencesSvc.syncAnnotationComment(comment.id);
+      const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
+      const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
+
+      await logActivity(db, {
+        companyId: issue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "issue.document_annotation_comment_added",
+        entityType: "issue",
+        entityId: issue.id,
+        details: {
+          documentKey: keyParsed.data,
+          threadId: comment.threadId,
+          commentId: comment.id,
+          bodySnippet: comment.body.slice(0, 120),
+          ...summarizeIssueReferenceActivityDetails({
+            addedReferencedIssues: referenceDiff.addedReferencedIssues.map(summarizeIssueRelationForActivity),
+            removedReferencedIssues: referenceDiff.removedReferencedIssues.map(summarizeIssueRelationForActivity),
+            currentReferencedIssues: referenceDiff.currentReferencedIssues.map(summarizeIssueRelationForActivity),
+          }),
+        },
+      });
+
+      queueAnnotationCommentWakeup({
+        issue,
+        actor,
+        threadId: comment.threadId,
+        commentId: comment.id,
+        documentKey: keyParsed.data,
+      });
+
+      res.status(201).json(comment);
+    },
+  );
+
+  router.patch(
+    "/issues/:id/documents/:key/annotations/:threadId",
+    validate(updateDocumentAnnotationThreadSchema),
+    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 (!(await assertAgentIssueMutationAllowed(req, res, issue))) return;
+      const keyParsed = issueDocumentKeySchema.safeParse(String(req.params.key ?? "").trim().toLowerCase());
+      if (!keyParsed.success) {
+        res.status(400).json({ error: "Invalid document key", details: keyParsed.error.issues });
+        return;
+      }
+      const { actor, annotationActor } = annotationActorInput(req);
+      const thread = await documentAnnotationsSvc.updateThread(
+        issue.id,
+        keyParsed.data,
+        req.params.threadId as string,
+        req.body,
+        annotationActor,
+      );
+      await logActivity(db, {
+        companyId: issue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: thread.status === "resolved"
+          ? "issue.document_annotation_thread_resolved"
+          : "issue.document_annotation_thread_reopened",
+        entityType: "issue",
+        entityId: issue.id,
+        details: {
+          documentKey: thread.documentKey,
+          documentId: thread.documentId,
+          threadId: thread.id,
+          status: thread.status,
+        },
+      });
+      res.json(thread);
+    },
+  );
+
   router.put("/issues/:id/documents/:key", validate(upsertIssueDocumentSchema), async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);
@@ -2488,6 +2788,16 @@ export function issueRoutes(
     await issueReferencesSvc.syncDocument(doc.id);
     const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
     const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
+    const remappedAnnotations = result.created
+      ? []
+      : await documentAnnotationsSvc.remapOpenThreadsForDocument({
+        issueId: issue.id,
+        key: doc.key,
+        documentId: doc.id,
+        nextRevisionId: doc.latestRevisionId,
+        nextRevisionNumber: doc.latestRevisionNumber,
+        nextBody: doc.body,
+      });
 
     await logActivity(db, {
       companyId: issue.companyId,
@@ -2513,6 +2823,28 @@ export function issueRoutes(
       },
     });
 
+    for (const remap of remappedAnnotations) {
+      await logActivity(db, {
+        companyId: issue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "issue.document_annotation_remapped",
+        entityType: "issue",
+        entityId: issue.id,
+        details: {
+          key: doc.key,
+          documentId: doc.id,
+          threadId: remap.thread.id,
+          revisionNumber: doc.latestRevisionNumber,
+          anchorState: remap.thread.anchorState,
+          anchorConfidence: remap.thread.anchorConfidence,
+          snapshotId: remap.snapshot.id,
+        },
+      });
+    }
+
     if (!result.created) {
       const expiredInteractions = await issueThreadInteractionService(db).expireStaleRequestConfirmationsForIssueDocument(
         issue,
@@ -2684,6 +3016,14 @@ export function issueRoutes(
       await issueReferencesSvc.syncDocument(result.document.id);
       const referenceSummaryAfter = await issueReferencesSvc.listIssueReferenceSummary(issue.id);
       const referenceDiff = issueReferencesSvc.diffIssueReferenceSummary(referenceSummaryBefore, referenceSummaryAfter);
+      const remappedAnnotations = await documentAnnotationsSvc.remapOpenThreadsForDocument({
+        issueId: issue.id,
+        key: result.document.key,
+        documentId: result.document.id,
+        nextRevisionId: result.document.latestRevisionId,
+        nextRevisionNumber: result.document.latestRevisionNumber,
+        nextBody: result.document.body,
+      });
 
       await logActivity(db, {
         companyId: issue.companyId,
@@ -2710,6 +3050,28 @@ export function issueRoutes(
         },
       });
 
+      for (const remap of remappedAnnotations) {
+        await logActivity(db, {
+          companyId: issue.companyId,
+          actorType: actor.actorType,
+          actorId: actor.actorId,
+          agentId: actor.agentId,
+          runId: actor.runId,
+          action: "issue.document_annotation_remapped",
+          entityType: "issue",
+          entityId: issue.id,
+          details: {
+            key: result.document.key,
+            documentId: result.document.id,
+            threadId: remap.thread.id,
+            revisionNumber: result.document.latestRevisionNumber,
+            anchorState: remap.thread.anchorState,
+            anchorConfidence: remap.thread.anchorConfidence,
+            snapshotId: remap.snapshot.id,
+          },
+        });
+      }
+
       const expiredInteractions = await issueThreadInteractionService(db).expireStaleRequestConfirmationsForIssueDocument(
         issue,
         {
@@ -3332,6 +3694,151 @@ export function issueRoutes(
     res.status(201).json(issue);
   });
 
+  router.get("/issues/:id/accepted-plan-decompositions", async (req, res) => {
+    const sourceIssueId = req.params.id as string;
+    const sourceIssue = await svc.getById(sourceIssueId);
+    if (!sourceIssue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, sourceIssue.companyId);
+    const decompositions = await svc.listAcceptedPlanDecompositions(sourceIssue.id);
+    res.json(decompositions);
+  });
+
+  router.post("/issues/:id/accepted-plan-decompositions", validate(createAcceptedPlanDecompositionSchema), async (req, res) => {
+    const sourceIssueId = req.params.id as string;
+    const sourceIssue = await svc.getById(sourceIssueId);
+    if (!sourceIssue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, sourceIssue.companyId);
+    if (!(await assertAgentIssueMutationAllowed(req, res, sourceIssue))) return;
+
+    for (const child of req.body.children as Array<typeof req.body.children[number]>) {
+      assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(child));
+      if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, sourceIssue, child))) return;
+      if (child.assigneeAgentId || child.assigneeUserId) {
+        await assertCanAssignTasks(req, sourceIssue.companyId, {
+          projectId: child.projectId ?? sourceIssue.projectId ?? null,
+          parentIssueId: sourceIssue.id,
+          assigneeAgentId: child.assigneeAgentId ?? null,
+          assigneeUserId: child.assigneeUserId ?? null,
+        });
+      }
+      await assertIssueEnvironmentSelection(sourceIssue.companyId, child.executionWorkspaceSettings?.environmentId);
+    }
+
+    const actor = getActorInfo(req);
+    const normalizedChildren = req.body.children.map((child: typeof req.body.children[number]) => {
+      const executionPolicy = applyActorMonitorScheduledBy(
+        normalizeIssueExecutionPolicy(child.executionPolicy),
+        actor.actorType,
+      );
+      assertCanManageIssueMonitor(req, child.assigneeAgentId ?? null, Boolean(executionPolicy?.monitor));
+      return {
+        ...child,
+        executionPolicy,
+        createdByAgentId: actor.agentId,
+        createdByUserId: actor.actorType === "user" ? actor.actorId : null,
+        actorAgentId: actor.agentId,
+        actorUserId: actor.actorType === "user" ? actor.actorId : null,
+      };
+    });
+
+    const result = await svc.decomposeAcceptedPlan(sourceIssue.id, {
+      acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+      children: normalizedChildren,
+      actorAgentId: actor.agentId,
+      actorUserId: actor.actorType === "user" ? actor.actorId : null,
+      actorRunId: actor.runId ?? null,
+    });
+
+    await logActivity(db, {
+      companyId: sourceIssue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.accepted_plan_decomposition_updated",
+      entityType: "issue",
+      entityId: sourceIssue.id,
+      details: {
+        identifier: sourceIssue.identifier,
+        acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+        decompositionId: result.decomposition.id,
+        status: result.decomposition.status,
+        requestedChildCount: req.body.children.length,
+        childIssueIds: result.childIssueIds,
+        newlyCreatedChildIssueIds: result.newlyCreatedIssues.map((issue) => issue.id),
+      },
+    });
+
+    for (const issue of result.newlyCreatedIssues) {
+      await logActivity(db, {
+        companyId: sourceIssue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "issue.child_created",
+        entityType: "issue",
+        entityId: issue.id,
+        details: {
+          parentId: sourceIssue.id,
+          identifier: issue.identifier,
+          title: issue.title,
+          inheritedExecutionWorkspaceFromIssueId: sourceIssue.id,
+          acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+          ...buildCreateIssueActivityStatusDetails(issue, res),
+        },
+      });
+
+      const executionPolicy = normalizeIssueExecutionPolicy(issue.executionPolicy);
+      if (executionPolicy?.monitor) {
+        await logActivity(db, {
+          companyId: sourceIssue.companyId,
+          actorType: actor.actorType,
+          actorId: actor.actorId,
+          agentId: actor.agentId,
+          runId: actor.runId,
+          action: "issue.monitor_scheduled",
+          entityType: "issue",
+          entityId: issue.id,
+          details: {
+            identifier: issue.identifier,
+            parentId: sourceIssue.id,
+            acceptedPlanRevisionId: req.body.acceptedPlanRevisionId,
+            nextCheckAt: executionPolicy.monitor.nextCheckAt,
+            notes: executionPolicy.monitor.notes,
+            scheduledBy: executionPolicy.monitor.scheduledBy,
+            serviceName: executionPolicy.monitor.serviceName ?? null,
+            timeoutAt: executionPolicy.monitor.timeoutAt ?? null,
+            maxAttempts: executionPolicy.monitor.maxAttempts ?? null,
+            recoveryPolicy: executionPolicy.monitor.recoveryPolicy ?? null,
+          },
+        });
+      }
+
+      void queueIssueAssignmentWakeup({
+        heartbeat,
+        issue,
+        reason: "issue_assigned",
+        mutation: "accepted_plan_decomposition",
+        contextSource: "issue.accepted_plan_decomposition",
+        requestedByActorType: actor.actorType,
+        requestedByActorId: actor.actorId,
+      });
+    }
+
+    res.json({
+      decomposition: result.decomposition,
+      childIssueIds: result.childIssueIds,
+      newlyCreatedChildIssueIds: result.newlyCreatedIssues.map((issue) => issue.id),
+    });
+  });
+
   router.post("/issues/:id/monitor/check-now", async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);
@@ -4758,10 +5265,12 @@ export function issueRoutes(
         });
       }
 
+      const acceptedPlanTarget = readAcceptedPlanConfirmationTarget(interaction.payload);
       const acceptedPlanConfirmation =
         interaction.kind === "request_confirmation" &&
         interaction.status === "accepted" &&
-        issue.workMode === "planning";
+        acceptedPlanTarget?.issueId === issue.id &&
+        acceptedPlanTarget.key === "plan";
       queueResolvedInteractionContinuationWakeup({
         heartbeat,
         issue: continuationWakeIssue,

server/src/routes/plugins.ts

@@ -18,7 +18,7 @@
  * @see doc/plugins/PLUGIN_SPEC.md for the full plugin specification
  */
 
-import { existsSync } from "node:fs";
+import { access, readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -114,13 +114,14 @@ interface PluginInstallRequest {
   isLocalPath?: boolean;
 }
 
-interface AvailablePluginExample {
+interface AvailableBundledPlugin {
   packageName: string;
   pluginKey: string;
   displayName: string;
   description: string;
   localPath: string;
   tag: "example" | "first-party";
+  experimental: boolean;
 }
 
 /** Response body for GET /api/plugins/:pluginId/health */
@@ -150,58 +151,166 @@ const PLUGIN_SCOPED_API_RESPONSE_HEADER_ALLOWLIST = new Set([
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, "../../..");
+const EXPERIMENTAL_BUNDLED_PLUGIN_PACKAGE_NAMES = new Set([
+  "@paperclipai/plugin-llm-wiki",
+  "@paperclipai/plugin-modal",
+  "@paperclipai/plugin-workspace-diff",
+]);
+let bundledPluginsCache: Promise<AvailableBundledPlugin[]> | null = null;
 
-const BUNDLED_PLUGIN_EXAMPLES: AvailablePluginExample[] = [
-  {
-    packageName: "@paperclipai/plugin-workspace-diff",
-    pluginKey: "paperclip.workspace-diff",
-    displayName: "Workspace Changes",
-    description: "First-party workspace Changes tab backed by plugin-local Git diff computation.",
-    localPath: "packages/plugins/plugin-workspace-diff",
-    tag: "first-party",
-  },
-  {
-    packageName: "@paperclipai/plugin-hello-world-example",
-    pluginKey: "paperclip.hello-world-example",
-    displayName: "Hello World Widget (Example)",
-    description: "Reference UI plugin that adds a simple Hello World widget to the Paperclip dashboard.",
-    localPath: "packages/plugins/examples/plugin-hello-world-example",
-    tag: "example",
-  },
-  {
-    packageName: "@paperclipai/plugin-file-browser-example",
-    pluginKey: "paperclip-file-browser-example",
-    displayName: "File Browser (Example)",
-    description: "Example plugin that adds a Files link in project navigation plus a project detail file browser.",
-    localPath: "packages/plugins/examples/plugin-file-browser-example",
-    tag: "example",
-  },
-  {
-    packageName: "@paperclipai/plugin-kitchen-sink-example",
-    pluginKey: "paperclip-kitchen-sink-example",
-    displayName: "Kitchen Sink (Example)",
-    description: "Reference plugin that demonstrates the current Paperclip plugin API surface, bridge flows, UI extension surfaces, jobs, webhooks, tools, streams, and trusted local workspace/process demos.",
-    localPath: "packages/plugins/examples/plugin-kitchen-sink-example",
-    tag: "example",
-  },
-  {
-    packageName: "@paperclipai/plugin-orchestration-smoke-example",
-    pluginKey: "paperclipai.plugin-orchestration-smoke-example",
-    displayName: "Orchestration Smoke (Example)",
-    description: "Acceptance fixture for scoped plugin routes, restricted database namespaces, issue orchestration, documents, wakeups, summaries, and UI status surfaces.",
-    localPath: "packages/plugins/examples/plugin-orchestration-smoke-example",
-    tag: "example",
-  },
-];
+function titleCasePluginName(packageName: string): string {
+  const localName = packageName.split("/").pop() ?? packageName;
+  return localName
+    .replace(/^paperclip-plugin-/, "")
+    .replace(/^plugin-/, "")
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
 
-function listBundledPluginExamples(): AvailablePluginExample[] {
-  return BUNDLED_PLUGIN_EXAMPLES.flatMap((plugin) => {
-    const absoluteLocalPath = path.resolve(REPO_ROOT, plugin.localPath);
-    if (!existsSync(absoluteLocalPath)) return [];
-    return [{ ...plugin, localPath: absoluteLocalPath }];
+async function fileExists(filePath: string): Promise<boolean> {
+  return access(filePath).then(() => true, () => false);
+}
+
+async function readJsonFile(filePath: string): Promise<Record<string, unknown> | null> {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8")) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+async function findPackageJsonFiles(root: string, maxDepth = 4): Promise<string[]> {
+  if (!(await fileExists(root))) return [];
+
+  const packageJsonFiles: string[] = [];
+  const walk = async (dir: string, depth: number): Promise<void> => {
+    if (depth > maxDepth) return;
+
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === "dist") continue;
+      const entryPath = path.join(dir, entry.name);
+
+      if (entry.isFile() && entry.name === "package.json") {
+        packageJsonFiles.push(entryPath);
+      } else if (entry.isDirectory()) {
+        await walk(entryPath, depth + 1);
+      }
+    }
+  };
+
+  await walk(root, 0);
+  return packageJsonFiles;
+}
+
+function manifestSourcePath(packageRoot: string, pkgJson: Record<string, unknown>): string | null {
+  const paperclipPlugin = pkgJson.paperclipPlugin;
+  if (
+    !paperclipPlugin
+    || typeof paperclipPlugin !== "object"
+    || Array.isArray(paperclipPlugin)
+  ) {
+    return null;
+  }
+
+  const manifestPath = (paperclipPlugin as Record<string, unknown>).manifest;
+  if (typeof manifestPath !== "string") return null;
+
+  const sourcePath = manifestPath
+    .replace(/^\.\/dist\//, "./src/")
+    .replace(/\.js$/, ".ts");
+  return path.resolve(packageRoot, sourcePath);
+}
+
+function firstStringLiteral(source: string, key: string): string | null {
+  const match = source.match(
+    new RegExp(`${key}:\\s*(?:"([^"]*)"|'([^']*)'|\`([^\`]*)\`)`, "s"),
+  );
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+
+async function bundledPluginMetadata(
+  packageRoot: string,
+  pkgJson: Record<string, unknown>,
+): Promise<{ pluginKey?: string; displayName?: string; description?: string }> {
+  const sourcePath = manifestSourcePath(packageRoot, pkgJson);
+  if (!sourcePath || !(await fileExists(sourcePath))) return {};
+
+  try {
+    const source = await readFile(sourcePath, "utf8");
+    const pluginId = source
+      .match(/(?:export\s+)?const\s+PLUGIN_ID\s*=\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/)
+      ?.slice(1)
+      .find(Boolean)
+      ?? firstStringLiteral(source, "id")
+      ?? null;
+    return {
+      pluginKey: pluginId ?? undefined,
+      displayName: firstStringLiteral(source, "displayName") ?? undefined,
+      description: firstStringLiteral(source, "description") ?? undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function isExperimentalBundledPlugin(packageRoot: string, packageName: string): boolean {
+  return (
+    EXPERIMENTAL_BUNDLED_PLUGIN_PACKAGE_NAMES.has(packageName)
+    || packageRoot.includes(`${path.sep}sandbox-providers${path.sep}`)
+    || packageName.includes("sandbox")
+  );
+}
+
+async function discoverBundledPlugins(): Promise<AvailableBundledPlugin[]> {
+  const pluginRoot = path.resolve(REPO_ROOT, "packages/plugins");
+  const bundledPlugins: AvailableBundledPlugin[] = [];
+  for (const packageJsonPath of await findPackageJsonFiles(pluginRoot)) {
+    const packageRoot = path.dirname(packageJsonPath);
+    const pkgJson = await readJsonFile(packageJsonPath);
+    const paperclipPlugin = pkgJson?.paperclipPlugin;
+    if (
+      !pkgJson
+      || !paperclipPlugin
+      || typeof paperclipPlugin !== "object"
+      || Array.isArray(paperclipPlugin)
+    ) {
+      continue;
+    }
+
+    const packageName = pkgJson.name;
+    if (typeof packageName !== "string" || packageName.length === 0) continue;
+
+    const metadata = await bundledPluginMetadata(packageRoot, pkgJson);
+    const tag = packageRoot.includes(`${path.sep}examples${path.sep}`) ? "example" : "first-party";
+    bundledPlugins.push({
+      packageName,
+      pluginKey: metadata.pluginKey ?? packageName,
+      displayName: metadata.displayName ?? titleCasePluginName(packageName),
+      description: metadata.description
+        ?? `Bundled Paperclip plugin from ${path.relative(REPO_ROOT, packageRoot)}.`,
+      localPath: packageRoot,
+      tag,
+      experimental: isExperimentalBundledPlugin(packageRoot, packageName),
+    });
+  }
+
+  return bundledPlugins.sort((left, right) => {
+    if (left.tag !== right.tag) return left.tag === "first-party" ? -1 : 1;
+    return left.displayName.localeCompare(right.displayName);
   });
 }
 
+async function listBundledPlugins(): Promise<AvailableBundledPlugin[]> {
+  bundledPluginsCache ??= discoverBundledPlugins().catch((error: unknown) => {
+    bundledPluginsCache = null;
+    throw error;
+  });
+  return bundledPluginsCache;
+}
+
 /**
  * Resolve a plugin by either database ID or plugin key.
  *
@@ -677,12 +786,12 @@ export function pluginRoutes(
   /**
    * GET /api/plugins/examples
    *
-   * Return first-party example plugins bundled in this repo, if present.
+   * Return plugin packages bundled in this repo, if present.
    * These can be installed through the normal local-path install flow.
    */
   router.get("/plugins/examples", async (req, res) => {
     assertBoardOrgAccess(req);
-    res.json(listBundledPluginExamples());
+    res.json(await listBundledPlugins());
   });
 
   // IMPORTANT: Static routes must come before parameterized routes

server/src/services/document-annotations.ts

@@ -0,0 +1,413 @@
+import { and, asc, desc, eq, inArray, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  documentAnnotationAnchorSnapshots,
+  documentAnnotationComments,
+  documentAnnotationThreads,
+  documents,
+  issueDocuments,
+} from "@paperclipai/db";
+import {
+  anchorSnapshotToSelector,
+  remapDocumentAnchor,
+  selectorToAnchorSnapshot,
+  verifyDocumentAnchorSelector,
+  type DocumentAnnotationAnchorSnapshot,
+  type DocumentAnnotationComment,
+  type DocumentAnnotationThread,
+  CreateDocumentAnnotationComment,
+  CreateDocumentAnnotationThread,
+  UpdateDocumentAnnotationThread,
+} from "@paperclipai/shared";
+import { conflict, notFound, unprocessable } from "../errors.js";
+
+type ActorInput = {
+  actorType: "agent" | "user";
+  actorId: string;
+  agentId?: string | null;
+  userId?: string | null;
+  runId?: string | null;
+};
+
+type IssueDocumentRow = {
+  issueId: string;
+  companyId: string;
+  documentId: string;
+  documentKey: string;
+  latestBody: string;
+  latestRevisionId: string | null;
+  latestRevisionNumber: number;
+};
+
+const threadSelect = {
+  id: documentAnnotationThreads.id,
+  companyId: documentAnnotationThreads.companyId,
+  issueId: documentAnnotationThreads.issueId,
+  documentId: documentAnnotationThreads.documentId,
+  documentKey: documentAnnotationThreads.documentKey,
+  status: documentAnnotationThreads.status,
+  anchorState: documentAnnotationThreads.anchorState,
+  anchorConfidence: documentAnnotationThreads.anchorConfidence,
+  originalRevisionId: documentAnnotationThreads.originalRevisionId,
+  originalRevisionNumber: documentAnnotationThreads.originalRevisionNumber,
+  currentRevisionId: documentAnnotationThreads.currentRevisionId,
+  currentRevisionNumber: documentAnnotationThreads.currentRevisionNumber,
+  selectedText: documentAnnotationThreads.selectedText,
+  prefixText: documentAnnotationThreads.prefixText,
+  suffixText: documentAnnotationThreads.suffixText,
+  normalizedStart: documentAnnotationThreads.normalizedStart,
+  normalizedEnd: documentAnnotationThreads.normalizedEnd,
+  markdownStart: documentAnnotationThreads.markdownStart,
+  markdownEnd: documentAnnotationThreads.markdownEnd,
+  anchorSelector: documentAnnotationThreads.anchorSelector,
+  createdByAgentId: documentAnnotationThreads.createdByAgentId,
+  createdByUserId: documentAnnotationThreads.createdByUserId,
+  resolvedByAgentId: documentAnnotationThreads.resolvedByAgentId,
+  resolvedByUserId: documentAnnotationThreads.resolvedByUserId,
+  resolvedAt: documentAnnotationThreads.resolvedAt,
+  createdAt: documentAnnotationThreads.createdAt,
+  updatedAt: documentAnnotationThreads.updatedAt,
+};
+
+const commentSelect = {
+  id: documentAnnotationComments.id,
+  companyId: documentAnnotationComments.companyId,
+  threadId: documentAnnotationComments.threadId,
+  issueId: documentAnnotationComments.issueId,
+  documentId: documentAnnotationComments.documentId,
+  body: documentAnnotationComments.body,
+  authorType: documentAnnotationComments.authorType,
+  authorAgentId: documentAnnotationComments.authorAgentId,
+  authorUserId: documentAnnotationComments.authorUserId,
+  createdByRunId: documentAnnotationComments.createdByRunId,
+  createdAt: documentAnnotationComments.createdAt,
+  updatedAt: documentAnnotationComments.updatedAt,
+};
+
+function snapshotFromThread(thread: Pick<DocumentAnnotationThread, "selectedText" | "prefixText" | "suffixText" | "normalizedStart" | "normalizedEnd" | "markdownStart" | "markdownEnd">): DocumentAnnotationAnchorSnapshot {
+  return {
+    selectedText: thread.selectedText,
+    prefixText: thread.prefixText,
+    suffixText: thread.suffixText,
+    normalizedStart: thread.normalizedStart,
+    normalizedEnd: thread.normalizedEnd,
+    markdownStart: thread.markdownStart,
+    markdownEnd: thread.markdownEnd,
+  };
+}
+
+export function documentAnnotationService(db: Db) {
+  async function getIssueDocument(issueId: string, key: string, dbOrTx: any = db): Promise<IssueDocumentRow | null> {
+    return dbOrTx
+      .select({
+        issueId: issueDocuments.issueId,
+        companyId: documents.companyId,
+        documentId: documents.id,
+        documentKey: issueDocuments.key,
+        latestBody: documents.latestBody,
+        latestRevisionId: documents.latestRevisionId,
+        latestRevisionNumber: documents.latestRevisionNumber,
+      })
+      .from(issueDocuments)
+      .innerJoin(documents, eq(issueDocuments.documentId, documents.id))
+      .where(and(eq(issueDocuments.issueId, issueId), eq(issueDocuments.key, key)))
+      .then((rows: IssueDocumentRow[]) => rows[0] ?? null);
+  }
+
+  async function getThreadForIssue(
+    issueId: string,
+    documentKey: string,
+    threadId: string,
+    dbOrTx: any = db,
+  ): Promise<DocumentAnnotationThread | null> {
+    return dbOrTx
+      .select(threadSelect)
+      .from(documentAnnotationThreads)
+      .where(and(
+        eq(documentAnnotationThreads.id, threadId),
+        eq(documentAnnotationThreads.issueId, issueId),
+        eq(documentAnnotationThreads.documentKey, documentKey),
+      ))
+      .then((rows: DocumentAnnotationThread[]) => rows[0] ?? null);
+  }
+
+  async function commentsForThreads(threadIds: string[], dbOrTx: any = db): Promise<DocumentAnnotationComment[]> {
+    if (threadIds.length === 0) return [];
+    return dbOrTx
+      .select(commentSelect)
+      .from(documentAnnotationComments)
+      .where(inArray(documentAnnotationComments.threadId, threadIds))
+      .orderBy(asc(documentAnnotationComments.createdAt), asc(documentAnnotationComments.id));
+  }
+
+  return {
+    listThreadsForIssueDocument: async (
+      issueId: string,
+      key: string,
+      options: { status?: "open" | "resolved" | "all"; includeComments?: boolean } = {},
+    ) => {
+      const doc = await getIssueDocument(issueId, key);
+      if (!doc) throw notFound("Document not found");
+      const conditions = [
+        eq(documentAnnotationThreads.issueId, issueId),
+        eq(documentAnnotationThreads.documentId, doc.documentId),
+      ];
+      if (options.status && options.status !== "all") {
+        conditions.push(eq(documentAnnotationThreads.status, options.status));
+      }
+      const threads: DocumentAnnotationThread[] = await db
+        .select(threadSelect)
+        .from(documentAnnotationThreads)
+        .where(and(...conditions))
+        .orderBy(desc(documentAnnotationThreads.updatedAt), desc(documentAnnotationThreads.id));
+      if (!options.includeComments) return threads;
+      const comments = await commentsForThreads(threads.map((thread) => thread.id));
+      const commentsByThread = new Map<string, DocumentAnnotationComment[]>();
+      for (const comment of comments) {
+        const existing = commentsByThread.get(comment.threadId) ?? [];
+        existing.push(comment);
+        commentsByThread.set(comment.threadId, existing);
+      }
+      return threads.map((thread) => ({
+        ...thread,
+        comments: commentsByThread.get(thread.id) ?? [],
+      }));
+    },
+
+    getThreadForIssueDocument: async (issueId: string, key: string, threadId: string) => {
+      const thread = await getThreadForIssue(issueId, key, threadId);
+      if (!thread) return null;
+      const comments = await commentsForThreads([thread.id]);
+      return { ...thread, comments };
+    },
+
+    createThread: async (
+      issueId: string,
+      key: string,
+      input: CreateDocumentAnnotationThread,
+      actor: ActorInput,
+    ) => db.transaction(async (tx) => {
+      await tx.execute(sql`
+        select ${documents.id}
+        from ${issueDocuments}
+        inner join ${documents} on ${issueDocuments.documentId} = ${documents.id}
+        where ${and(eq(issueDocuments.issueId, issueId), eq(issueDocuments.key, key))}
+        for update of ${documents}
+      `);
+      const doc = await getIssueDocument(issueId, key, tx);
+      if (!doc) throw notFound("Document not found");
+      if (
+        input.baseRevisionId !== doc.latestRevisionId
+        || input.baseRevisionNumber !== doc.latestRevisionNumber
+      ) {
+        throw conflict("Annotation anchor requires the current document revision", {
+          currentRevisionId: doc.latestRevisionId,
+          currentRevisionNumber: doc.latestRevisionNumber,
+        });
+      }
+
+      const verification = verifyDocumentAnchorSelector({
+        markdown: doc.latestBody,
+        selector: input.selector,
+      });
+      if (!verification.ok || !verification.anchor) {
+        throw unprocessable("Annotation anchor does not match the current document revision", {
+          reason: verification.reason,
+        });
+      }
+
+      const now = new Date();
+      const [thread] = await tx
+        .insert(documentAnnotationThreads)
+        .values({
+          companyId: doc.companyId,
+          issueId,
+          documentId: doc.documentId,
+          documentKey: doc.documentKey,
+          status: "open",
+          anchorState: "active",
+          anchorConfidence: "exact",
+          originalRevisionId: doc.latestRevisionId,
+          originalRevisionNumber: doc.latestRevisionNumber,
+          currentRevisionId: doc.latestRevisionId,
+          currentRevisionNumber: doc.latestRevisionNumber,
+          selectedText: verification.anchor.selectedText,
+          prefixText: verification.anchor.prefixText,
+          suffixText: verification.anchor.suffixText,
+          normalizedStart: verification.anchor.normalizedStart,
+          normalizedEnd: verification.anchor.normalizedEnd,
+          markdownStart: verification.anchor.markdownStart,
+          markdownEnd: verification.anchor.markdownEnd,
+          anchorSelector: input.selector,
+          createdByAgentId: actor.agentId ?? null,
+          createdByUserId: actor.userId ?? null,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .returning(threadSelect);
+
+      const [comment] = await tx
+        .insert(documentAnnotationComments)
+        .values({
+          companyId: doc.companyId,
+          threadId: thread.id,
+          issueId,
+          documentId: doc.documentId,
+          body: input.body,
+          authorType: actor.actorType,
+          authorAgentId: actor.agentId ?? null,
+          authorUserId: actor.userId ?? null,
+          createdByRunId: actor.runId ?? null,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .returning(commentSelect);
+
+      return { ...thread, comments: [comment] };
+    }),
+
+    addComment: async (
+      issueId: string,
+      key: string,
+      threadId: string,
+      input: CreateDocumentAnnotationComment,
+      actor: ActorInput,
+    ) => db.transaction(async (tx) => {
+      const thread = await getThreadForIssue(issueId, key, threadId, tx);
+      if (!thread) throw notFound("Annotation thread not found");
+      const now = new Date();
+      const [comment] = await tx
+        .insert(documentAnnotationComments)
+        .values({
+          companyId: thread.companyId,
+          threadId: thread.id,
+          issueId: thread.issueId,
+          documentId: thread.documentId,
+          body: input.body,
+          authorType: actor.actorType,
+          authorAgentId: actor.agentId ?? null,
+          authorUserId: actor.userId ?? null,
+          createdByRunId: actor.runId ?? null,
+          createdAt: now,
+          updatedAt: now,
+        })
+        .returning(commentSelect);
+      await tx
+        .update(documentAnnotationThreads)
+        .set({ updatedAt: now })
+        .where(eq(documentAnnotationThreads.id, thread.id));
+      return comment;
+    }),
+
+    updateThread: async (
+      issueId: string,
+      key: string,
+      threadId: string,
+      input: UpdateDocumentAnnotationThread,
+      actor: ActorInput,
+    ) => db.transaction(async (tx) => {
+      const thread = await getThreadForIssue(issueId, key, threadId, tx);
+      if (!thread) throw notFound("Annotation thread not found");
+      if (!input.status || input.status === thread.status) return thread;
+
+      const now = new Date();
+      const [updated] = await tx
+        .update(documentAnnotationThreads)
+        .set(input.status === "resolved"
+          ? {
+            status: "resolved",
+            resolvedByAgentId: actor.agentId ?? null,
+            resolvedByUserId: actor.userId ?? null,
+            resolvedAt: now,
+            updatedAt: now,
+          }
+          : {
+            status: "open",
+            resolvedByAgentId: null,
+            resolvedByUserId: null,
+            resolvedAt: null,
+            updatedAt: now,
+          })
+        .where(eq(documentAnnotationThreads.id, thread.id))
+        .returning(threadSelect);
+      return updated;
+    }),
+
+    remapOpenThreadsForDocument: async (input: {
+      issueId: string;
+      key: string;
+      documentId: string;
+      nextRevisionId: string | null;
+      nextRevisionNumber: number;
+      nextBody: string;
+    }) => db.transaction(async (tx) => {
+      const threads: DocumentAnnotationThread[] = await tx
+        .select(threadSelect)
+        .from(documentAnnotationThreads)
+        .where(and(
+          eq(documentAnnotationThreads.issueId, input.issueId),
+          eq(documentAnnotationThreads.documentId, input.documentId),
+          eq(documentAnnotationThreads.status, "open"),
+        ));
+      const changed = [];
+      const now = new Date();
+
+      for (const thread of threads) {
+        if (thread.currentRevisionId === input.nextRevisionId) continue;
+        const previousAnchor = snapshotFromThread(thread);
+        const remap = remapDocumentAnchor({
+          previousAnchor,
+          nextMarkdown: input.nextBody,
+        });
+        const nextAnchor = remap.anchor;
+        const nextSelector = nextAnchor ? anchorSnapshotToSelector(nextAnchor) : thread.anchorSelector;
+        const [updated] = await tx
+          .update(documentAnnotationThreads)
+          .set({
+            currentRevisionId: input.nextRevisionId,
+            currentRevisionNumber: input.nextRevisionNumber,
+            anchorState: remap.anchorState,
+            anchorConfidence: remap.confidence,
+            ...(nextAnchor
+              ? {
+                selectedText: nextAnchor.selectedText,
+                prefixText: nextAnchor.prefixText,
+                suffixText: nextAnchor.suffixText,
+                normalizedStart: nextAnchor.normalizedStart,
+                normalizedEnd: nextAnchor.normalizedEnd,
+                markdownStart: nextAnchor.markdownStart,
+                markdownEnd: nextAnchor.markdownEnd,
+              }
+              : {}),
+            anchorSelector: nextSelector,
+            updatedAt: now,
+          })
+          .where(eq(documentAnnotationThreads.id, thread.id))
+          .returning(threadSelect);
+        const [snapshot] = await tx
+          .insert(documentAnnotationAnchorSnapshots)
+          .values({
+            companyId: thread.companyId,
+            threadId: thread.id,
+            documentId: thread.documentId,
+            fromRevisionId: thread.currentRevisionId,
+            fromRevisionNumber: thread.currentRevisionNumber,
+            toRevisionId: input.nextRevisionId,
+            toRevisionNumber: input.nextRevisionNumber,
+            previousAnchor,
+            nextAnchor,
+            anchorState: remap.anchorState,
+            anchorConfidence: remap.confidence,
+            failureReason: remap.anchor ? null : remap.reason,
+            createdAt: now,
+          })
+          .returning();
+        changed.push({ thread: updated, snapshot });
+      }
+
+      return changed;
+    }),
+
+    selectorToAnchorSnapshot,
+  };
+}

server/src/services/execution-workspace-policy.ts

@@ -119,26 +119,126 @@ export function parseIssueExecutionWorkspaceSettings(raw: unknown): IssueExecuti
   };
 }
 
+export type ExecutionWorkspaceEnvironmentSource =
+  | "workspace"
+  | "issue"
+  | "project"
+  | "agent"
+  | "default";
+
+export type ExecutionWorkspaceEnvironmentConflict = {
+  reason: "reused_workspace_environment_mismatch";
+  workspaceEnvironmentId: string;
+  assigneeIntendedEnvironmentId: string;
+  assigneeIntendedSource: Exclude<ExecutionWorkspaceEnvironmentSource, "workspace">;
+};
+
+export type ExecutionWorkspaceEnvironmentResolution = {
+  environmentId: string;
+  source: ExecutionWorkspaceEnvironmentSource;
+  conflict: ExecutionWorkspaceEnvironmentConflict | null;
+};
+
+function resolveAssigneeIntendedExecutionWorkspaceEnvironment(input: {
+  projectPolicy: ProjectExecutionWorkspacePolicy | null;
+  issueSettings: IssueExecutionWorkspaceSettings | null;
+  agentDefaultEnvironmentId: string | null;
+  defaultEnvironmentId: string;
+}): {
+  environmentId: string;
+  source: Exclude<ExecutionWorkspaceEnvironmentSource, "workspace">;
+} {
+  // Explicit issue-level env override always wins, even for null-default
+  // (local-only) agents. An operator who deliberately set
+  // `executionWorkspaceSettings.environmentId` on this specific issue (see the
+  // issues-service contract preserved in issues.ts:4243) chose that env for
+  // this assignment and should not be silently downgraded to the local default
+  // (PAPA-430 review fix). Inherited issue envs from
+  // `inheritExecutionWorkspaceFromIssueId` are stripped before this point in
+  // `resolveExecutionWorkspaceEnvironmentId`.
+  if (input.issueSettings?.environmentId !== undefined) {
+    return {
+      environmentId: input.issueSettings.environmentId ?? input.defaultEnvironmentId,
+      source: "issue",
+    };
+  }
+  // A null defaultEnvironmentId on the agent means it is deliberately scoped to
+  // the local default (e.g. Manual QA today). Project policy must not promote
+  // such an agent off of local — only an explicit issue-level override above
+  // can move the assignee away from the local default.
+  if (input.agentDefaultEnvironmentId === null) {
+    return { environmentId: input.defaultEnvironmentId, source: "default" };
+  }
+  if (input.projectPolicy?.environmentId !== undefined) {
+    return {
+      environmentId: input.projectPolicy.environmentId ?? input.defaultEnvironmentId,
+      source: "project",
+    };
+  }
+  return { environmentId: input.agentDefaultEnvironmentId, source: "agent" };
+}
+
 export function resolveExecutionWorkspaceEnvironmentId(input: {
   projectPolicy: ProjectExecutionWorkspacePolicy | null;
   issueSettings: IssueExecutionWorkspaceSettings | null;
   workspaceConfig: { environmentId?: string | null } | null;
   agentDefaultEnvironmentId: string | null;
   defaultEnvironmentId: string;
-}) {
+}): ExecutionWorkspaceEnvironmentResolution {
+  // PAPA-431 companion: when the assignee has no explicit defaultEnvironmentId
+  // (deliberately local-only, e.g. Manual QA) AND the issue settings env exactly
+  // matches the reused workspace env, treat the issue env as a promoted artifact
+  // from `inheritExecutionWorkspaceFromIssueId` rather than a deliberate
+  // operator choice. Strip it so the resolver falls back to the local default
+  // and the workspace-vs-intended conflict check forces a fresh realization.
+  // A genuine operator override (via PATCH on the issue) reaches this code path
+  // either with no reused workspace (workspaceConfig === null) or against a
+  // workspace whose persisted env does not match the new override; both keep
+  // the issue setting in place.
+  const inheritedIssueEnvOnNullDefaultAssignee =
+    input.agentDefaultEnvironmentId === null &&
+    input.workspaceConfig?.environmentId !== undefined &&
+    input.workspaceConfig?.environmentId !== null &&
+    input.issueSettings?.environmentId !== undefined &&
+    input.issueSettings.environmentId === input.workspaceConfig.environmentId;
+  let issueSettingsForResolution = input.issueSettings;
+  if (inheritedIssueEnvOnNullDefaultAssignee && input.issueSettings) {
+    const { environmentId: _droppedInheritedEnv, ...rest } = input.issueSettings;
+    void _droppedInheritedEnv;
+    issueSettingsForResolution = rest as IssueExecutionWorkspaceSettings;
+  }
+
+  const assigneeIntended = resolveAssigneeIntendedExecutionWorkspaceEnvironment({
+    projectPolicy: input.projectPolicy,
+    issueSettings: issueSettingsForResolution,
+    agentDefaultEnvironmentId: input.agentDefaultEnvironmentId,
+    defaultEnvironmentId: input.defaultEnvironmentId,
+  });
+
   if (input.workspaceConfig?.environmentId !== undefined) {
-    return input.workspaceConfig.environmentId ?? input.defaultEnvironmentId;
+    const workspaceEnvironmentId =
+      input.workspaceConfig.environmentId ?? input.defaultEnvironmentId;
+    // PAPA-380 / PAPA-431: a reused workspace's persisted environmentId must
+    // never silently shadow the current assignee's environment identity.
+    // When they disagree, refuse the silent reuse: return the assignee's
+    // intended env and surface a conflict signal so the caller forces a fresh
+    // workspace realization (or otherwise alerts the operator) instead of
+    // running the agent on someone else's environment.
+    if (workspaceEnvironmentId !== assigneeIntended.environmentId) {
+      return {
+        environmentId: assigneeIntended.environmentId,
+        source: assigneeIntended.source,
+        conflict: {
+          reason: "reused_workspace_environment_mismatch",
+          workspaceEnvironmentId,
+          assigneeIntendedEnvironmentId: assigneeIntended.environmentId,
+          assigneeIntendedSource: assigneeIntended.source,
+        },
+      };
+    }
+    return { environmentId: workspaceEnvironmentId, source: "workspace", conflict: null };
   }
-  if (input.issueSettings?.environmentId !== undefined) {
-    return input.issueSettings.environmentId ?? input.defaultEnvironmentId;
-  }
-  if (input.projectPolicy?.environmentId !== undefined) {
-    return input.projectPolicy.environmentId ?? input.defaultEnvironmentId;
-  }
-  if (input.agentDefaultEnvironmentId !== null) {
-    return input.agentDefaultEnvironmentId;
-  }
-  return input.defaultEnvironmentId;
+  return { environmentId: assigneeIntended.environmentId, source: assigneeIntended.source, conflict: null };
 }
 
 export function defaultIssueExecutionWorkspaceSettingsForProject(

server/src/services/heartbeat.ts

@@ -37,6 +37,7 @@ import {
   heartbeatRuns,
   issueApprovals,
   issueComments,
+  issuePlanDecompositions,
   issueRelations,
   issueThreadInteractions,
   issues,
@@ -1933,6 +1934,59 @@ function normalizeInteractionContinuationWakeContext(
   clearInteractionContinuationWakeContext(contextSnapshot);
 }
 
+type AcceptedPlanWakeRoutingDecision = {
+  otherActiveClaimIssueId: string;
+  otherActiveClaimIdentifier: string | null;
+  otherActiveClaimTitle: string;
+  forceFreshSession: boolean;
+  suppressAcceptedContinuation: boolean;
+};
+
+async function resolveAcceptedPlanWakeRoutingDecision(args: {
+  db: Db;
+  companyId: string;
+  agentId: string;
+  issueId: string | null;
+  acceptedPlanContinuationWake: boolean;
+  contextSnapshot: Record<string, unknown>;
+}): Promise<AcceptedPlanWakeRoutingDecision | null> {
+  if (args.issueId === null) return null;
+  if (!args.acceptedPlanContinuationWake) return null;
+
+  const activeClaims = await args.db
+    .select({
+      sourceIssueId: issuePlanDecompositions.sourceIssueId,
+      identifier: issues.identifier,
+      title: issues.title,
+    })
+    .from(issuePlanDecompositions)
+    .innerJoin(issues, eq(issues.id, issuePlanDecompositions.sourceIssueId))
+    .where(and(
+      eq(issuePlanDecompositions.companyId, args.companyId),
+      eq(issuePlanDecompositions.ownerAgentId, args.agentId),
+      eq(issuePlanDecompositions.status, "in_flight"),
+    ))
+    .orderBy(desc(issuePlanDecompositions.updatedAt), asc(issuePlanDecompositions.createdAt));
+
+  if (activeClaims.length === 0) return null;
+  if (activeClaims.some((claim) => claim.sourceIssueId === args.issueId)) return null;
+
+  const otherActiveClaim = activeClaims[0];
+  if (!otherActiveClaim) return null;
+
+  const hasAcceptedContinuationWake =
+    readNonEmptyString(args.contextSnapshot.interactionKind) === "request_confirmation" &&
+    readNonEmptyString(args.contextSnapshot.interactionStatus) === "accepted";
+
+  return {
+    otherActiveClaimIssueId: otherActiveClaim.sourceIssueId,
+    otherActiveClaimIdentifier: otherActiveClaim.identifier ?? null,
+    otherActiveClaimTitle: otherActiveClaim.title,
+    forceFreshSession: true,
+    suppressAcceptedContinuation: hasAcceptedContinuationWake,
+  };
+}
+
 export function mergeCoalescedContextSnapshot(
   existingRaw: unknown,
   incoming: Record<string, unknown>,
@@ -2229,6 +2283,7 @@ export function buildPaperclipTaskMarkdown(input: {
     kind?: string | null;
     status?: string | null;
   } | null;
+  acceptedPlanContinuation?: boolean;
 }) {
   const quoteTaskScalar = (value: string) => JSON.stringify(value);
   const fenceTaskText = (value: string) => {
@@ -2243,8 +2298,11 @@ export function buildPaperclipTaskMarkdown(input: {
   const wakeComment = input.wakeComment ?? null;
   const acceptedPlanContinuation =
     !wakeComment &&
-    input.interaction?.kind === "request_confirmation" &&
-    input.interaction.status === "accepted";
+    (input.acceptedPlanContinuation || (
+      input.interaction?.kind === "request_confirmation" &&
+      input.interaction.status === "accepted" &&
+      issue?.workMode === "planning"
+    ));
   if (!issue && !wakeComment) return null;
 
   const lines = [
@@ -2270,6 +2328,12 @@ export function buildPaperclipTaskMarkdown(input: {
         "Planning mode directive:",
         directive,
       );
+    } else if (acceptedPlanContinuation) {
+      lines.push(
+        "",
+        "Accepted plan directive:",
+        "Create child issues from the approved plan only. Do not write code or perform implementation work on the source issue.",
+      );
     }
     const description = issue.description?.trim();
     if (description) {
@@ -7055,6 +7119,37 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
           .where(and(eq(projects.id, executionProjectId), eq(projects.companyId, agent.companyId)))
           .then((rows) => rows[0] ?? null)
       : null;
+    const acceptedPlanWakeRoutingDecision = issueContext
+      ? await resolveAcceptedPlanWakeRoutingDecision({
+          db,
+          companyId: agent.companyId,
+          agentId: agent.id,
+          issueId,
+          acceptedPlanContinuationWake:
+            readNonEmptyString(context.workspaceRefreshReason) === "accepted_plan_confirmation"
+            || (
+              issueContext.workMode === "planning"
+              && readNonEmptyString(context.interactionKind) === "request_confirmation"
+              && readNonEmptyString(context.interactionStatus) === "accepted"
+            ),
+          contextSnapshot: context,
+        })
+      : null;
+    if (acceptedPlanWakeRoutingDecision) {
+      context.forceFreshSession = true;
+      context.acceptedPlanWakeRouting = {
+        reason: "other_issue_claim_in_flight",
+        otherActiveClaimIssueId: acceptedPlanWakeRoutingDecision.otherActiveClaimIssueId,
+        otherActiveClaimIdentifier: acceptedPlanWakeRoutingDecision.otherActiveClaimIdentifier,
+        otherActiveClaimTitle: acceptedPlanWakeRoutingDecision.otherActiveClaimTitle,
+      };
+      if (acceptedPlanWakeRoutingDecision.suppressAcceptedContinuation) {
+        clearInteractionContinuationWakeContext(context);
+        delete context.workspaceRefreshReason;
+      }
+    } else {
+      delete context.acceptedPlanWakeRouting;
+    }
     const routineEnvContext = await getRoutineEnvForExecutionIssue(agent.companyId, issueContext);
     const projectExecutionWorkspacePolicy = gateProjectExecutionWorkspacePolicy(
       parseProjectExecutionWorkspacePolicy(projectContext?.executionWorkspacePolicy),
@@ -7154,6 +7249,9 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
         kind: readNonEmptyString(context.interactionKind),
         status: readNonEmptyString(context.interactionStatus),
       },
+      acceptedPlanContinuation:
+        readNonEmptyString(context.workspaceRefreshReason) === "accepted_plan_confirmation"
+        && !parseObject(context.acceptedPlanWakeRouting),
     });
     if (issueRef) {
       context.paperclipIssue = {
@@ -7178,13 +7276,47 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
     }
     const existingExecutionWorkspace =
       issueRef?.executionWorkspaceId ? await executionWorkspacesSvc.getById(issueRef.executionWorkspaceId) : null;
-    const shouldReuseExisting =
+    const requestedShouldReuseExisting =
       issueRef?.executionWorkspacePreference === "reuse_existing" &&
       existingExecutionWorkspace !== null &&
       existingExecutionWorkspace.status !== "archived";
-    const reusableExecutionWorkspaceConfig = shouldReuseExisting
+    const requestedReusableExecutionWorkspaceConfig = requestedShouldReuseExisting
       ? existingExecutionWorkspace?.config ?? null
       : null;
+    const defaultEnvironment = await environmentsSvc.ensureLocalEnvironment(agent.companyId);
+    const environmentResolution = resolveExecutionWorkspaceEnvironmentId({
+      projectPolicy: projectExecutionWorkspacePolicy,
+      issueSettings: issueExecutionWorkspaceSettings,
+      workspaceConfig: requestedReusableExecutionWorkspaceConfig,
+      agentDefaultEnvironmentId: agent.defaultEnvironmentId,
+      defaultEnvironmentId: defaultEnvironment.id,
+    });
+    // PAPA-380 / PAPA-431: when the resolver refuses silent reuse of the
+    // persisted workspace environment, also force a fresh workspace
+    // realization on the assignee's intended env. Reusing the on-disk
+    // workspace while swapping the env underneath it would mismatch the cwd's
+    // runtime expectations (e.g. an SSH-targeted worktree running on the
+    // local default driver).
+    if (environmentResolution.conflict) {
+      logger.warn(
+        {
+          runId: run.id,
+          issueId,
+          agentId: agent.id,
+          adapterType: agent.adapterType,
+          existingExecutionWorkspaceId: existingExecutionWorkspace?.id ?? null,
+          workspaceEnvironmentId: environmentResolution.conflict.workspaceEnvironmentId,
+          assigneeIntendedEnvironmentId:
+            environmentResolution.conflict.assigneeIntendedEnvironmentId,
+          assigneeIntendedSource: environmentResolution.conflict.assigneeIntendedSource,
+        },
+        "Refusing silent reuse of execution workspace whose environment does not match the assignee's intended environment; forcing fresh realization",
+      );
+    }
+    const shouldReuseExisting = requestedShouldReuseExisting && !environmentResolution.conflict;
+    const reusableExecutionWorkspaceConfig = shouldReuseExisting
+      ? requestedReusableExecutionWorkspaceConfig
+      : null;
     const persistedExecutionWorkspaceMode = shouldReuseExisting && existingExecutionWorkspace
       ? issueExecutionWorkspaceModeForPersistedWorkspace(existingExecutionWorkspace.mode)
       : null;
@@ -7194,14 +7326,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
       persistedExecutionWorkspaceMode === "agent_default"
         ? persistedExecutionWorkspaceMode
         : requestedExecutionWorkspaceMode;
-    const defaultEnvironment = await environmentsSvc.ensureLocalEnvironment(agent.companyId);
-    const selectedEnvironmentId = resolveExecutionWorkspaceEnvironmentId({
-      projectPolicy: projectExecutionWorkspacePolicy,
-      issueSettings: issueExecutionWorkspaceSettings,
-      workspaceConfig: reusableExecutionWorkspaceConfig,
-      agentDefaultEnvironmentId: agent.defaultEnvironmentId,
-      defaultEnvironmentId: defaultEnvironment.id,
-    });
+    const selectedEnvironmentId = environmentResolution.environmentId;
     const workspaceManagedConfig = shouldReuseExisting
       ? { ...config }
       : buildExecutionWorkspaceAdapterConfig({
@@ -7882,31 +8007,80 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
           "local agent jwt secret missing or invalid; running without injected PAPERCLIP_API_KEY",
         );
       }
-      const adapterResult = await adapter.execute({
-        runId: run.id,
-        agent,
-        runtime: runtimeForAdapter,
-        config: runtimeConfig,
-        context,
-        runtimeCommandSpec: adapter.getRuntimeCommandSpec?.(runtimeConfig) ?? null,
-        executionTarget,
-        executionTransport: remoteExecution
-          ? { remoteExecution: remoteExecution as unknown as Record<string, unknown> }
-          : undefined,
-        onLog,
-        onMeta: onAdapterMeta,
-        onSpawn: async (meta) => {
-          await persistRunProcessMetadata(run.id, {
-            pid: meta.pid,
-            processGroupId:
-              "processGroupId" in meta && typeof meta.processGroupId === "number"
-                ? meta.processGroupId
-                : null,
-            startedAt: meta.startedAt,
+      let adapterFinalizeOutcome: "succeeded" | "failed" | null = null;
+      const recordWorkspaceFinalize = async (
+        status: "succeeded" | "failed",
+        metadata?: Record<string, unknown>,
+      ) => {
+        if (adapterFinalizeOutcome) return;
+        await workspaceOperationRecorder.recordOperation({
+          phase: "workspace_finalize",
+          cwd: executionWorkspace.cwd,
+          metadata: {
+            adapterType: agent.adapterType,
+            executionTargetKind: executionTarget?.kind ?? "local",
+            ...metadata,
+          },
+          run: async () => ({ status }),
+        });
+        // Only mark the outcome after the row landed, so a transient write
+        // failure on the succeeded path can still be recovered by recording
+        // finalize=failed from the catch path below.
+        adapterFinalizeOutcome = status;
+      };
+
+      let adapterResult: Awaited<ReturnType<typeof adapter.execute>>;
+      try {
+        adapterResult = await adapter.execute({
+          runId: run.id,
+          agent,
+          runtime: runtimeForAdapter,
+          config: runtimeConfig,
+          context,
+          runtimeCommandSpec: adapter.getRuntimeCommandSpec?.(runtimeConfig) ?? null,
+          executionTarget,
+          executionTransport: remoteExecution
+            ? { remoteExecution: remoteExecution as unknown as Record<string, unknown> }
+            : undefined,
+          onLog,
+          onMeta: onAdapterMeta,
+          onSpawn: async (meta) => {
+            await persistRunProcessMetadata(run.id, {
+              pid: meta.pid,
+              processGroupId:
+                "processGroupId" in meta && typeof meta.processGroupId === "number"
+                  ? meta.processGroupId
+                  : null,
+              startedAt: meta.startedAt,
+            });
+          },
+          authToken: authToken ?? undefined,
+        });
+        // Adapter returned cleanly, which means its workspace-restore finally
+        // block also ran without throwing. Record the workspace_finalize
+        // barrier so dependents that share this executionWorkspace can wake.
+        // If recording the barrier itself fails, propagate as a run failure
+        // rather than silently leaving dependents stranded behind a missing
+        // finalize row.
+        await recordWorkspaceFinalize("succeeded");
+      } catch (adapterErr) {
+        // Adapter (or its restore finally) threw — or the finalize record
+        // write itself threw. Either way the workspace may be in a partial
+        // state. Best-effort record finalize=failed so the dependent readiness
+        // check keeps the gate closed instead of waking on stale local state,
+        // and surface the original error to the caller.
+        try {
+          await recordWorkspaceFinalize("failed", {
+            errorMessage: adapterErr instanceof Error ? adapterErr.message : String(adapterErr),
           });
-        },
-        authToken: authToken ?? undefined,
-      });
+        } catch (recordErr) {
+          logger.warn(
+            { err: recordErr, runId: run.id, executionWorkspaceId: persistedExecutionWorkspace?.id ?? null },
+            "failed to record workspace_finalize=failed operation; dependents may remain gated",
+          );
+        }
+        throw adapterErr;
+      }
       const adapterManagedRuntimeServices = adapterResult.runtimeServices
         ? await persistAdapterManagedRuntimeServices({
             db,
@@ -8152,6 +8326,54 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
             : livenessRun,
           agent,
         );
+
+        // Workspace-finalize wake re-fire: if this run's issue was marked done
+        // mid-run (so the original `issue_blockers_resolved` wake was gated by
+        // the readiness check waiting for workspace_finalize), the finalize
+        // row we just recorded now lets dependents proceed. Fire wakes here.
+        if (issueId && adapterFinalizeOutcome === "succeeded") {
+          try {
+            const blockerIssueStatus = await db
+              .select({ status: issues.status })
+              .from(issues)
+              .where(eq(issues.id, issueId))
+              .then((rows) => rows[0]?.status ?? null);
+            if (blockerIssueStatus === "done") {
+              const dependents = await issuesSvc.listWakeableBlockedDependents(issueId);
+              for (const dependent of dependents) {
+                await enqueueWakeup(dependent.assigneeAgentId, {
+                  source: "automation",
+                  triggerDetail: "system",
+                  reason: "issue_blockers_resolved",
+                  payload: {
+                    issueId: dependent.id,
+                    resolvedBlockerIssueId: issueId,
+                    blockerIssueIds: dependent.blockerIssueIds,
+                    deferredFor: "workspace_finalize",
+                  },
+                  contextSnapshot: {
+                    issueId: dependent.id,
+                    taskId: dependent.id,
+                    wakeReason: "issue_blockers_resolved",
+                    source: "workspace.finalize",
+                    resolvedBlockerIssueId: issueId,
+                    blockerIssueIds: dependent.blockerIssueIds,
+                  },
+                }).catch((wakeErr) => {
+                  logger.warn(
+                    { err: wakeErr, issueId, dependentIssueId: dependent.id, agentId: dependent.assigneeAgentId },
+                    "failed to fire deferred dependent wake after workspace_finalize",
+                  );
+                });
+              }
+            }
+          } catch (finalizeWakeErr) {
+            logger.warn(
+              { err: finalizeWakeErr, runId: run.id, issueId },
+              "failed to evaluate dependent wakes after workspace_finalize",
+            );
+          }
+        }
       }
 
       if (finalizedRun) {

server/src/services/index.ts

@@ -6,6 +6,7 @@ export { agentService, deduplicateAgentName } from "./agents.js";
 export { agentInstructionsService, syncInstructionsBundleConfigFromFilePath } from "./agent-instructions.js";
 export { assetService } from "./assets.js";
 export { documentService, extractLegacyPlanBody } from "./documents.js";
+export { documentAnnotationService } from "./document-annotations.js";
 export {
   ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY,
   buildContinuationSummaryMarkdown,

server/src/services/instance-settings.ts

@@ -43,6 +43,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimenta
     return {
       enableEnvironments: parsed.data.enableEnvironments ?? false,
       enableIsolatedWorkspaces: parsed.data.enableIsolatedWorkspaces ?? false,
+      enableIssuePlanDecompositions: parsed.data.enableIssuePlanDecompositions ?? false,
       enableCloudSync: parsed.data.enableCloudSync ?? false,
       autoRestartDevServerWhenIdle: parsed.data.autoRestartDevServerWhenIdle ?? false,
       enableIssueGraphLivenessAutoRecovery: parsed.data.enableIssueGraphLivenessAutoRecovery ?? false,
@@ -54,6 +55,7 @@ export function normalizeExperimentalSettings(raw: unknown): InstanceExperimenta
   return {
     enableEnvironments: false,
     enableIsolatedWorkspaces: false,
+    enableIssuePlanDecompositions: false,
     enableCloudSync: false,
     autoRestartDevServerWhenIdle: false,
     enableIssueGraphLivenessAutoRecovery: false,

server/src/services/issue-references.ts

@@ -1,6 +1,13 @@
 import { and, asc, eq, inArray, isNull } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import { documents, issueComments, issueDocuments, issueReferenceMentions, issues } from "@paperclipai/db";
+import {
+  documentAnnotationComments,
+  documents,
+  issueComments,
+  issueDocuments,
+  issueReferenceMentions,
+  issues,
+} from "@paperclipai/db";
 import type {
   IssueReferenceSource,
   IssueReferenceSourceKind,
@@ -230,6 +237,29 @@ export function issueReferenceService(db: Db) {
     }, dbOrTx);
   }
 
+  async function syncAnnotationComment(commentId: string, dbOrTx: any = db) {
+    const comment = await dbOrTx
+      .select({
+        id: documentAnnotationComments.id,
+        companyId: documentAnnotationComments.companyId,
+        issueId: documentAnnotationComments.issueId,
+        body: documentAnnotationComments.body,
+      })
+      .from(documentAnnotationComments)
+      .where(eq(documentAnnotationComments.id, commentId))
+      .then((rows: Array<{ id: string; companyId: string; issueId: string; body: string }>) => rows[0] ?? null);
+    if (!comment) throw notFound("Document annotation comment not found");
+
+    await replaceSourceMentions({
+      companyId: comment.companyId,
+      sourceIssueId: comment.issueId,
+      sourceKind: "comment",
+      sourceRecordId: comment.id,
+      documentKey: null,
+      text: comment.body,
+    }, dbOrTx);
+  }
+
   async function syncDocument(documentId: string, dbOrTx: any = db) {
     const document = await dbOrTx
       .select({
@@ -396,6 +426,7 @@ export function issueReferenceService(db: Db) {
   return {
     syncIssue,
     syncComment,
+    syncAnnotationComment,
     syncDocument,
     deleteDocumentSource,
     syncAllForIssue,

server/src/services/issue-thread-interactions.ts

@@ -36,7 +36,7 @@ import {
   suggestTasksResultSchema,
 } from "@paperclipai/shared";
 import { conflict, notFound, unprocessable } from "../errors.js";
-import { issueService } from "./issues.js";
+import { issueService, listUnfinalizedExecutionWorkspaceIds } from "./issues.js";
 
 type InteractionActor = {
   agentId?: string | null;
@@ -457,6 +457,32 @@ export function issueThreadInteractionService(db: Db) {
       .then((rows) => rows[0] ?? null);
   }
 
+  async function assertIssueWorkspaceFinalizedForAccept(args: {
+    db: Pick<Db, "select">;
+    issue: { id: string; companyId: string };
+  }) {
+    const executionWorkspaceId = await args.db
+      .select({ executionWorkspaceId: issues.executionWorkspaceId })
+      .from(issues)
+      .where(eq(issues.id, args.issue.id))
+      .then((rows: Array<{ executionWorkspaceId: string | null }>) => rows[0]?.executionWorkspaceId ?? null);
+
+    if (!executionWorkspaceId) return;
+
+    const unfinalized = await listUnfinalizedExecutionWorkspaceIds(
+      args.db,
+      args.issue.companyId,
+      [executionWorkspaceId],
+    );
+    if (!unfinalized.has(executionWorkspaceId)) return;
+
+    throw conflict(
+      "Cannot accept interaction: the issue's most recent run has not completed workspace_finalize. "
+        + "Retry once the local worktree has finished syncing.",
+      { executionWorkspaceId },
+    );
+  }
+
   async function getPendingInteractionForResolution(args: {
     issue: { id: string; companyId: string };
     interactionId: string;
@@ -747,8 +773,12 @@ export function issueThreadInteractionService(db: Db) {
       const current = await getPendingInteractionForResolution({ issue, interactionId });
       switch (current.kind) {
         case "suggest_tasks":
+          // Accepting suggest_tasks only creates follow-up issues; it does not
+          // approve code state or move the source workspace forward, so the
+          // workspace_finalize gate (PAPA-440) does not apply here.
           return issueThreadInteractionService(db).acceptSuggestedTasks(issue, interactionId, data, actor);
         case "request_confirmation": {
+          await assertIssueWorkspaceFinalizedForAccept({ db, issue });
           const accepted = await acceptRequestConfirmation({
             issue,
             current,

server/src/services/issues.ts

@@ -1,4 +1,5 @@
 import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 import { and, asc, desc, eq, gt, inArray, isNull, like, lt, ne, notInArray, or, sql, type SQL } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
@@ -9,6 +10,7 @@ import {
   assets,
   companies,
   companyMemberships,
+  documentRevisions,
   documents,
   goals,
   heartbeatRuns,
@@ -17,6 +19,7 @@ import {
   issueAttachments,
   issueInboxArchives,
   issueLabels,
+  issuePlanDecompositions,
   issueRecoveryActions,
   issueRelations,
   issueComments,
@@ -27,8 +30,10 @@ import {
   labels,
   projectWorkspaces,
   projects,
+  workspaceOperations,
 } from "@paperclipai/db";
 import type {
+  AcceptedPlanDecomposition,
   IssueCommentAuthorType,
   IssueCommentMetadata,
   IssueCommentPresentation,
@@ -245,6 +250,7 @@ export interface IssueFilters {
 
 type IssueRow = typeof issues.$inferSelect;
 type IssueLabelRow = typeof labels.$inferSelect;
+type IssuePlanDecompositionRow = typeof issuePlanDecompositions.$inferSelect;
 type IssueActiveRunRow = {
   id: string;
   status: string;
@@ -284,6 +290,30 @@ type IssueLastActivityStat = {
   latestCommentAt: Date | null;
   latestLogAt: Date | null;
 };
+
+function serializeAcceptedPlanDecomposition(
+  decomposition: IssuePlanDecompositionRow,
+): AcceptedPlanDecomposition {
+  return {
+    id: decomposition.id,
+    companyId: decomposition.companyId,
+    sourceIssueId: decomposition.sourceIssueId,
+    acceptedPlanRevisionId: decomposition.acceptedPlanRevisionId,
+    acceptedInteractionId: decomposition.acceptedInteractionId,
+    status: decomposition.status as AcceptedPlanDecomposition["status"],
+    requestFingerprint: decomposition.requestFingerprint,
+    // Intentionally omit requestedChildren here; the API only needs stable counts
+    // and child ids, while the durable table keeps the full child draft payload.
+    requestedChildCount: decomposition.requestedChildCount,
+    childIssueIds: normalizeIssuePlanDecompositionChildIds(decomposition.childIssueIds),
+    ownerAgentId: decomposition.ownerAgentId,
+    ownerUserId: decomposition.ownerUserId,
+    ownerRunId: decomposition.ownerRunId,
+    completedAt: decomposition.completedAt,
+    createdAt: decomposition.createdAt,
+    updatedAt: decomposition.updatedAt,
+  };
+}
 type IssueUserContextInput = {
   createdByUserId: string | null;
   assigneeUserId: string | null;
@@ -303,6 +333,16 @@ type IssueChildCreateInput = IssueCreateInput & {
   actorAgentId?: string | null;
   actorUserId?: string | null;
 };
+type AcceptedPlanDecompositionInput = {
+  acceptedPlanRevisionId: string;
+  children: IssueChildCreateInput[];
+  actorAgentId?: string | null;
+  actorUserId?: string | null;
+  actorRunId?: string | null;
+};
+type AcceptedPlanDocumentInteraction = {
+  id: string;
+};
 type IssueRelationSummaryMap = {
   blockedBy: IssueRelationIssueSummary[];
   blocks: IssueRelationIssueSummary[];
@@ -312,6 +352,8 @@ export type IssueDependencyReadiness = {
   blockerIssueIds: string[];
   unresolvedBlockerIssueIds: string[];
   unresolvedBlockerCount: number;
+  /** Blockers whose status is `done` but whose execution workspace has not yet finalized. */
+  pendingFinalizeBlockerIssueIds: string[];
   allBlockersDone: boolean;
   isDependencyReady: boolean;
 };
@@ -376,17 +418,237 @@ function appendAcceptanceCriteriaToDescription(description: string | null | unde
   return base ? `${base}\n\n${criteriaMarkdown}` : criteriaMarkdown;
 }
 
+function normalizeAcceptedPlanDecompositionFingerprintValue(value: unknown): unknown {
+  if (value === undefined) return null;
+  if (
+    value == null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeAcceptedPlanDecompositionFingerprintValue(item));
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort()
+        .map((key) => [key, normalizeAcceptedPlanDecompositionFingerprintValue(record[key])]),
+    );
+  }
+  return String(value);
+}
+
+const ACCEPTED_PLAN_DECOMPOSITION_FINGERPRINT_CHILD_METADATA_KEYS = new Set([
+  "id",
+  "companyId",
+  "parentId",
+  "identifier",
+  "checkoutRunId",
+  "executionRunId",
+  "executionLockedAt",
+  "startedAt",
+  "completedAt",
+  "cancelledAt",
+  "hiddenAt",
+  "createdAt",
+  "updatedAt",
+  "createdByAgentId",
+  "createdByUserId",
+  "updatedByAgentId",
+  "updatedByUserId",
+  "actorAgentId",
+  "actorUserId",
+]);
+
+function normalizeAcceptedPlanDecompositionFingerprintChild(child: IssueChildCreateInput) {
+  return Object.fromEntries(
+    Object.entries(child).filter(([key]) => !ACCEPTED_PLAN_DECOMPOSITION_FINGERPRINT_CHILD_METADATA_KEYS.has(key)),
+  );
+}
+
+function createAcceptedPlanDecompositionRequestFingerprint(input: {
+  acceptedPlanRevisionId: string;
+  children: IssueChildCreateInput[];
+}) {
+  const canonical = JSON.stringify(normalizeAcceptedPlanDecompositionFingerprintValue({
+    acceptedPlanRevisionId: input.acceptedPlanRevisionId,
+    children: input.children.map(normalizeAcceptedPlanDecompositionFingerprintChild),
+  }));
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function normalizeIssuePlanDecompositionChildIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && item.length > 0);
+}
+
+export function readAcceptedPlanConfirmationTarget(payload: unknown): {
+  revisionId: string;
+  key: string;
+  issueId: string;
+} | null {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const target = (payload as Record<string, unknown>).target;
+  if (!target || typeof target !== "object" || Array.isArray(target)) return null;
+  const record = target as Record<string, unknown>;
+  if (record.type !== "issue_document") return null;
+  const revisionId = readStringFromRecord(record, "revisionId");
+  const key = readStringFromRecord(record, "key");
+  const issueId = readStringFromRecord(record, "issueId");
+  if (!revisionId || !key || !issueId) return null;
+  return { revisionId, key, issueId };
+}
+
+async function resolveAcceptedPlanClaimOwner(input: {
+  dbOrTx: Pick<Db, "select">;
+  claim: Pick<typeof issuePlanDecompositions.$inferSelect, "ownerAgentId" | "ownerUserId" | "ownerRunId">;
+  actorAgentId?: string | null;
+  actorUserId?: string | null;
+  actorRunId?: string | null;
+}) {
+  const nextOwner = {
+    ownerAgentId: input.actorAgentId ?? null,
+    ownerUserId: input.actorUserId ?? null,
+    ownerRunId: input.actorRunId ?? null,
+  };
+  if (
+    input.claim.ownerAgentId === nextOwner.ownerAgentId
+    && input.claim.ownerUserId === nextOwner.ownerUserId
+    && input.claim.ownerRunId === nextOwner.ownerRunId
+  ) {
+    return nextOwner;
+  }
+
+  if (!input.claim.ownerRunId) {
+    return nextOwner;
+  }
+
+  const existingOwnerRun = await input.dbOrTx
+    .select({ status: heartbeatRuns.status })
+    .from(heartbeatRuns)
+    .where(eq(heartbeatRuns.id, input.claim.ownerRunId))
+    .then((rows) => rows[0] ?? null);
+  if (existingOwnerRun && !TERMINAL_HEARTBEAT_RUN_STATUSES.has(existingOwnerRun.status)) {
+    return {
+      ownerAgentId: input.claim.ownerAgentId,
+      ownerUserId: input.claim.ownerUserId,
+      ownerRunId: input.claim.ownerRunId,
+    };
+  }
+
+  return nextOwner;
+}
+
+async function findAcceptedPlanDocumentInteraction(
+  dbOrTx: Pick<Db, "select">,
+  input: {
+    companyId: string;
+    sourceIssueId: string;
+    acceptedPlanRevisionId: string;
+  },
+): Promise<AcceptedPlanDocumentInteraction | null> {
+  const rows = await dbOrTx
+    .select({
+      id: issueThreadInteractions.id,
+      payload: issueThreadInteractions.payload,
+    })
+    .from(issueThreadInteractions)
+    .where(and(
+      eq(issueThreadInteractions.companyId, input.companyId),
+      eq(issueThreadInteractions.issueId, input.sourceIssueId),
+      eq(issueThreadInteractions.kind, "request_confirmation"),
+      eq(issueThreadInteractions.status, "accepted"),
+    ))
+    .orderBy(desc(issueThreadInteractions.resolvedAt), desc(issueThreadInteractions.createdAt));
+
+  for (const row of rows) {
+    const target = readAcceptedPlanConfirmationTarget(row.payload);
+    if (
+      target?.issueId === input.sourceIssueId &&
+      target.key === "plan" &&
+      target.revisionId === input.acceptedPlanRevisionId
+    ) {
+      return { id: row.id };
+    }
+  }
+  return null;
+}
+
 function createIssueDependencyReadiness(issueId: string): IssueDependencyReadiness {
   return {
     issueId,
     blockerIssueIds: [],
     unresolvedBlockerIssueIds: [],
     unresolvedBlockerCount: 0,
+    pendingFinalizeBlockerIssueIds: [],
     allBlockersDone: true,
     isDependencyReady: true,
   };
 }
 
+/**
+ * Returns the set of execution-workspace ids whose most recent workspace operation
+ * is NOT a successful `workspace_finalize`. These workspaces have either an in-flight
+ * run, a failed finalize, or never reached the finalize barrier — dependents that
+ * read this workspace must wait until finalize succeeds.
+ *
+ * Workspaces with no recorded operations are considered finalized (nothing has
+ * touched them since they were realized).
+ */
+export async function listUnfinalizedExecutionWorkspaceIds(
+  dbOrTx: Pick<Db, "select">,
+  companyId: string,
+  executionWorkspaceIds: string[],
+): Promise<Set<string>> {
+  const unfinalized = new Set<string>();
+  if (executionWorkspaceIds.length === 0) return unfinalized;
+
+  // Pull every workspace op for the candidate workspaces and pick the latest per
+  // workspace in memory. Per-workspace LATERAL queries would be tighter, but the
+  // candidate set is tiny in practice (one workspace per blocker per readiness call).
+  const rows = await dbOrTx
+    .select({
+      executionWorkspaceId: workspaceOperations.executionWorkspaceId,
+      phase: workspaceOperations.phase,
+      status: workspaceOperations.status,
+      startedAt: workspaceOperations.startedAt,
+    })
+    .from(workspaceOperations)
+    .where(
+      and(
+        eq(workspaceOperations.companyId, companyId),
+        inArray(workspaceOperations.executionWorkspaceId, executionWorkspaceIds),
+      ),
+    );
+
+  const latestByWorkspace = new Map<string, { phase: string; status: string; startedAt: Date }>();
+  for (const row of rows) {
+    if (!row.executionWorkspaceId) continue;
+    const current = latestByWorkspace.get(row.executionWorkspaceId);
+    if (!current || row.startedAt > current.startedAt) {
+      latestByWorkspace.set(row.executionWorkspaceId, {
+        phase: row.phase,
+        status: row.status,
+        startedAt: row.startedAt,
+      });
+    }
+  }
+
+  for (const workspaceId of executionWorkspaceIds) {
+    const latest = latestByWorkspace.get(workspaceId);
+    if (!latest) continue; // no ops recorded → treat as finalized
+    if (latest.phase === "workspace_finalize" && latest.status === "succeeded") continue;
+    unfinalized.add(workspaceId);
+  }
+
+  return unfinalized;
+}
+
 async function listIssueDependencyReadinessMap(
   dbOrTx: Pick<Db, "select">,
   companyId: string,
@@ -404,6 +666,7 @@ async function listIssueDependencyReadinessMap(
       issueId: issueRelations.relatedIssueId,
       blockerIssueId: issueRelations.issueId,
       blockerStatus: issues.status,
+      blockerExecutionWorkspaceId: issues.executionWorkspaceId,
     })
     .from(issueRelations)
     .innerJoin(issues, eq(issueRelations.issueId, issues.id))
@@ -415,6 +678,21 @@ async function listIssueDependencyReadinessMap(
       ),
     );
 
+  // Collect executionWorkspaceIds of "done" blockers — these are the only ones
+  // subject to the workspace-finalize barrier. Blockers that aren't done already
+  // mark the dependent as not-ready and don't need a finalize check.
+  const doneBlockerWorkspaceIds = new Set<string>();
+  for (const row of blockerRows) {
+    if (row.blockerStatus === "done" && row.blockerExecutionWorkspaceId) {
+      doneBlockerWorkspaceIds.add(row.blockerExecutionWorkspaceId);
+    }
+  }
+  const unfinalizedWorkspaceIds = await listUnfinalizedExecutionWorkspaceIds(
+    dbOrTx,
+    companyId,
+    [...doneBlockerWorkspaceIds],
+  );
+
   for (const row of blockerRows) {
     const current = readinessMap.get(row.issueId) ?? createIssueDependencyReadiness(row.issueId);
     current.blockerIssueIds.push(row.blockerIssueId);
@@ -425,6 +703,21 @@ async function listIssueDependencyReadinessMap(
       current.unresolvedBlockerCount += 1;
       current.allBlockersDone = false;
       current.isDependencyReady = false;
+    } else if (
+      row.blockerExecutionWorkspaceId &&
+      unfinalizedWorkspaceIds.has(row.blockerExecutionWorkspaceId)
+    ) {
+      // Workspace-finalize barrier: the blocker's most recent run on its
+      // execution workspace hasn't recorded a successful workspace_finalize.
+      // Treat the dependent as not-ready until sync-back lands (or the run
+      // finalizes); a subsequent finalize wake will re-evaluate readiness.
+      // `allBlockersDone` is cleared too so that callers using it as a
+      // proxy for "this dependent can proceed" still see the gate.
+      current.unresolvedBlockerIssueIds.push(row.blockerIssueId);
+      current.unresolvedBlockerCount += 1;
+      current.pendingFinalizeBlockerIssueIds.push(row.blockerIssueId);
+      current.allBlockersDone = false;
+      current.isDependencyReady = false;
     }
     readinessMap.set(row.issueId, current);
   }
@@ -3891,45 +4184,33 @@ export function issueService(db: Db) {
         );
       if (candidates.length === 0) return [];
 
-      const candidateIds = candidates.map((candidate) => candidate.id);
-      const blockerRows = await db
-        .select({
-          issueId: issueRelations.relatedIssueId,
-          blockerIssueId: issueRelations.issueId,
-          blockerStatus: issues.status,
-        })
-        .from(issueRelations)
-        .innerJoin(issues, eq(issueRelations.issueId, issues.id))
-        .where(
-          and(
-            eq(issueRelations.companyId, blockerIssue.companyId),
-            eq(issueRelations.type, "blocks"),
-            inArray(issueRelations.relatedIssueId, candidateIds),
-          ),
-        );
+      const wakeableCandidates = candidates.filter(
+        (candidate) =>
+          candidate.assigneeAgentId && !["backlog", "done", "cancelled"].includes(candidate.status),
+      );
+      if (wakeableCandidates.length === 0) return [];
 
-      const blockersByIssueId = new Map<string, Array<{ blockerIssueId: string; blockerStatus: string }>>();
-      for (const row of blockerRows) {
-        const list = blockersByIssueId.get(row.issueId) ?? [];
-        list.push({ blockerIssueId: row.blockerIssueId, blockerStatus: row.blockerStatus });
-        blockersByIssueId.set(row.issueId, list);
-      }
+      // Defer to the unified readiness check so that a dependent only fires when
+      // (a) every blocker is done AND (b) every done blocker's workspace has
+      // recorded a successful workspace_finalize. The finalize hook also calls
+      // this function on completion, so a wake initially gated by an in-flight
+      // sync-back will re-fire once the restore lands locally.
+      const readinessMap = await listIssueDependencyReadinessMap(
+        db,
+        blockerIssue.companyId,
+        wakeableCandidates.map((candidate) => candidate.id),
+      );
 
-      return candidates
-        .filter((candidate) => candidate.assigneeAgentId && !["backlog", "done", "cancelled"].includes(candidate.status))
+      return wakeableCandidates
         .map((candidate) => {
-          const blockers = blockersByIssueId.get(candidate.id) ?? [];
-          return {
-            ...candidate,
-            blockerIssueIds: blockers.map((blocker) => blocker.blockerIssueId),
-            allBlockersDone: blockers.length > 0 && blockers.every((blocker) => blocker.blockerStatus === "done"),
-          };
+          const readiness = readinessMap.get(candidate.id) ?? createIssueDependencyReadiness(candidate.id);
+          return { candidate, readiness };
         })
-        .filter((candidate) => candidate.allBlockersDone)
-        .map((candidate) => ({
+        .filter(({ readiness }) => readiness.isDependencyReady && readiness.blockerIssueIds.length > 0)
+        .map(({ candidate, readiness }) => ({
           id: candidate.id,
           assigneeAgentId: candidate.assigneeAgentId!,
-          blockerIssueIds: candidate.blockerIssueIds,
+          blockerIssueIds: readiness.blockerIssueIds,
         }));
     },
 
@@ -4058,6 +4339,278 @@ export function issueService(db: Db) {
       };
     },
 
+    decomposeAcceptedPlan: async (
+      sourceIssueId: string,
+      data: AcceptedPlanDecompositionInput,
+    ) => {
+      const sourceIssue = await db
+        .select({
+          id: issues.id,
+          companyId: issues.companyId,
+          projectId: issues.projectId,
+          goalId: issues.goalId,
+        })
+        .from(issues)
+        .where(eq(issues.id, sourceIssueId))
+        .then((rows) => rows[0] ?? null);
+      if (!sourceIssue) throw notFound("Source issue not found");
+
+      const requestFingerprint = createAcceptedPlanDecompositionRequestFingerprint({
+        acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+        children: data.children,
+      });
+
+      const initialClaim = await db.transaction(async (tx) => {
+        await tx.execute(sql`select ${issues.id} from ${issues} where ${issues.id} = ${sourceIssue.id} for update`);
+
+        const belongsToPlanDocument = await tx
+          .select({ revisionId: documentRevisions.id })
+          .from(issueDocuments)
+          .innerJoin(documentRevisions, eq(issueDocuments.documentId, documentRevisions.documentId))
+          .where(and(
+            eq(issueDocuments.companyId, sourceIssue.companyId),
+            eq(issueDocuments.issueId, sourceIssue.id),
+            eq(issueDocuments.key, "plan"),
+            eq(documentRevisions.id, data.acceptedPlanRevisionId),
+          ))
+          .then((rows) => rows[0] ?? null);
+        if (!belongsToPlanDocument) {
+          throw unprocessable("acceptedPlanRevisionId must belong to the source issue's plan document");
+        }
+
+        const acceptedInteraction = await findAcceptedPlanDocumentInteraction(tx, {
+          companyId: sourceIssue.companyId,
+          sourceIssueId: sourceIssue.id,
+          acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+        });
+        if (!acceptedInteraction) {
+          throw unprocessable("acceptedPlanRevisionId must have an accepted plan confirmation");
+        }
+
+        const existing = await tx
+          .select()
+          .from(issuePlanDecompositions)
+          .where(and(
+            eq(issuePlanDecompositions.companyId, sourceIssue.companyId),
+            eq(issuePlanDecompositions.sourceIssueId, sourceIssue.id),
+            eq(issuePlanDecompositions.acceptedPlanRevisionId, data.acceptedPlanRevisionId),
+          ))
+          .then((rows) => rows[0] ?? null);
+
+        const now = new Date();
+        if (!existing) {
+          const [created] = await tx
+            .insert(issuePlanDecompositions)
+            .values({
+              companyId: sourceIssue.companyId,
+              sourceIssueId: sourceIssue.id,
+              acceptedPlanRevisionId: data.acceptedPlanRevisionId,
+              acceptedInteractionId: acceptedInteraction.id,
+              status: "in_flight",
+              requestFingerprint,
+              requestedChildCount: data.children.length,
+              requestedChildren: data.children as unknown as Record<string, unknown>[],
+              childIssueIds: [],
+              ownerAgentId: data.actorAgentId ?? null,
+              ownerUserId: data.actorUserId ?? null,
+              ownerRunId: data.actorRunId ?? null,
+              updatedAt: now,
+            })
+            .returning();
+          if (!created) throw new Error("Failed to create accepted-plan decomposition claim");
+          return created;
+        }
+
+        if (existing.requestFingerprint !== requestFingerprint) {
+          throw conflict("Accepted-plan decomposition already exists for this revision with a different child set");
+        }
+
+        return existing;
+      });
+
+      let currentClaim = initialClaim;
+      const newlyCreatedIssues: Array<typeof issues.$inferSelect> = [];
+
+      while (true) {
+        const step = await db.transaction(async (tx) => {
+          await tx.execute(
+            sql`select ${issuePlanDecompositions.id}
+                from ${issuePlanDecompositions}
+                where ${issuePlanDecompositions.id} = ${currentClaim.id}
+                for update`,
+          );
+
+          const claim = await tx
+            .select()
+            .from(issuePlanDecompositions)
+            .where(eq(issuePlanDecompositions.id, currentClaim.id))
+            .then((rows) => rows[0] ?? null);
+          if (!claim) throw notFound("Accepted-plan decomposition claim not found");
+          if (claim.requestFingerprint !== requestFingerprint) {
+            throw conflict("Accepted-plan decomposition already exists for this revision with a different child set");
+          }
+
+          const existingChildIssueIds = normalizeIssuePlanDecompositionChildIds(claim.childIssueIds);
+          if (claim.status === "completed" || existingChildIssueIds.length >= data.children.length) {
+            const nextIds = existingChildIssueIds.slice(0, data.children.length);
+            if (claim.status === "completed" && nextIds.length === data.children.length) {
+              return {
+                claim,
+                createdIssue: null,
+              };
+            }
+
+            const completedAt = claim.completedAt ?? new Date();
+            const ownerPatch = await resolveAcceptedPlanClaimOwner({
+              dbOrTx: tx,
+              claim,
+              actorAgentId: data.actorAgentId,
+              actorUserId: data.actorUserId,
+              actorRunId: data.actorRunId,
+            });
+            const [completed] = await tx
+              .update(issuePlanDecompositions)
+              .set({
+                status: "completed",
+                childIssueIds: nextIds,
+                completedAt,
+                ...ownerPatch,
+                updatedAt: completedAt,
+              })
+              .where(eq(issuePlanDecompositions.id, claim.id))
+              .returning();
+            if (!completed) throw new Error("Failed to complete accepted-plan decomposition claim");
+            return {
+              claim: completed,
+              createdIssue: null,
+            };
+          }
+
+          const nextChildInput = data.children[existingChildIssueIds.length];
+          if (!nextChildInput) {
+            throw new Error("Accepted-plan decomposition child cursor moved past the requested children");
+          }
+
+          const createdChild = await issueService(tx as unknown as Db).createChild(sourceIssue.id, nextChildInput);
+          const nextIds = [...existingChildIssueIds, createdChild.issue.id];
+          const now = new Date();
+          const nextStatus = nextIds.length === data.children.length ? "completed" : "in_flight";
+          const ownerPatch = await resolveAcceptedPlanClaimOwner({
+            dbOrTx: tx,
+            claim,
+            actorAgentId: data.actorAgentId,
+            actorUserId: data.actorUserId,
+            actorRunId: data.actorRunId,
+          });
+          const [updatedClaim] = await tx
+            .update(issuePlanDecompositions)
+            .set({
+              status: nextStatus,
+              childIssueIds: nextIds,
+              completedAt: nextStatus === "completed" ? now : null,
+              ...ownerPatch,
+              updatedAt: now,
+            })
+            .where(eq(issuePlanDecompositions.id, claim.id))
+            .returning();
+          if (!updatedClaim) throw new Error("Failed to persist accepted-plan decomposition progress");
+          return {
+            claim: updatedClaim,
+            createdIssue: createdChild.issue,
+          };
+        });
+
+        currentClaim = step.claim;
+        if (step.createdIssue) {
+          newlyCreatedIssues.push(step.createdIssue);
+        }
+        if (step.claim.status === "completed") break;
+      }
+
+      const childIssueIds = normalizeIssuePlanDecompositionChildIds(currentClaim.childIssueIds);
+      const childIssueRows = childIssueIds.length > 0
+        ? await db
+            .select()
+            .from(issues)
+            .where(and(eq(issues.companyId, sourceIssue.companyId), inArray(issues.id, childIssueIds)))
+        : [];
+      const childIssueMap = new Map(childIssueRows.map((row) => [row.id, row]));
+      const orderedChildIssues = childIssueIds
+        .map((childIssueId) => childIssueMap.get(childIssueId))
+        .filter((row): row is typeof issues.$inferSelect => Boolean(row));
+
+      const decomposition = serializeAcceptedPlanDecomposition(currentClaim);
+
+      return {
+        decomposition,
+        childIssueIds: decomposition.childIssueIds,
+        childIssues: orderedChildIssues,
+        newlyCreatedIssues,
+      };
+    },
+
+    listAcceptedPlanDecompositions: async (sourceIssueId: string) => {
+      const sourceIssue = await db
+        .select({ id: issues.id, companyId: issues.companyId })
+        .from(issues)
+        .where(eq(issues.id, sourceIssueId))
+        .then((rows) => rows[0] ?? null);
+      if (!sourceIssue) return [];
+
+      const rows = await db
+        .select({
+          decomposition: issuePlanDecompositions,
+          revisionNumber: documentRevisions.revisionNumber,
+        })
+        .from(issuePlanDecompositions)
+        .leftJoin(
+          documentRevisions,
+          eq(documentRevisions.id, issuePlanDecompositions.acceptedPlanRevisionId),
+        )
+        .where(and(
+          eq(issuePlanDecompositions.companyId, sourceIssue.companyId),
+          eq(issuePlanDecompositions.sourceIssueId, sourceIssue.id),
+        ))
+        .orderBy(desc(issuePlanDecompositions.createdAt));
+
+      if (rows.length === 0) return [];
+
+      const allChildIds = new Set<string>();
+      for (const row of rows) {
+        for (const childId of normalizeIssuePlanDecompositionChildIds(row.decomposition.childIssueIds)) {
+          allChildIds.add(childId);
+        }
+      }
+
+      const childIssueRows = allChildIds.size > 0
+        ? await db
+            .select({
+              id: issues.id,
+              identifier: issues.identifier,
+              title: issues.title,
+              status: issues.status,
+              priority: issues.priority,
+              assigneeAgentId: issues.assigneeAgentId,
+              assigneeUserId: issues.assigneeUserId,
+            })
+            .from(issues)
+            .where(and(eq(issues.companyId, sourceIssue.companyId), inArray(issues.id, Array.from(allChildIds))))
+        : [];
+      const childIssueMap = new Map(childIssueRows.map((row) => [row.id, row]));
+
+      return rows.map((row) => {
+        const decomposition = serializeAcceptedPlanDecomposition(row.decomposition);
+        const childIds = decomposition.childIssueIds;
+        return {
+          ...decomposition,
+          acceptedPlanRevisionNumber: row.revisionNumber ?? null,
+          childIssues: childIds
+            .map((childId) => childIssueMap.get(childId) ?? null)
+            .filter((entry): entry is NonNullable<typeof entry> => entry !== null),
+        };
+      });
+    },
+
     create: async (
       companyId: string,
       data: IssueCreateInput,

server/src/services/recovery/service.ts

@@ -159,6 +159,54 @@ function didAutomaticRecoveryFail(
     );
 }
 
+const TRANSIENT_INFRA_CONTINUATION_ERROR_CODES = new Set<string>([
+  "adapter_failed",
+  "codex_transient_upstream",
+  "claude_transient_upstream",
+  "timeout",
+]);
+
+const NON_RETRYABLE_CONTINUATION_ERROR_CODES = new Set<string>([
+  "agent_not_invokable",
+  "agent_not_found",
+  "budget_blocked",
+  "budget_exhausted",
+  "issue_paused",
+  "issue_dependencies_blocked",
+]);
+
+const CONTINUATION_RECOVERY_TRANSIENT_MAX_ATTEMPTS = 3;
+const CONTINUATION_RECOVERY_DEFAULT_MAX_ATTEMPTS = 1;
+const CONTINUATION_RECOVERY_TRANSIENT_BASE_BACKOFF_MS = 60_000;
+
+type ContinuationRetryClassification = {
+  kind: "transient_infra" | "non_retryable" | "default";
+  maxAttempts: number;
+  baseBackoffMs: number;
+  errorCode: string | null;
+};
+
+function classifyContinuationFailure(latestRun: LatestIssueRun): ContinuationRetryClassification {
+  const errorCode = readNonEmptyString(latestRun?.errorCode);
+  if (errorCode && NON_RETRYABLE_CONTINUATION_ERROR_CODES.has(errorCode)) {
+    return { kind: "non_retryable", maxAttempts: 0, baseBackoffMs: 0, errorCode };
+  }
+  if (errorCode && TRANSIENT_INFRA_CONTINUATION_ERROR_CODES.has(errorCode)) {
+    return {
+      kind: "transient_infra",
+      maxAttempts: CONTINUATION_RECOVERY_TRANSIENT_MAX_ATTEMPTS,
+      baseBackoffMs: CONTINUATION_RECOVERY_TRANSIENT_BASE_BACKOFF_MS,
+      errorCode,
+    };
+  }
+  return {
+    kind: "default",
+    maxAttempts: CONTINUATION_RECOVERY_DEFAULT_MAX_ATTEMPTS,
+    baseBackoffMs: 0,
+    errorCode,
+  };
+}
+
 function successfulRunHandoffRecoveryEvidence(latestRun: LatestIssueRun): SuccessfulRunHandoffRecoveryEvidence | null {
   if (!latestRun) return null;
 
@@ -438,6 +486,54 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
       .then((rows) => rows[0] ?? null);
   }
 
+  async function summarizeRecentContinuationRetries(
+    companyId: string,
+    issueId: string,
+    errorCodeToMatch: string | null,
+  ) {
+    const rows = await db
+      .select({
+        id: heartbeatRuns.id,
+        status: heartbeatRuns.status,
+        errorCode: heartbeatRuns.errorCode,
+        contextSnapshot: heartbeatRuns.contextSnapshot,
+        finishedAt: heartbeatRuns.finishedAt,
+      })
+      .from(heartbeatRuns)
+      .where(
+        and(
+          eq(heartbeatRuns.companyId, companyId),
+          sql`${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${issueId}`,
+        ),
+      )
+      .orderBy(desc(heartbeatRuns.createdAt), desc(heartbeatRuns.id))
+      .limit(10);
+
+    let consecutive = 0;
+    let latestFinishedAt: Date | null = null;
+    for (const row of rows) {
+      const ctx = parseObject(row.contextSnapshot);
+      const retryReason = readNonEmptyString(ctx.retryReason);
+      if (retryReason !== "issue_continuation_needed") break;
+      if (
+        !UNSUCCESSFUL_HEARTBEAT_RUN_TERMINAL_STATUSES.includes(
+          row.status as (typeof UNSUCCESSFUL_HEARTBEAT_RUN_TERMINAL_STATUSES)[number],
+        )
+      ) {
+        break;
+      }
+
+      const rowErrorCode = readNonEmptyString(row.errorCode);
+      if (errorCodeToMatch !== rowErrorCode) {
+        break;
+      }
+
+      consecutive += 1;
+      if (latestFinishedAt === null) latestFinishedAt = row.finishedAt ?? null;
+    }
+    return { consecutive, latestFinishedAt };
+  }
+
   async function hasActiveExecutionPath(companyId: string, issueId: string) {
     const [run, deferredWake] = await Promise.all([
       db
@@ -2545,24 +2641,69 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
         }
         continue;
       }
-      if (didAutomaticRecoveryFail(latestRun, "issue_continuation_needed")) {
-        const failureSummary = summarizeRunFailureForIssueComment(latestRun);
-        const updated = await escalateStrandedAssignedIssue({
-          issue,
-          previousStatus: "in_progress",
-          latestRun,
-          comment:
-            "Paperclip automatically retried continuation for this assigned `in_progress` issue after its live " +
-            `execution disappeared, but it still has no live execution path.${failureSummary ?? ""} ` +
-            "Moving it to `blocked` so it is visible for intervention.",
-        });
-        if (updated) {
-          result.escalated += 1;
-          result.issueIds.push(issue.id);
-        } else {
-          result.skipped += 1;
+      if (isUnsuccessfulTerminalIssueRun(latestRun)) {
+        const classification = classifyContinuationFailure(latestRun);
+
+        if (classification.kind === "non_retryable") {
+          const failureSummary = summarizeRunFailureForIssueComment(latestRun);
+          const updated = await escalateStrandedAssignedIssue({
+            issue,
+            previousStatus: "in_progress",
+            latestRun,
+            comment:
+              "Paperclip detected a non-retryable failure on this issue's continuation run " +
+              `(\`${classification.errorCode}\`). Skipping automatic retries and moving it to \`blocked\` ` +
+              `so it is visible for intervention.${failureSummary ?? ""}`,
+          });
+          if (updated) {
+            result.escalated += 1;
+            result.issueIds.push(issue.id);
+          } else {
+            result.skipped += 1;
+          }
+          continue;
+        }
+
+        if (didAutomaticRecoveryFail(latestRun, "issue_continuation_needed")) {
+          const { consecutive, latestFinishedAt } = await summarizeRecentContinuationRetries(
+            issue.companyId,
+            issue.id,
+            classification.errorCode,
+          );
+          if (consecutive >= classification.maxAttempts) {
+            const failureSummary = summarizeRunFailureForIssueComment(latestRun);
+            const attemptCopy = consecutive <= 1 ? "" : ` (${consecutive}× attempts)`;
+            const causeCopy = classification.errorCode
+              ? ` Latest cause: \`${classification.errorCode}\`.`
+              : "";
+            const updated = await escalateStrandedAssignedIssue({
+              issue,
+              previousStatus: "in_progress",
+              latestRun,
+              comment:
+                "Paperclip automatically retried continuation for this assigned `in_progress` issue after its live " +
+                `execution disappeared, but it still has no live execution path${attemptCopy}.${causeCopy}${failureSummary ?? ""} ` +
+                "Moving it to `blocked` so it is visible for intervention.",
+            });
+            if (updated) {
+              result.escalated += 1;
+              result.issueIds.push(issue.id);
+            } else {
+              result.skipped += 1;
+            }
+            continue;
+          }
+
+          if (classification.baseBackoffMs > 0 && latestFinishedAt) {
+            const elapsed = Date.now() - latestFinishedAt.getTime();
+            const requiredDelay = classification.baseBackoffMs *
+              Math.pow(2, Math.max(0, consecutive - 1));
+            if (elapsed < requiredDelay) {
+              result.skipped += 1;
+              continue;
+            }
+          }
         }
-        continue;
       }
 
       if (await isInvocationBudgetBlocked(issue, agentId)) {
@@ -3248,7 +3389,7 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
     let escalation: Awaited<ReturnType<typeof issuesSvc.create>>;
     try {
       escalation = await issuesSvc.create(issue.companyId, {
-        title: `Unblock liveness incident for ${recoveryIssue.identifier ?? recoveryIssue.title}`,
+        title: `Unblock liveness incident for ${issue.identifier ?? issue.id}`,
         description: buildLivenessEscalationDescription(input.finding),
         status: "todo",
         priority: "high",