fix: pass plugin workers to issue tree resume (#13757)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Issue tree controls can resume tasks and wake their assigned agents.
> - A sandbox-backed run needs the shared plugin worker manager to
acquire its lease.
> - The issue tree route constructed a heartbeat service without that
manager.
> - A ready sandbox provider therefore appeared offline and the resumed
run failed setup.
> - This pull request passes the existing manager to the route and
distinguishes missing wiring from a stopped worker.

## Linked Issues or Issue Description

Related implementation: #10262 identified this wiring defect in several
dispatch paths. This PR applies the issue-tree resume fix to current
master and adds coverage in the current route and runtime suites. The
other dispatch paths remain in the scope of that earlier PR.

**What happened?**

Resuming a paused issue subtree can fail to acquire a sandbox lease even
while its provider plugin is ready and its worker is running. The error
says the worker is not running because this route's heartbeat service
never received the process's worker manager.

**Expected behavior**

Resumed work uses the same worker manager as normal issue dispatch.
Missing wiring and an actually stopped worker produce distinct
diagnostic errors.

**Steps to reproduce**

1. Configure an agent with a plugin-backed sandbox environment and start
the provider worker.
2. Pause a subtree assigned to that agent.
3. Release the hold with `metadata.wakeAgents: true`.
4. The old route constructs an unwired heartbeat service and the resumed
run fails during setup.

**Paperclip version or commit**

Reproduced by source inspection and regression coverage against
`9d19f98b50`.

**Deployment mode**

Server with a plugin-backed sandbox environment.

## What Changed

- Pass the process's plugin worker manager from `createApp` through
issue tree controls to heartbeat dispatch.
- Check for a missing manager before reporting the sandbox worker as
stopped.
- Exercise the resume request with a shared manager and cover both
runtime failure cases. Model a stopped worker explicitly in the existing
infrastructure-retry fixture. Existing board and company access checks
remain covered.

## Verification

- Targeted Vitest route/runtime/recovery suites: 17 passed; 384 native
database tests skipped because embedded Postgres cannot start on this
host.
- Direct server `tsc --noEmit` passed.
- `pnpm -r typecheck`, server typecheck wrapper, and `pnpm build` were
attempted. Their runner dependency requires `cargo`, which is absent on
this host. CI must pass these checks before merge.
- Full `pnpm test:run` was attempted. The general server stage reported
8,146 passed, 4,747 skipped, and 14 failed tests across 35 failed
suites. Failures were embedded Postgres startup errors (with related
teardown errors) and 10 cache-directory rename failures on this macOS
host. The local run stopped there; Linux CI must pass the complete suite
before merge.
- All CI gates are green, including the native database recovery suite,
workspace typecheck/build, runner checks, and browser tests. Greptile
reviewed the current commit at 5/5 with no unresolved threads.
- No live provider operations were performed by these tests.

## Risks

Low risk: dependency forwarding and error classification only. The route
retains board authorization, company boundaries, hold semantics, and
existing cancellation/replay guards. The change does not replace a
sandbox or discard a retained lease. No schema or API shape changes.

## Model Used

OpenAI GPT-6 (Codex), with reasoning, repository tooling, and code
execution.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] This fixes existing behavior and does not add planned core
features
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have described the issue in-PR following the bug issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no private ticket
or instance data
- [x] Targeted local tests pass; full-suite and toolchain limits are
recorded above
- [x] I have added or updated tests where applicable
- [x] No documentation changes are needed for dependency forwarding
- [x] I have considered and documented risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all reviewer comments before requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

Author: devinfoley

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

@@ -494,6 +494,29 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
     },
   );
 
+  it("reports an unwired manager separately from a stopped sandbox worker", async () => {
+    const { companyId, environment, runId } = await seedReusablePluginSandboxLease();
+    const input = {
+      companyId,
+      environment,
+      issueId: null,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    };
+    const runtimeWithoutManager = environmentRuntimeService(db);
+    await expect(runtimeWithoutManager.acquireRunLease(input))
+      .rejects.toThrow("sandbox plugin workers are unavailable in this server process");
+
+    const offlineManager = { isRunning: () => false, call: vi.fn() } as unknown as PluginWorkerManager;
+    const runtimeWithStoppedWorker = environmentRuntimeService(db, {
+      pluginWorkerManager: offlineManager,
+      pluginWorkerReadyTimeoutMs: 0,
+    });
+    await expect(runtimeWithStoppedWorker.acquireRunLease(input))
+      .rejects.toThrow("its worker is not running");
+    expect(offlineManager.call).not.toHaveBeenCalled();
+  });
+
   it("retains a successful reusable sandbox lease without stopping the provider resource", async () => {
     const { pluginId, runId, reusableLease } = await seedReusablePluginSandboxLease();
     const workerManager = {

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

@@ -212,6 +212,7 @@ import {
   redactDetectedSuccessfulRunProgressSummaryForBoard,
   redactSuccessfulRunHandoffEvidence,
 } from "../services/heartbeat.ts";
+import type { PluginWorkerManager } from "../services/plugin-worker-manager.ts";
 import {
   claimNativeRestartRecoveries,
   currentNativeControllerIdentity,
@@ -4221,8 +4222,9 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   });
 
   it("schedules an infra retry for a setup failure caused by a transient sandbox provider worker restart", async () => {
-    // Reproduces the production incident: the "Kubernetes Sandbox" plugin
-    // worker was mid-restart when a run tried to acquire a lease. The lease
+    // Model a configured plugin manager whose worker is mid-restart when
+    // a run tries to acquire a lease. A missing manager is a wiring error,
+    // not a worker restart. The lease
     // acquisition fails BEFORE the adapter is ever dispatched (no call to
     // mockAdapterExecute), so this hits the setup-failure catch (errorCode
     // "setup_failed") rather than the adapter-failure catch. The condition is
@@ -4342,16 +4344,23 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       .set({ status: "in_progress" })
       .where(eq(issues.id, issueId));
 
-    const heartbeat = heartbeatService(db);
+    const heartbeat = heartbeatService(db, {
+      pluginWorkerManager: {
+        isRunning: () => false,
+        call: vi.fn(),
+      } as unknown as PluginWorkerManager,
+    });
     await heartbeat.resumeQueuedRuns();
 
+    // The real manager waits up to five seconds for worker readiness before
+    // lease acquisition fails and the heartbeat can schedule its retry.
     const runs = await waitForValue(async () => {
       const rows = await db
         .select()
         .from(heartbeatRuns)
         .where(eq(heartbeatRuns.agentId, agentId));
       return rows.length >= 2 ? rows : null;
-    });
+    }, 10_000);
     expect(runs).toHaveLength(2);
 
     const failedRun = runs?.find((row) => row.id === runId);

server/src/__tests__/issue-tree-control-routes.test.ts

@@ -1,4 +1,5 @@
 import express from "express";
+import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
 import { PgDialect } from "drizzle-orm/pg-core";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -28,14 +29,19 @@ const mockHeartbeatService = vi.hoisted(() => ({
   wakeup: vi.fn(),
 }));
 
+const mockHeartbeatFactory = vi.hoisted(() => vi.fn());
+
 vi.mock("../services/index.js", () => ({
-  heartbeatService: () => mockHeartbeatService,
+  heartbeatService: mockHeartbeatFactory,
   issueService: () => mockIssueService,
   issueTreeControlService: () => mockTreeControlService,
   logActivity: mockLogActivity,
 }));
 
-async function createApp(actor: Record<string, unknown>) {
+async function createApp(
+  actor: Record<string, unknown>,
+  pluginWorkerManager?: PluginWorkerManager,
+) {
   const [{ errorHandler }, { issueTreeControlRoutes }] = await Promise.all([
     import("../middleware/index.js"),
     import("../routes/issue-tree-control.js"),
@@ -52,14 +58,15 @@ async function createApp(actor: Record<string, unknown>) {
     where: (predicate: unknown) => { mockReplayWhere(predicate); return mockReplayBlocks(); },
     limit: mockReplayBlocks,
   };
-  app.use("/api", issueTreeControlRoutes({ select: () => query } as any));
+  app.use("/api", issueTreeControlRoutes({ select: () => query } as any, { pluginWorkerManager }));
   app.use(errorHandler);
   return app;
 }
 
 describe("issue tree control routes", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    mockHeartbeatFactory.mockReturnValue(mockHeartbeatService);
     mockReplayBlocks.mockResolvedValue([]);
     mockExecutionBlocker.mockResolvedValue(null);
     mockTreeControlService.getHold.mockResolvedValue(null);
@@ -185,6 +192,39 @@ describe("issue tree control routes", () => {
     },
   );
 
+  it("resumes sandbox-backed work through the shared plugin worker manager", async () => {
+    const rootId = "11111111-1111-4111-8111-111111111111";
+    const holdId = "33333333-3333-4333-8333-333333333333";
+    const pluginWorkerManager = { isRunning: () => true } as unknown as PluginWorkerManager;
+    mockHeartbeatFactory.mockImplementation((_db, options) => ({
+      ...mockHeartbeatService,
+      wakeup: async (...args: unknown[]) => {
+        // Lease acquisition needs the process's manager, even when its worker
+        // is already running. A service without it cannot dispatch this run.
+        expect(options?.pluginWorkerManager).toBe(pluginWorkerManager);
+        return mockHeartbeatService.wakeup(...args);
+      },
+    }));
+    mockIssueService.getById.mockResolvedValue({
+      id: rootId, companyId: "company-2", status: "todo", assigneeAgentId: "agent-parent",
+    });
+    mockTreeControlService.releaseHold.mockResolvedValue({
+      id: holdId, mode: "pause", status: "released", members: [{ issueId: rootId }],
+    });
+    const app = await createApp({
+      type: "board", userId: "user-1", companyIds: ["company-2"], source: "session",
+    }, pluginWorkerManager);
+    const response = await request(app)
+      .post(`/api/issues/${rootId}/tree-holds/${holdId}/release`)
+      .send({ metadata: { wakeAgents: true } });
+    expect(response.status).toBe(200);
+    expect(response.body.wakeFailures).toBeUndefined();
+    expect(mockHeartbeatService.wakeup).toHaveBeenCalledWith("agent-parent", expect.objectContaining({
+      reason: "issue_tree_resumed",
+      contextSnapshot: expect.objectContaining({ issueId: rootId, source: "issue.tree_resume" }),
+    }));
+  });
+
   it("reports wake failures without undoing release or skipping other assignees", async () => {
     const rootId = "11111111-1111-4111-8111-111111111111";
     const holdId = "33333333-3333-4333-8333-333333333333";

server/src/app.ts

@@ -740,7 +740,7 @@ export async function createApp(
   api.use(projectToolRoutes(db));
   api.use(projectRoutes(db));
   api.use(caseRoutes(db, opts.storageService));
-  api.use(issueTreeControlRoutes(db));
+  api.use(issueTreeControlRoutes(db, { pluginWorkerManager: workerManager }));
   api.use(fileResourceRoutes(db));
   api.use(routineRoutes(db, { pluginWorkerManager: workerManager }));
   api.use(pipelineRoutes(db));

server/src/routes/issue-tree-control.ts

@@ -22,6 +22,8 @@ import {
 } from "../services/index.js";
 import { assertBoard, getAccessibleResource, getActorInfo } from "./authz.js";
 
+import type { PluginWorkerManager } from "../services/plugin-worker-manager.js";
+
 const TREE_RUN_CANCELLATION_RESPONSE_WAIT_MS = 1_000;
 const RESUME_EXECUTABLE_STATUSES = ["todo", "in_progress", "in_review"];
 
@@ -43,11 +45,16 @@ async function waitForRunCancellationTasks(tasks: Promise<void>[]) {
   }
 }
 
-export function issueTreeControlRoutes(db: Db) {
+export function issueTreeControlRoutes(
+  db: Db,
+  options: { pluginWorkerManager?: PluginWorkerManager } = {},
+) {
   const router = Router();
   const issuesSvc = issueService(db);
   const treeControlSvc = issueTreeControlService(db);
-  const heartbeat = heartbeatService(db);
+  const heartbeat = heartbeatService(db, {
+    pluginWorkerManager: options.pluginWorkerManager,
+  });
 
   async function resolveRootIssue(req: Request) {
     const rootIssueId = req.params.id as string;

server/src/services/environment-runtime.ts

@@ -1785,14 +1785,16 @@ function createSandboxEnvironmentDriver(
             `Sandbox provider "${parsed.config.provider}" is installed via plugin "${pluginProvider.resolved.plugin.pluginKey}", but that plugin is currently ${pluginProvider.resolved.plugin.status}.`,
           );
         }
-        if (pluginProvider.state === "worker_unavailable") {
+        // A missing manager is a wiring failure, even when the plugin worker
+        // is healthy elsewhere in this process. Check it before worker state.
+        if (!pluginWorkerManager) {
           throw new Error(
-            `Sandbox provider "${parsed.config.provider}" is installed via plugin "${pluginProvider.resolved.plugin.pluginKey}", but its worker is not running.`,
+            `Sandbox provider "${parsed.config.provider}" is installed, but sandbox plugin workers are unavailable in this server process.`,
           );
         }
-        if (!pluginWorkerManager) {
+        if (pluginProvider.state === "worker_unavailable") {
           throw new Error(
-            `Sandbox provider "${parsed.config.provider}" is installed, but sandbox plugin workers are unavailable in this server process.`,
+            `Sandbox provider "${parsed.config.provider}" is installed via plugin "${pluginProvider.resolved.plugin.pluginKey}", but its worker is not running.`,
           );
         }