Generalize sandbox provider core for plugin-only providers (#4449)

## Thinking Path

> - Paperclip is a control plane, so optional execution providers should
sit at the plugin edge instead of hardcoding provider-specific behavior
into core shared/server/ui layers.
> - Sandbox environments are already first-class, and the fake provider
proves the built-in path; the remaining gap was that real providers
still leaked provider-specific config and runtime assumptions into core.
> - That coupling showed up in config normalization, secret persistence,
capabilities reporting, lease reconstruction, and the board UI form
fields.
> - As long as core knew about those provider-shaped details, shipping a
provider as a pure third-party plugin meant every new provider would
still require host changes.
> - This pull request generalizes the sandbox provider seam around
schema-driven plugin metadata and generic secret-ref handling.
> - The runtime and UI now consume provider metadata generically, so
core only special-cases the built-in fake provider while third-party
providers can live entirely in plugins.

## What Changed

- Added generic sandbox-provider capability metadata so plugin-backed
providers can expose `configSchema` through shared environment support
and the environments capabilities API.
- Reworked sandbox config normalization/persistence/runtime resolution
to handle schema-declared secret-ref fields generically, storing them as
Paperclip secrets and resolving them for probe/execute/release flows.
- Generalized plugin sandbox runtime handling so provider validation,
reusable-lease matching, lease reconstruction, and plugin worker calls
all operate on provider-agnostic config instead of provider-shaped
branches.
- Replaced hardcoded sandbox provider form fields in Company Settings
with schema-driven rendering and blocked agent environment selection
from the built-in fake provider.
- Added regression coverage for the generic seam across shared support
helpers plus environment config, probe, routes, runtime, and
sandbox-provider runtime tests.

## Verification

- `pnpm vitest --run packages/shared/src/environment-support.test.ts
server/src/__tests__/environment-config.test.ts
server/src/__tests__/environment-probe.test.ts
server/src/__tests__/environment-routes.test.ts
server/src/__tests__/environment-runtime.test.ts
server/src/__tests__/sandbox-provider-runtime.test.ts`
- `pnpm -r typecheck`

## Risks

- Plugin sandbox providers now depend more heavily on accurate
`configSchema` declarations; incorrect schemas can misclassify
secret-bearing fields or omit required config.
- Reusable lease matching is now metadata-driven for plugin-backed
providers, so providers that fail to persist stable metadata may
reprovision instead of resuming an existing lease.
- The UI form is now fully schema-driven for plugin-backed sandbox
providers; provider manifests without good defaults or descriptions may
produce a rougher operator experience.

## Model Used

- OpenAI Codex via `codex_local`
- Model ID: `gpt-5.4`
- Reasoning effort: `high`
- Context window observed in runtime session metadata: `258400` tokens
- Capabilities used: terminal tool execution, git, and local code/test
inspection

## 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] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

.gitignore

@@ -3,6 +3,7 @@ node_modules/
 **/node_modules
 **/node_modules/
 dist/
+ui/storybook-static/
 .env
 *.tsbuildinfo
 drizzle/meta/

Dockerfile

@@ -29,6 +29,7 @@ COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-
 COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
 COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
 COPY packages/plugins/sdk/package.json packages/plugins/sdk/
+COPY packages/plugins/paperclip-plugin-fake-sandbox/package.json packages/plugins/paperclip-plugin-fake-sandbox/
 COPY patches/ patches/
 
 RUN pnpm install --frozen-lockfile

cli/src/__tests__/company-import-export-e2e.test.ts

@@ -398,10 +398,11 @@ describeEmbeddedPostgres("paperclipai company import/export e2e", () => {
       apiBase,
       `/api/companies/${importedNew.company.id}/issues`,
     );
+    const importedMatchingIssues = importedIssues.filter((issue) => issue.title === sourceIssue.title);
 
     expect(importedAgents.map((agent) => agent.name)).toContain(sourceAgent.name);
     expect(importedProjects.map((project) => project.name)).toContain(sourceProject.name);
-    expect(importedIssues.map((issue) => issue.title)).toContain(sourceIssue.title);
+    expect(importedMatchingIssues).toHaveLength(1);
 
     const previewExisting = await runCliJson<{
       errors: string[];
@@ -471,11 +472,13 @@ describeEmbeddedPostgres("paperclipai company import/export e2e", () => {
       apiBase,
       `/api/companies/${importedNew.company.id}/issues`,
     );
+    const twiceImportedMatchingIssues = twiceImportedIssues.filter((issue) => issue.title === sourceIssue.title);
 
     expect(twiceImportedAgents).toHaveLength(2);
     expect(new Set(twiceImportedAgents.map((agent) => agent.name)).size).toBe(2);
     expect(twiceImportedProjects).toHaveLength(2);
-    expect(twiceImportedIssues).toHaveLength(2);
+    expect(twiceImportedMatchingIssues).toHaveLength(2);
+    expect(new Set(twiceImportedMatchingIssues.map((issue) => issue.identifier)).size).toBe(2);
 
     const zipPath = path.join(tempRoot, "exported-company.zip");
     const portableFiles: Record<string, string> = {};

cli/src/commands/client/issue.ts

@@ -61,6 +61,7 @@ interface IssueUpdateOptions extends BaseClientOptions {
 interface IssueCommentOptions extends BaseClientOptions {
   body: string;
   reopen?: boolean;
+  resume?: boolean;
 }
 
 interface IssueCheckoutOptions extends BaseClientOptions {
@@ -241,12 +242,14 @@ export function registerIssueCommands(program: Command): void {
       .argument("<issueId>", "Issue ID")
       .requiredOption("--body <text>", "Comment body")
       .option("--reopen", "Reopen if issue is done/cancelled")
+      .option("--resume", "Request explicit follow-up and wake the assignee when resumable")
       .action(async (issueId: string, opts: IssueCommentOptions) => {
         try {
           const ctx = resolveCommandContext(opts);
           const payload = addIssueCommentSchema.parse({
             body: opts.body,
             reopen: opts.reopen,
+            resume: opts.resume,
           });
           const comment = await ctx.api.post<IssueComment>(`/api/issues/${issueId}/comments`, payload);
           printOutput(comment, { json: ctx.json });

doc/SPEC-implementation.md

@@ -37,7 +37,7 @@ These decisions close open questions from `SPEC.md` for V1.
 | Visibility | Full visibility to board and all agents in same company |
 | Communication | Tasks + comments only (no separate chat system) |
 | Task ownership | Single assignee; atomic checkout required for `in_progress` transition |
-| Recovery | No automatic reassignment; work recovery stays manual/explicit |
+| Recovery | No automatic reassignment; control-plane recovery may retry lost execution continuity once, then uses explicit recovery issues or human escalation |
 | Agent adapters | Built-in `process` and `http` adapters |
 | Auth | Mode-dependent human auth (`local_trusted` implicit board in current code; authenticated mode uses sessions), API keys for agents |
 | Budget period | Monthly UTC calendar window |
@@ -395,7 +395,7 @@ Side effects:
 - entering `done` sets `completed_at`
 - entering `cancelled` sets `cancelled_at`
 
-Detailed ownership, execution, blocker, and crash-recovery semantics are documented in `doc/execution-semantics.md`.
+Detailed ownership, execution, blocker, active-run watchdog, and crash-recovery semantics are documented in `doc/execution-semantics.md`.
 
 ## 8.3 Approval Status
 

doc/execution-semantics.md

@@ -1,7 +1,7 @@
 # Execution Semantics
 
 Status: Current implementation guide
-Date: 2026-04-13
+Date: 2026-04-23
 Audience: Product and engineering
 
 This document explains how Paperclip interprets issue assignment, issue status, execution runs, wakeups, parent/sub-issue structure, and blocker relationships.
@@ -218,15 +218,81 @@ This is an active-work continuity recovery.
 
 Startup recovery and periodic recovery are different from normal wakeup delivery.
 
-On startup and on the periodic recovery loop, Paperclip now does three things in sequence:
+On startup and on the periodic recovery loop, Paperclip now does four things in sequence:
 
 1. reap orphaned `running` runs
 2. resume persisted `queued` runs
 3. reconcile stranded assigned work
+4. scan silent active runs and create or update explicit watchdog review issues
 
-That last step is what closes the gap where issue state survives a crash but the wake/run path does not.
+The stranded-work pass closes the gap where issue state survives a crash but the wake/run path does not. The silent-run scan covers the separate case where a live process exists but has stopped producing observable output.
 
-## 10. What This Does Not Mean
+## 10. Silent Active-Run Watchdog
+
+An active run can still be unhealthy even when its process is `running`. Paperclip treats prolonged output silence as a watchdog signal, not as proof that the run is failed.
+
+The recovery service owns this contract:
+
+- classify active-run output silence as `ok`, `suspicious`, `critical`, `snoozed`, or `not_applicable`
+- collect bounded evidence from run logs, recent run events, child issues, and blockers
+- preserve redaction and truncation before evidence is written to issue descriptions
+- create at most one open `stale_active_run_evaluation` issue per run
+- honor active snooze decisions before creating more review work
+- build the `outputSilence` summary shown by live-run and active-run API responses
+
+Suspicious silence creates a medium-priority review issue for the selected recovery owner. Critical silence raises that review issue to high priority and blocks the source issue on the explicit evaluation task without cancelling the active process.
+
+Watchdog decisions are explicit operator/recovery-owner decisions:
+
+- `snooze` records an operator-chosen future quiet-until time and suppresses scan-created review work during that window
+- `continue` records that the current evidence is acceptable, does not cancel or mutate the active run, and sets a 30-minute default re-arm window before the watchdog evaluates the still-silent run again
+- `dismissed_false_positive` records why the review was not actionable
+
+Operators should prefer `snooze` for known time-bounded quiet periods. `continue` is only a short acknowledgement of the current evidence; if the run remains silent after the re-arm window, the periodic watchdog scan can create or update review work again.
+
+The board can record watchdog decisions. The assigned owner of the watchdog evaluation issue can also record them. Other agents cannot.
+
+## 11. Auto-Recover vs Explicit Recovery vs Human Escalation
+
+Paperclip uses three different recovery outcomes, depending on how much it can safely infer.
+
+### Auto-Recover
+
+Auto-recovery is allowed when ownership is clear and the control plane only lost execution continuity.
+
+Examples:
+
+- requeue one dispatch wake for an assigned `todo` issue whose latest run failed, timed out, or was cancelled
+- requeue one continuation wake for an assigned `in_progress` issue whose live execution path disappeared
+- assign an orphan blocker back to its creator when that blocker is already preventing other work
+
+Auto-recovery preserves the existing owner. It does not choose a replacement agent.
+
+### Explicit Recovery Issue
+
+Paperclip creates an explicit recovery issue when the system can identify a problem but cannot safely complete the work itself.
+
+Examples:
+
+- automatic stranded-work retry was already exhausted
+- a dependency graph has an invalid/uninvokable owner, unassigned blocker, or invalid review participant
+- an active run is silent past the watchdog threshold
+
+The source issue remains visible and blocked on the recovery issue when blocking is necessary for correctness. The recovery owner must restore a live path, resolve the source issue manually, or record the reason it is a false positive.
+
+### Human Escalation
+
+Human escalation is required when the next safe action depends on board judgment, budget/approval policy, or information unavailable to the control plane.
+
+Examples:
+
+- all candidate recovery owners are paused, terminated, pending approval, or budget-blocked
+- the issue is human-owned rather than agent-owned
+- the run is intentionally quiet but needs an operator decision before cancellation or continuation
+
+In these cases Paperclip should leave a visible issue/comment trail instead of silently retrying.
+
+## 12. What This Does Not Mean
 
 These semantics do not change V1 into an auto-reassignment system.
 
@@ -240,9 +306,10 @@ The recovery model is intentionally conservative:
 
 - preserve ownership
 - retry once when the control plane lost execution continuity
+- create explicit recovery work when the system can identify a bounded recovery owner/action
 - escalate visibly when the system cannot safely keep going
 
-## 11. Practical Interpretation
+## 13. Practical Interpretation
 
 For a board operator, the intended meaning is:
 

package.json

@@ -17,7 +17,7 @@
     "typecheck": "pnpm run preflight:workspace-links && pnpm -r typecheck",
     "test": "pnpm run test:run",
     "test:watch": "pnpm run preflight:workspace-links && vitest",
-    "test:run": "pnpm run preflight:workspace-links && vitest run",
+    "test:run": "pnpm run preflight:workspace-links && node scripts/run-vitest-stable.mjs",
     "db:generate": "pnpm --filter @paperclipai/db generate",
     "db:migrate": "pnpm --filter @paperclipai/db migrate",
     "issue-references:backfill": "pnpm run preflight:workspace-links && tsx scripts/backfill-issue-reference-mentions.ts",

packages/adapter-utils/src/command-managed-runtime.ts

@@ -0,0 +1,152 @@
+import path from "node:path";
+import {
+  prepareSandboxManagedRuntime,
+  type PreparedSandboxManagedRuntime,
+  type SandboxManagedRuntimeAsset,
+  type SandboxManagedRuntimeClient,
+  type SandboxRemoteExecutionSpec,
+} from "./sandbox-managed-runtime.js";
+import type { RunProcessResult } from "./server-utils.js";
+
+export interface CommandManagedRuntimeRunner {
+  execute(input: {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    timeoutMs?: number;
+    onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
+    onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
+  }): Promise<RunProcessResult>;
+}
+
+export interface CommandManagedRuntimeSpec {
+  providerKey?: string | null;
+  leaseId?: string | null;
+  remoteCwd: string;
+  timeoutMs?: number | null;
+  paperclipApiUrl?: string | null;
+}
+
+export type CommandManagedRuntimeAsset = SandboxManagedRuntimeAsset;
+
+function shellQuote(value: string) {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function toBuffer(bytes: Buffer | Uint8Array | ArrayBuffer): Buffer {
+  if (Buffer.isBuffer(bytes)) return bytes;
+  if (bytes instanceof ArrayBuffer) return Buffer.from(bytes);
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function requireSuccessfulResult(result: RunProcessResult, action: string): void {
+  if (result.exitCode === 0 && !result.timedOut) return;
+  const stderr = result.stderr.trim();
+  const detail = stderr.length > 0 ? `: ${stderr}` : "";
+  throw new Error(`${action} failed with exit code ${result.exitCode ?? "null"}${detail}`);
+}
+
+function createCommandManagedRuntimeClient(input: {
+  runner: CommandManagedRuntimeRunner;
+  remoteCwd: string;
+  timeoutMs: number;
+}): SandboxManagedRuntimeClient {
+  const runShell = async (script: string, opts: { stdin?: string; timeoutMs?: number } = {}) => {
+    const result = await input.runner.execute({
+      command: "sh",
+      args: ["-lc", script],
+      cwd: input.remoteCwd,
+      stdin: opts.stdin,
+      timeoutMs: opts.timeoutMs ?? input.timeoutMs,
+    });
+    requireSuccessfulResult(result, script);
+    return result;
+  };
+
+  return {
+    makeDir: async (remotePath) => {
+      await runShell(`mkdir -p ${shellQuote(remotePath)}`);
+    },
+    writeFile: async (remotePath, bytes) => {
+      const body = toBuffer(bytes).toString("base64");
+      await runShell(
+        `mkdir -p ${shellQuote(path.posix.dirname(remotePath))} && base64 -d > ${shellQuote(remotePath)}`,
+        { stdin: body },
+      );
+    },
+    readFile: async (remotePath) => {
+      const result = await runShell(`base64 < ${shellQuote(remotePath)}`);
+      return Buffer.from(result.stdout.replace(/\s+/g, ""), "base64");
+    },
+    remove: async (remotePath) => {
+      const result = await input.runner.execute({
+        command: "sh",
+        args: ["-lc", `rm -rf ${shellQuote(remotePath)}`],
+        cwd: input.remoteCwd,
+        timeoutMs: input.timeoutMs,
+      });
+      requireSuccessfulResult(result, `remove ${remotePath}`);
+    },
+    run: async (command, options) => {
+      const result = await input.runner.execute({
+        command: "sh",
+        args: ["-lc", command],
+        cwd: input.remoteCwd,
+        timeoutMs: options.timeoutMs,
+      });
+      requireSuccessfulResult(result, command);
+    },
+  };
+}
+
+export async function prepareCommandManagedRuntime(input: {
+  runner: CommandManagedRuntimeRunner;
+  spec: CommandManagedRuntimeSpec;
+  adapterKey: string;
+  workspaceLocalDir: string;
+  workspaceRemoteDir?: string;
+  workspaceExclude?: string[];
+  preserveAbsentOnRestore?: string[];
+  assets?: CommandManagedRuntimeAsset[];
+  installCommand?: string | null;
+}): Promise<PreparedSandboxManagedRuntime> {
+  const timeoutMs = input.spec.timeoutMs && input.spec.timeoutMs > 0 ? input.spec.timeoutMs : 300_000;
+  const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
+  const runtimeSpec: SandboxRemoteExecutionSpec = {
+    transport: "sandbox",
+    provider: input.spec.providerKey ?? "sandbox",
+    sandboxId: input.spec.leaseId ?? "managed",
+    remoteCwd: workspaceRemoteDir,
+    timeoutMs,
+    apiKey: null,
+    paperclipApiUrl: input.spec.paperclipApiUrl ?? null,
+  };
+  const client = createCommandManagedRuntimeClient({
+    runner: input.runner,
+    remoteCwd: workspaceRemoteDir,
+    timeoutMs,
+  });
+
+  if (input.installCommand?.trim()) {
+    const result = await input.runner.execute({
+      command: "sh",
+      args: ["-lc", input.installCommand.trim()],
+      cwd: workspaceRemoteDir,
+      timeoutMs,
+    });
+    requireSuccessfulResult(result, input.installCommand.trim());
+  }
+
+  return await prepareSandboxManagedRuntime({
+    spec: runtimeSpec,
+    client,
+    adapterKey: input.adapterKey,
+    workspaceLocalDir: input.workspaceLocalDir,
+    workspaceRemoteDir,
+    workspaceExclude: input.workspaceExclude,
+    preserveAbsentOnRestore: input.preserveAbsentOnRestore,
+    assets: input.assets,
+  });
+}

packages/adapter-utils/src/execution-target-sandbox.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  adapterExecutionTargetSessionIdentity,
+  adapterExecutionTargetToRemoteSpec,
+  runAdapterExecutionTargetProcess,
+  runAdapterExecutionTargetShellCommand,
+  type AdapterSandboxExecutionTarget,
+} from "./execution-target.js";
+
+describe("sandbox adapter execution targets", () => {
+  it("executes through the provider-neutral runner without a remote spec", async () => {
+    const runner = {
+      execute: vi.fn(async () => ({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: "ok\n",
+        stderr: "",
+        pid: null,
+        startedAt: new Date().toISOString(),
+      })),
+    };
+    const target: AdapterSandboxExecutionTarget = {
+      kind: "remote",
+      transport: "sandbox",
+      providerKey: "acme-sandbox",
+      environmentId: "env-1",
+      leaseId: "lease-1",
+      remoteCwd: "/workspace",
+      timeoutMs: 30_000,
+      runner,
+    };
+
+    expect(adapterExecutionTargetToRemoteSpec(target)).toBeNull();
+
+    const result = await runAdapterExecutionTargetProcess("run-1", target, "agent-cli", ["--json"], {
+      cwd: "/local/workspace",
+      env: { TOKEN: "token" },
+      stdin: "prompt",
+      timeoutSec: 5,
+      graceSec: 1,
+      onLog: async () => {},
+    });
+
+    expect(result.stdout).toBe("ok\n");
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      command: "agent-cli",
+      args: ["--json"],
+      cwd: "/workspace",
+      env: { TOKEN: "token" },
+      stdin: "prompt",
+      timeoutMs: 5000,
+    }));
+    expect(adapterExecutionTargetSessionIdentity(target)).toEqual({
+      transport: "sandbox",
+      providerKey: "acme-sandbox",
+      environmentId: "env-1",
+      leaseId: "lease-1",
+      remoteCwd: "/workspace",
+    });
+  });
+
+  it("runs shell commands through the same runner", async () => {
+    const runner = {
+      execute: vi.fn(async () => ({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: "/home/sandbox",
+        stderr: "",
+        pid: null,
+        startedAt: new Date().toISOString(),
+      })),
+    };
+    const target: AdapterSandboxExecutionTarget = {
+      kind: "remote",
+      transport: "sandbox",
+      remoteCwd: "/workspace",
+      runner,
+    };
+
+    await runAdapterExecutionTargetShellCommand("run-2", target, 'printf %s "$HOME"', {
+      cwd: "/local/workspace",
+      env: {},
+      timeoutSec: 7,
+    });
+
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      command: "sh",
+      args: ["-lc", 'printf %s "$HOME"'],
+      cwd: "/workspace",
+      timeoutMs: 7000,
+    }));
+  });
+});

packages/adapter-utils/src/execution-target.ts

@@ -1,5 +1,9 @@
 import path from "node:path";
 import type { SshRemoteExecutionSpec } from "./ssh.js";
+import {
+  prepareCommandManagedRuntime,
+  type CommandManagedRuntimeRunner,
+} from "./command-managed-runtime.js";
 import {
   buildRemoteExecutionSessionIdentity,
   prepareRemoteManagedRuntime,
@@ -31,9 +35,22 @@ export interface AdapterSshExecutionTarget {
   spec: SshRemoteExecutionSpec;
 }
 
+export interface AdapterSandboxExecutionTarget {
+  kind: "remote";
+  transport: "sandbox";
+  providerKey?: string | null;
+  environmentId?: string | null;
+  leaseId?: string | null;
+  remoteCwd: string;
+  paperclipApiUrl?: string | null;
+  timeoutMs?: number | null;
+  runner?: CommandManagedRuntimeRunner;
+}
+
 export type AdapterExecutionTarget =
   | AdapterLocalExecutionTarget
-  | AdapterSshExecutionTarget;
+  | AdapterSshExecutionTarget
+  | AdapterSandboxExecutionTarget;
 
 export type AdapterRemoteExecutionSpec = SshRemoteExecutionSpec;
 
@@ -84,7 +101,8 @@ function isAdapterExecutionTargetInstance(value: unknown): value is AdapterExecu
   if (parsed.kind === "local") return true;
   if (parsed.kind !== "remote") return false;
   if (parsed.transport === "ssh") return parseSshRemoteExecutionSpec(parseObject(parsed.spec)) !== null;
-  return false;
+  if (parsed.transport !== "sandbox") return false;
+  return readStringMeta(parsed, "remoteCwd") !== null;
 }
 
 export function adapterExecutionTargetToRemoteSpec(
@@ -102,10 +120,7 @@ export function adapterExecutionTargetIsRemote(
 export function adapterExecutionTargetUsesManagedHome(
   target: AdapterExecutionTarget | null | undefined,
 ): boolean {
-  // SSH execution targets sync the runtime assets they need into the remote cwd today,
-  // so neither local nor remote targets provision a separate managed adapter home.
-  void target;
-  return false;
+  return target?.kind === "remote" && target.transport === "sandbox";
 }
 
 export function adapterExecutionTargetRemoteCwd(
@@ -119,14 +134,25 @@ export function adapterExecutionTargetPaperclipApiUrl(
   target: AdapterExecutionTarget | null | undefined,
 ): string | null {
   if (target?.kind !== "remote") return null;
-  return target.paperclipApiUrl ?? target.spec.paperclipApiUrl ?? null;
+  if (target.transport === "ssh") return target.paperclipApiUrl ?? target.spec.paperclipApiUrl ?? null;
+  return target.paperclipApiUrl ?? null;
 }
 
 export function describeAdapterExecutionTarget(
   target: AdapterExecutionTarget | null | undefined,
 ): string {
   if (!target || target.kind === "local") return "local environment";
-  return `SSH environment ${target.spec.username}@${target.spec.host}:${target.spec.port}`;
+  if (target.transport === "ssh") {
+    return `SSH environment ${target.spec.username}@${target.spec.host}:${target.spec.port}`;
+  }
+  return `sandbox environment${target.providerKey ? ` (${target.providerKey})` : ""}`;
+}
+
+function requireSandboxRunner(target: AdapterSandboxExecutionTarget): CommandManagedRuntimeRunner {
+  if (target.runner) return target.runner;
+  throw new Error(
+    "Sandbox execution target is missing its provider runtime runner. Sandbox commands must execute through the environment runtime.",
+  );
 }
 
 export async function ensureAdapterExecutionTargetCommandResolvable(
@@ -135,6 +161,9 @@ export async function ensureAdapterExecutionTargetCommandResolvable(
   cwd: string,
   env: NodeJS.ProcessEnv,
 ) {
+  if (target?.kind === "remote" && target.transport === "sandbox") {
+    return;
+  }
   await ensureCommandResolvable(command, cwd, env, {
     remoteExecution: adapterExecutionTargetToRemoteSpec(target),
   });
@@ -146,6 +175,9 @@ export async function resolveAdapterExecutionTargetCommandForLogs(
   cwd: string,
   env: NodeJS.ProcessEnv,
 ): Promise<string> {
+  if (target?.kind === "remote" && target.transport === "sandbox") {
+    return `sandbox://${target.providerKey ?? "provider"}/${target.leaseId ?? "lease"}/${target.remoteCwd} :: ${command}`;
+  }
   return await resolveCommandForLogs(command, cwd, env, {
     remoteExecution: adapterExecutionTargetToRemoteSpec(target),
   });
@@ -158,6 +190,22 @@ export async function runAdapterExecutionTargetProcess(
   args: string[],
   options: AdapterExecutionTargetProcessOptions,
 ): Promise<RunProcessResult> {
+  if (target?.kind === "remote" && target.transport === "sandbox") {
+    const runner = requireSandboxRunner(target);
+    return await runner.execute({
+      command,
+      args,
+      cwd: target.remoteCwd,
+      env: options.env,
+      stdin: options.stdin,
+      timeoutMs: options.timeoutSec > 0 ? options.timeoutSec * 1000 : target.timeoutMs ?? undefined,
+      onLog: options.onLog,
+      onSpawn: options.onSpawn
+        ? async (meta) => options.onSpawn?.({ ...meta, processGroupId: null })
+        : undefined,
+    });
+  }
+
   return await runChildProcess(runId, command, args, {
     cwd: options.cwd,
     env: options.env,
@@ -180,57 +228,68 @@ export async function runAdapterExecutionTargetShellCommand(
   const onLog = options.onLog ?? (async () => {});
   if (target?.kind === "remote") {
     const startedAt = new Date().toISOString();
-    try {
-      const result = await runSshCommand(target.spec, `sh -lc ${shellQuote(command)}`, {
-        timeoutMs: (options.timeoutSec ?? 15) * 1000,
-      });
-      if (result.stdout) await onLog("stdout", result.stdout);
-      if (result.stderr) await onLog("stderr", result.stderr);
-      return {
-        exitCode: 0,
-        signal: null,
-        timedOut: false,
-        stdout: result.stdout,
-        stderr: result.stderr,
-        pid: null,
-        startedAt,
-      };
-    } catch (error) {
-      const timedOutError = error as NodeJS.ErrnoException & {
-        stdout?: string;
-        stderr?: string;
-        signal?: string | null;
-      };
-      const stdout = timedOutError.stdout ?? "";
-      const stderr = timedOutError.stderr ?? "";
-      if (typeof timedOutError.code === "number") {
+    if (target.transport === "ssh") {
+      try {
+        const result = await runSshCommand(target.spec, `sh -lc ${shellQuote(command)}`, {
+          timeoutMs: (options.timeoutSec ?? 15) * 1000,
+        });
+        if (result.stdout) await onLog("stdout", result.stdout);
+        if (result.stderr) await onLog("stderr", result.stderr);
+        return {
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          pid: null,
+          startedAt,
+        };
+      } catch (error) {
+        const timedOutError = error as NodeJS.ErrnoException & {
+          stdout?: string;
+          stderr?: string;
+          signal?: string | null;
+        };
+        const stdout = timedOutError.stdout ?? "";
+        const stderr = timedOutError.stderr ?? "";
+        if (typeof timedOutError.code === "number") {
+          if (stdout) await onLog("stdout", stdout);
+          if (stderr) await onLog("stderr", stderr);
+          return {
+            exitCode: timedOutError.code,
+            signal: timedOutError.signal ?? null,
+            timedOut: false,
+            stdout,
+            stderr,
+            pid: null,
+            startedAt,
+          };
+        }
+        if (timedOutError.code !== "ETIMEDOUT") {
+          throw error;
+        }
         if (stdout) await onLog("stdout", stdout);
         if (stderr) await onLog("stderr", stderr);
         return {
-          exitCode: timedOutError.code,
+          exitCode: null,
           signal: timedOutError.signal ?? null,
-          timedOut: false,
+          timedOut: true,
           stdout,
           stderr,
           pid: null,
           startedAt,
         };
       }
-      if (timedOutError.code !== "ETIMEDOUT") {
-        throw error;
-      }
-      if (stdout) await onLog("stdout", stdout);
-      if (stderr) await onLog("stderr", stderr);
-      return {
-        exitCode: null,
-        signal: timedOutError.signal ?? null,
-        timedOut: true,
-        stdout,
-        stderr,
-        pid: null,
-        startedAt,
-      };
     }
+
+    return await requireSandboxRunner(target).execute({
+      command: "sh",
+      args: ["-lc", command],
+      cwd: target.remoteCwd,
+      env: options.env,
+      timeoutMs: (options.timeoutSec ?? 15) * 1000,
+      onLog,
+    });
   }
 
   return await runAdapterExecutionTargetProcess(
@@ -281,7 +340,15 @@ export function adapterExecutionTargetSessionIdentity(
   target: AdapterExecutionTarget | null | undefined,
 ): Record<string, unknown> | null {
   if (!target || target.kind === "local") return null;
-  return buildRemoteExecutionSessionIdentity(target.spec);
+  if (target.transport === "ssh") return buildRemoteExecutionSessionIdentity(target.spec);
+  return {
+    transport: "sandbox",
+    providerKey: target.providerKey ?? null,
+    environmentId: target.environmentId ?? null,
+    leaseId: target.leaseId ?? null,
+    remoteCwd: target.remoteCwd,
+    ...(target.paperclipApiUrl ? { paperclipApiUrl: target.paperclipApiUrl } : {}),
+  };
 }
 
 export function adapterExecutionTargetSessionMatches(
@@ -291,7 +358,17 @@ export function adapterExecutionTargetSessionMatches(
   if (!target || target.kind === "local") {
     return Object.keys(parseObject(saved)).length === 0;
   }
-  return remoteExecutionSessionMatches(saved, target.spec);
+  if (target.transport === "ssh") return remoteExecutionSessionMatches(saved, target.spec);
+  const current = adapterExecutionTargetSessionIdentity(target);
+  const parsedSaved = parseObject(saved);
+  return (
+    readStringMeta(parsedSaved, "transport") === current?.transport &&
+    readStringMeta(parsedSaved, "providerKey") === current?.providerKey &&
+    readStringMeta(parsedSaved, "environmentId") === current?.environmentId &&
+    readStringMeta(parsedSaved, "leaseId") === current?.leaseId &&
+    readStringMeta(parsedSaved, "remoteCwd") === current?.remoteCwd &&
+    readStringMeta(parsedSaved, "paperclipApiUrl") === (current?.paperclipApiUrl ?? null)
+  );
 }
 
 export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTarget | null {
@@ -320,6 +397,21 @@ export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTar
     };
   }
 
+  if (kind === "remote" && readStringMeta(parsed, "transport") === "sandbox") {
+    const remoteCwd = readStringMeta(parsed, "remoteCwd");
+    if (!remoteCwd) return null;
+    return {
+      kind: "remote",
+      transport: "sandbox",
+      providerKey: readStringMeta(parsed, "providerKey"),
+      environmentId: readStringMeta(parsed, "environmentId"),
+      leaseId: readStringMeta(parsed, "leaseId"),
+      remoteCwd,
+      paperclipApiUrl: readStringMeta(parsed, "paperclipApiUrl"),
+      timeoutMs: typeof parsed.timeoutMs === "number" ? parsed.timeoutMs : null,
+    };
+  }
+
   return null;
 }
 
@@ -376,11 +468,36 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
     };
   }
 
-  const prepared = await prepareRemoteManagedRuntime({
-    spec: target.spec,
+  if (target.transport === "ssh") {
+    const prepared = await prepareRemoteManagedRuntime({
+      spec: target.spec,
+      adapterKey: input.adapterKey,
+      workspaceLocalDir: input.workspaceLocalDir,
+      assets: input.assets,
+    });
+    return {
+      target,
+      runtimeRootDir: prepared.runtimeRootDir,
+      assetDirs: prepared.assetDirs,
+      restoreWorkspace: prepared.restoreWorkspace,
+    };
+  }
+
+  const prepared = await prepareCommandManagedRuntime({
+    runner: requireSandboxRunner(target),
+    spec: {
+      providerKey: target.providerKey,
+      leaseId: target.leaseId,
+      remoteCwd: target.remoteCwd,
+      timeoutMs: target.timeoutMs,
+      paperclipApiUrl: target.paperclipApiUrl,
+    },
     adapterKey: input.adapterKey,
     workspaceLocalDir: input.workspaceLocalDir,
+    workspaceExclude: input.workspaceExclude,
+    preserveAbsentOnRestore: input.preserveAbsentOnRestore,
     assets: input.assets,
+    installCommand: input.installCommand,
   });
   return {
     target,

packages/adapter-utils/src/sandbox-managed-runtime.test.ts

@@ -0,0 +1,126 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  mirrorDirectory,
+  prepareSandboxManagedRuntime,
+  type SandboxManagedRuntimeClient,
+} from "./sandbox-managed-runtime.js";
+
+const execFile = promisify(execFileCallback);
+
+describe("sandbox managed runtime", () => {
+  const cleanupDirs: string[] = [];
+
+  afterEach(async () => {
+    while (cleanupDirs.length > 0) {
+      const dir = cleanupDirs.pop();
+      if (!dir) continue;
+      await rm(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+  });
+
+  it("preserves excluded local workspace artifacts during restore mirroring", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-restore-"));
+    cleanupDirs.push(rootDir);
+    const sourceDir = path.join(rootDir, "source");
+    const targetDir = path.join(rootDir, "target");
+    await mkdir(path.join(sourceDir, "src"), { recursive: true });
+    await mkdir(path.join(targetDir, ".claude"), { recursive: true });
+    await mkdir(path.join(targetDir, ".paperclip-runtime"), { recursive: true });
+    await writeFile(path.join(sourceDir, "src", "app.ts"), "export const value = 2;\n", "utf8");
+    await writeFile(path.join(targetDir, "stale.txt"), "remove me\n", "utf8");
+    await writeFile(path.join(targetDir, ".claude", "settings.json"), "{\"keep\":true}\n", "utf8");
+    await writeFile(path.join(targetDir, ".claude.json"), "{\"keep\":true}\n", "utf8");
+    await writeFile(path.join(targetDir, ".paperclip-runtime", "state.json"), "{}\n", "utf8");
+
+    await mirrorDirectory(sourceDir, targetDir, {
+      preserveAbsent: [".paperclip-runtime", ".claude", ".claude.json"],
+    });
+
+    await expect(readFile(path.join(targetDir, "src", "app.ts"), "utf8")).resolves.toBe("export const value = 2;\n");
+    await expect(readFile(path.join(targetDir, ".claude", "settings.json"), "utf8")).resolves.toBe("{\"keep\":true}\n");
+    await expect(readFile(path.join(targetDir, ".claude.json"), "utf8")).resolves.toBe("{\"keep\":true}\n");
+    await expect(readFile(path.join(targetDir, ".paperclip-runtime", "state.json"), "utf8")).resolves.toBe("{}\n");
+    await expect(readFile(path.join(targetDir, "stale.txt"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("syncs workspace and assets through a provider-neutral sandbox client", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-sandbox-managed-"));
+    cleanupDirs.push(rootDir);
+    const localWorkspaceDir = path.join(rootDir, "local-workspace");
+    const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");
+    const localAssetsDir = path.join(rootDir, "local-assets");
+    const linkedAssetPath = path.join(rootDir, "linked-skill.md");
+    await mkdir(path.join(localWorkspaceDir, ".claude"), { recursive: true });
+    await mkdir(localAssetsDir, { recursive: true });
+    await writeFile(path.join(localWorkspaceDir, "README.md"), "local workspace\n", "utf8");
+    await writeFile(path.join(localWorkspaceDir, "._README.md"), "appledouble\n", "utf8");
+    await writeFile(path.join(localWorkspaceDir, ".claude", "settings.json"), "{\"local\":true}\n", "utf8");
+    await writeFile(linkedAssetPath, "skill body\n", "utf8");
+    await symlink(linkedAssetPath, path.join(localAssetsDir, "skill.md"));
+
+    const client: SandboxManagedRuntimeClient = {
+      makeDir: async (remotePath) => {
+        await mkdir(remotePath, { recursive: true });
+      },
+      writeFile: async (remotePath, bytes) => {
+        await mkdir(path.dirname(remotePath), { recursive: true });
+        await writeFile(remotePath, Buffer.from(bytes));
+      },
+      readFile: async (remotePath) => await readFile(remotePath),
+      remove: async (remotePath) => {
+        await rm(remotePath, { recursive: true, force: true });
+      },
+      run: async (command) => {
+        await execFile("sh", ["-lc", command], {
+          maxBuffer: 32 * 1024 * 1024,
+        });
+      },
+    };
+
+    const prepared = await prepareSandboxManagedRuntime({
+      spec: {
+        transport: "sandbox",
+        provider: "test",
+        sandboxId: "sandbox-1",
+        remoteCwd: remoteWorkspaceDir,
+        timeoutMs: 30_000,
+        apiKey: null,
+      },
+      adapterKey: "test-adapter",
+      client,
+      workspaceLocalDir: localWorkspaceDir,
+      workspaceExclude: [".claude"],
+      preserveAbsentOnRestore: [".claude"],
+      assets: [{
+        key: "skills",
+        localDir: localAssetsDir,
+        followSymlinks: true,
+      }],
+    });
+
+    await expect(readFile(path.join(remoteWorkspaceDir, "README.md"), "utf8")).resolves.toBe("local workspace\n");
+    await expect(readFile(path.join(remoteWorkspaceDir, "._README.md"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(path.join(remoteWorkspaceDir, ".claude", "settings.json"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(path.join(prepared.assetDirs.skills, "skill.md"), "utf8")).resolves.toBe("skill body\n");
+    expect((await lstat(path.join(prepared.assetDirs.skills, "skill.md"))).isFile()).toBe(true);
+
+    await writeFile(path.join(remoteWorkspaceDir, "README.md"), "remote workspace\n", "utf8");
+    await writeFile(path.join(remoteWorkspaceDir, "remote-only.txt"), "sync back\n", "utf8");
+    await mkdir(path.join(localWorkspaceDir, ".paperclip-runtime"), { recursive: true });
+    await writeFile(path.join(localWorkspaceDir, ".paperclip-runtime", "state.json"), "{}\n", "utf8");
+    await writeFile(path.join(localWorkspaceDir, "local-stale.txt"), "remove\n", "utf8");
+    await prepared.restoreWorkspace();
+
+    await expect(readFile(path.join(localWorkspaceDir, "README.md"), "utf8")).resolves.toBe("remote workspace\n");
+    await expect(readFile(path.join(localWorkspaceDir, "remote-only.txt"), "utf8")).resolves.toBe("sync back\n");
+    await expect(readFile(path.join(localWorkspaceDir, "local-stale.txt"), "utf8")).rejects.toMatchObject({ code: "ENOENT" });
+    await expect(readFile(path.join(localWorkspaceDir, ".claude", "settings.json"), "utf8")).resolves.toBe("{\"local\":true}\n");
+    await expect(readFile(path.join(localWorkspaceDir, ".paperclip-runtime", "state.json"), "utf8")).resolves.toBe("{}\n");
+  });
+});

packages/adapter-utils/src/sandbox-managed-runtime.ts

@@ -0,0 +1,338 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCallback);
+
+export interface SandboxRemoteExecutionSpec {
+  transport: "sandbox";
+  provider: string;
+  sandboxId: string;
+  remoteCwd: string;
+  timeoutMs: number;
+  apiKey: string | null;
+  paperclipApiUrl?: string | null;
+}
+
+export interface SandboxManagedRuntimeAsset {
+  key: string;
+  localDir: string;
+  followSymlinks?: boolean;
+  exclude?: string[];
+}
+
+export interface SandboxManagedRuntimeClient {
+  makeDir(remotePath: string): Promise<void>;
+  writeFile(remotePath: string, bytes: ArrayBuffer): Promise<void>;
+  readFile(remotePath: string): Promise<Buffer | Uint8Array | ArrayBuffer>;
+  remove(remotePath: string): Promise<void>;
+  run(command: string, options: { timeoutMs: number }): Promise<void>;
+}
+
+export interface PreparedSandboxManagedRuntime {
+  spec: SandboxRemoteExecutionSpec;
+  workspaceLocalDir: string;
+  workspaceRemoteDir: string;
+  runtimeRootDir: string;
+  assetDirs: Record<string, string>;
+  restoreWorkspace(): Promise<void>;
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function asNumber(value: unknown): number {
+  return typeof value === "number" ? value : Number(value);
+}
+
+function shellQuote(value: string) {
+  return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+export function parseSandboxRemoteExecutionSpec(value: unknown): SandboxRemoteExecutionSpec | null {
+  const parsed = asObject(value);
+  const transport = asString(parsed.transport).trim();
+  const provider = asString(parsed.provider).trim();
+  const sandboxId = asString(parsed.sandboxId).trim();
+  const remoteCwd = asString(parsed.remoteCwd).trim();
+  const timeoutMs = asNumber(parsed.timeoutMs);
+
+  if (
+    transport !== "sandbox" ||
+    provider.length === 0 ||
+    sandboxId.length === 0 ||
+    remoteCwd.length === 0 ||
+    !Number.isFinite(timeoutMs) ||
+    timeoutMs <= 0
+  ) {
+    return null;
+  }
+
+  return {
+    transport: "sandbox",
+    provider,
+    sandboxId,
+    remoteCwd,
+    timeoutMs,
+    apiKey: asString(parsed.apiKey).trim() || null,
+    paperclipApiUrl: asString(parsed.paperclipApiUrl).trim() || null,
+  };
+}
+
+export function buildSandboxExecutionSessionIdentity(spec: SandboxRemoteExecutionSpec | null) {
+  if (!spec) return null;
+  return {
+    transport: "sandbox",
+    provider: spec.provider,
+    sandboxId: spec.sandboxId,
+    remoteCwd: spec.remoteCwd,
+    ...(spec.paperclipApiUrl ? { paperclipApiUrl: spec.paperclipApiUrl } : {}),
+  } as const;
+}
+
+export function sandboxExecutionSessionMatches(saved: unknown, current: SandboxRemoteExecutionSpec | null): boolean {
+  const currentIdentity = buildSandboxExecutionSessionIdentity(current);
+  if (!currentIdentity) return false;
+  const parsedSaved = asObject(saved);
+  return (
+    asString(parsedSaved.transport) === currentIdentity.transport &&
+    asString(parsedSaved.provider) === currentIdentity.provider &&
+    asString(parsedSaved.sandboxId) === currentIdentity.sandboxId &&
+    asString(parsedSaved.remoteCwd) === currentIdentity.remoteCwd &&
+    asString(parsedSaved.paperclipApiUrl) === asString(currentIdentity.paperclipApiUrl)
+  );
+}
+
+async function withTempDir<T>(prefix: string, fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+  try {
+    return await fn(dir);
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+async function execTar(args: string[]): Promise<void> {
+  await execFile("tar", args, {
+    env: {
+      ...process.env,
+      COPYFILE_DISABLE: "1",
+    },
+    maxBuffer: 32 * 1024 * 1024,
+  });
+}
+
+async function createTarballFromDirectory(input: {
+  localDir: string;
+  archivePath: string;
+  exclude?: string[];
+  followSymlinks?: boolean;
+}): Promise<void> {
+  const excludeArgs = ["._*", ...(input.exclude ?? [])].flatMap((entry) => ["--exclude", entry]);
+  await execTar([
+    "-c",
+    ...(input.followSymlinks ? ["-h"] : []),
+    "-f",
+    input.archivePath,
+    "-C",
+    input.localDir,
+    ...excludeArgs,
+    ".",
+  ]);
+}
+
+async function extractTarballToDirectory(input: {
+  archivePath: string;
+  localDir: string;
+}): Promise<void> {
+  await fs.mkdir(input.localDir, { recursive: true });
+  await execTar(["-xf", input.archivePath, "-C", input.localDir]);
+}
+
+async function walkDirectory(root: string, relative = ""): Promise<string[]> {
+  const current = path.join(root, relative);
+  const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+  const out: string[] = [];
+  for (const entry of entries) {
+    const nextRelative = relative ? path.posix.join(relative, entry.name) : entry.name;
+    out.push(nextRelative);
+    if (entry.isDirectory()) {
+      out.push(...(await walkDirectory(root, nextRelative)));
+    }
+  }
+  return out.sort((left, right) => right.length - left.length);
+}
+
+function isRelativePathOrDescendant(relative: string, candidate: string): boolean {
+  return relative === candidate || relative.startsWith(`${candidate}/`);
+}
+
+export async function mirrorDirectory(
+  sourceDir: string,
+  targetDir: string,
+  options: { preserveAbsent?: string[] } = {},
+): Promise<void> {
+  await fs.mkdir(targetDir, { recursive: true });
+  const preserveAbsent = new Set(options.preserveAbsent ?? []);
+  const shouldPreserveAbsent = (relative: string) =>
+    [...preserveAbsent].some((candidate) => isRelativePathOrDescendant(relative, candidate));
+
+  const sourceEntries = new Set(await walkDirectory(sourceDir));
+  const targetEntries = await walkDirectory(targetDir);
+  for (const relative of targetEntries) {
+    if (shouldPreserveAbsent(relative)) continue;
+    if (!sourceEntries.has(relative)) {
+      await fs.rm(path.join(targetDir, relative), { recursive: true, force: true }).catch(() => undefined);
+    }
+  }
+
+  const copyEntry = async (relative: string) => {
+    const sourcePath = path.join(sourceDir, relative);
+    const targetPath = path.join(targetDir, relative);
+    const stats = await fs.lstat(sourcePath);
+
+    if (stats.isDirectory()) {
+      await fs.mkdir(targetPath, { recursive: true });
+      return;
+    }
+
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.rm(targetPath, { recursive: true, force: true }).catch(() => undefined);
+    if (stats.isSymbolicLink()) {
+      const linkTarget = await fs.readlink(sourcePath);
+      await fs.symlink(linkTarget, targetPath);
+      return;
+    }
+
+    await fs.copyFile(sourcePath, targetPath, fsConstants.COPYFILE_FICLONE).catch(async () => {
+      await fs.copyFile(sourcePath, targetPath);
+    });
+    await fs.chmod(targetPath, stats.mode);
+  };
+
+  const entries = (await walkDirectory(sourceDir)).sort((left, right) => left.localeCompare(right));
+  for (const relative of entries) {
+    await copyEntry(relative);
+  }
+}
+
+function toArrayBuffer(bytes: Buffer): ArrayBuffer {
+  return Uint8Array.from(bytes).buffer;
+}
+
+function toBuffer(bytes: Buffer | Uint8Array | ArrayBuffer): Buffer {
+  if (Buffer.isBuffer(bytes)) return bytes;
+  if (bytes instanceof ArrayBuffer) return Buffer.from(bytes);
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+function tarExcludeFlags(exclude: string[] | undefined): string {
+  return ["._*", ...(exclude ?? [])].map((entry) => `--exclude ${shellQuote(entry)}`).join(" ");
+}
+
+export async function prepareSandboxManagedRuntime(input: {
+  spec: SandboxRemoteExecutionSpec;
+  adapterKey: string;
+  client: SandboxManagedRuntimeClient;
+  workspaceLocalDir: string;
+  workspaceRemoteDir?: string;
+  workspaceExclude?: string[];
+  preserveAbsentOnRestore?: string[];
+  assets?: SandboxManagedRuntimeAsset[];
+}): Promise<PreparedSandboxManagedRuntime> {
+  const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
+  const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
+
+  await withTempDir("paperclip-sandbox-sync-", async (tempDir) => {
+    const workspaceTarPath = path.join(tempDir, "workspace.tar");
+    await createTarballFromDirectory({
+      localDir: input.workspaceLocalDir,
+      archivePath: workspaceTarPath,
+      exclude: input.workspaceExclude,
+    });
+    const workspaceTarBytes = await fs.readFile(workspaceTarPath);
+    const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-upload.tar");
+    await input.client.makeDir(runtimeRootDir);
+    await input.client.writeFile(remoteWorkspaceTar, toArrayBuffer(workspaceTarBytes));
+    const preservedNames = new Set([".paperclip-runtime", ...(input.preserveAbsentOnRestore ?? [])]);
+    const findPreserveArgs = [...preservedNames].map((entry) => `! -name ${shellQuote(entry)}`).join(" ");
+    await input.client.run(
+      `sh -lc ${shellQuote(
+        `mkdir -p ${shellQuote(workspaceRemoteDir)} && ` +
+          `find ${shellQuote(workspaceRemoteDir)} -mindepth 1 -maxdepth 1 ${findPreserveArgs} -exec rm -rf -- {} + && ` +
+          `tar -xf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} && ` +
+          `rm -f ${shellQuote(remoteWorkspaceTar)}`,
+      )}`,
+      { timeoutMs: input.spec.timeoutMs },
+    );
+
+    for (const asset of input.assets ?? []) {
+      const assetTarPath = path.join(tempDir, `${asset.key}.tar`);
+      await createTarballFromDirectory({
+        localDir: asset.localDir,
+        archivePath: assetTarPath,
+        followSymlinks: asset.followSymlinks,
+        exclude: asset.exclude,
+      });
+      const assetTarBytes = await fs.readFile(assetTarPath);
+      const remoteAssetDir = path.posix.join(runtimeRootDir, asset.key);
+      const remoteAssetTar = path.posix.join(runtimeRootDir, `${asset.key}-upload.tar`);
+      await input.client.writeFile(remoteAssetTar, toArrayBuffer(assetTarBytes));
+      await input.client.run(
+        `sh -lc ${shellQuote(
+          `rm -rf ${shellQuote(remoteAssetDir)} && ` +
+            `mkdir -p ${shellQuote(remoteAssetDir)} && ` +
+            `tar -xf ${shellQuote(remoteAssetTar)} -C ${shellQuote(remoteAssetDir)} && ` +
+            `rm -f ${shellQuote(remoteAssetTar)}`,
+        )}`,
+        { timeoutMs: input.spec.timeoutMs },
+      );
+    }
+  });
+
+  const assetDirs = Object.fromEntries(
+    (input.assets ?? []).map((asset) => [asset.key, path.posix.join(runtimeRootDir, asset.key)]),
+  );
+
+  return {
+    spec: input.spec,
+    workspaceLocalDir: input.workspaceLocalDir,
+    workspaceRemoteDir,
+    runtimeRootDir,
+    assetDirs,
+    restoreWorkspace: async () => {
+      await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
+        const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-download.tar");
+        await input.client.run(
+          `sh -lc ${shellQuote(
+            `mkdir -p ${shellQuote(runtimeRootDir)} && ` +
+              `tar -cf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} ` +
+              `${tarExcludeFlags(input.workspaceExclude)} .`,
+          )}`,
+          { timeoutMs: input.spec.timeoutMs },
+        );
+        const archiveBytes = await input.client.readFile(remoteWorkspaceTar);
+        await input.client.remove(remoteWorkspaceTar).catch(() => undefined);
+        const localArchivePath = path.join(tempDir, "workspace.tar");
+        const extractedDir = path.join(tempDir, "workspace");
+        await fs.writeFile(localArchivePath, toBuffer(archiveBytes));
+        await extractTarballToDirectory({
+          archivePath: localArchivePath,
+          localDir: extractedDir,
+        });
+        await mirrorDirectory(extractedDir, input.workspaceLocalDir, {
+          preserveAbsent: [".paperclip-runtime", ...(input.preserveAbsentOnRestore ?? [])],
+        });
+      });
+    },
+  };
+}

packages/adapter-utils/src/server-utils.ts

@@ -92,6 +92,7 @@ export const DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE = [
   "- If woken by a human comment on a dependency-blocked issue, respond or triage the comment without treating the blocked deliverable work as unblocked.",
   "- Create child issues directly when you know what needs to be done; use issue-thread interactions when the board/user must choose suggested tasks, answer structured questions, or confirm a proposal.",
   "- To ask for that input, create an interaction on the current issue with POST /api/issues/{issueId}/interactions using kind suggest_tasks, ask_user_questions, or request_confirmation. Use continuationPolicy wake_assignee when you need to resume after a response; for request_confirmation this resumes only after acceptance.",
+  "- When you intentionally restart follow-up work on a completed assigned issue, include structured `resume: true` with the POST /api/issues/{issueId}/comments or PATCH /api/issues/{issueId} comment payload. Generic agent comments on closed issues are inert by default.",
   "- For plan approval, update the plan document first, then create request_confirmation targeting the latest plan revision with idempotencyKey confirmation:{issueId}:plan:{revisionId}. Wait for acceptance before creating implementation subtasks, and create a fresh confirmation after superseding board/user comments if approval is still needed.",
   "- If blocked, mark the issue blocked and name the unblock owner and action.",
   "- Respect budget, pause/cancel, approval gates, and company boundaries.",

packages/adapters/codex-local/src/index.ts

@@ -4,7 +4,23 @@ export const DEFAULT_CODEX_LOCAL_MODEL = "gpt-5.3-codex";
 export const DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX = true;
 export const CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS = ["gpt-5.4"] as const;
 
+function normalizeModelId(model: string | null | undefined): string {
+  return typeof model === "string" ? model.trim() : "";
+}
+
+export function isCodexLocalKnownModel(model: string | null | undefined): boolean {
+  const normalizedModel = normalizeModelId(model);
+  if (!normalizedModel) return false;
+  return models.some((entry) => entry.id === normalizedModel);
+}
+
+export function isCodexLocalManualModel(model: string | null | undefined): boolean {
+  const normalizedModel = normalizeModelId(model);
+  return Boolean(normalizedModel) && !isCodexLocalKnownModel(normalizedModel);
+}
+
 export function isCodexLocalFastModeSupported(model: string | null | undefined): boolean {
+  if (isCodexLocalManualModel(model)) return true;
   const normalizedModel = typeof model === "string" ? model.trim() : "";
   return CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS.includes(
     normalizedModel as (typeof CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS)[number],
@@ -35,7 +51,7 @@ Core fields:
 - modelReasoningEffort (string, optional): reasoning effort override (minimal|low|medium|high|xhigh) passed via -c model_reasoning_effort=...
 - promptTemplate (string, optional): run prompt template
 - search (boolean, optional): run codex with --search
-- fastMode (boolean, optional): enable Codex Fast mode; currently supported on GPT-5.4 only and consumes credits faster
+- fastMode (boolean, optional): enable Codex Fast mode; supported on GPT-5.4 and passed through for manual model IDs
 - dangerouslyBypassApprovalsAndSandbox (boolean, optional): run with bypass flag
 - command (string, optional): defaults to "codex"
 - extraArgs (string[], optional): additional CLI args
@@ -54,6 +70,6 @@ Notes:
 - Paperclip injects desired local skills into the effective CODEX_HOME/skills/ directory at execution time so Codex can discover "$paperclip" and related skills without polluting the project working directory. In managed-home mode (the default) this is ~/.paperclip/instances/<id>/companies/<companyId>/codex-home/skills/; when CODEX_HOME is explicitly overridden in adapter config, that override is used instead.
 - Unless explicitly overridden in adapter config, Paperclip runs Codex with a per-company managed CODEX_HOME under the active Paperclip instance and seeds auth/config from the shared Codex home (the CODEX_HOME env var, when set, or ~/.codex).
 - Some model/tool combinations reject certain effort levels (for example minimal with web search enabled).
-- Fast mode is currently supported on GPT-5.4 only. When enabled, Paperclip applies \`service_tier="fast"\` and \`features.fast_mode=true\`.
+- Fast mode is supported on GPT-5.4 and manual model IDs. When enabled for those models, Paperclip applies \`service_tier="fast"\` and \`features.fast_mode=true\`.
 - When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
 `;

packages/adapters/codex-local/src/server/codex-args.test.ts

@@ -26,6 +26,28 @@ describe("buildCodexExecArgs", () => {
     ]);
   });
 
+  it("enables Codex fast mode overrides for manual models", () => {
+    const result = buildCodexExecArgs({
+      model: "gpt-5.5",
+      fastMode: true,
+    });
+
+    expect(result.fastModeRequested).toBe(true);
+    expect(result.fastModeApplied).toBe(true);
+    expect(result.fastModeIgnoredReason).toBeNull();
+    expect(result.args).toEqual([
+      "exec",
+      "--json",
+      "--model",
+      "gpt-5.5",
+      "-c",
+      'service_tier="fast"',
+      "-c",
+      "features.fast_mode=true",
+      "-",
+    ]);
+  });
+
   it("ignores fast mode for unsupported models", () => {
     const result = buildCodexExecArgs({
       model: "gpt-5.3-codex",
@@ -34,7 +56,9 @@ describe("buildCodexExecArgs", () => {
 
     expect(result.fastModeRequested).toBe(true);
     expect(result.fastModeApplied).toBe(false);
-    expect(result.fastModeIgnoredReason).toContain("currently only supported on gpt-5.4");
+    expect(result.fastModeIgnoredReason).toContain(
+      "currently only supported on gpt-5.4 or manually configured model IDs",
+    );
     expect(result.args).toEqual([
       "exec",
       "--json",

packages/adapters/codex-local/src/server/codex-args.ts

@@ -25,7 +25,7 @@ function asRecord(value: unknown): Record<string, unknown> {
 }
 
 function formatFastModeSupportedModels(): string {
-  return CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS.join(", ");
+  return `${CODEX_LOCAL_FAST_MODE_SUPPORTED_MODELS.join(", ")} or manually configured model IDs`;
 }
 
 export function buildCodexExecArgs(

packages/adapters/codex-local/src/server/test.ts

@@ -146,7 +146,7 @@ export async function testEnvironment(
           code: "codex_fast_mode_unsupported_model",
           level: "warn",
           message: execArgs.fastModeIgnoredReason,
-          hint: "Switch the agent model to GPT-5.4 to enable Codex Fast mode.",
+          hint: "Switch the agent model to GPT-5.4 or enter a manual model ID to enable Codex Fast mode.",
         });
       }
 

packages/db/src/migrations/0069_liveness_recovery_dedupe.sql

@@ -0,0 +1,13 @@
+CREATE UNIQUE INDEX IF NOT EXISTS "issues_active_liveness_recovery_incident_uq"
+  ON "issues" USING btree ("company_id","origin_kind","origin_id")
+  WHERE "origin_kind" = 'harness_liveness_escalation'
+    AND "origin_id" IS NOT NULL
+    AND "hidden_at" IS NULL
+    AND "status" NOT IN ('done', 'cancelled');
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "issues_active_liveness_recovery_leaf_uq"
+  ON "issues" USING btree ("company_id","origin_kind","origin_fingerprint")
+  WHERE "origin_kind" = 'harness_liveness_escalation'
+    AND "origin_fingerprint" <> 'default'
+    AND "hidden_at" IS NULL
+    AND "status" NOT IN ('done', 'cancelled');

packages/db/src/migrations/0070_active_run_output_watchdog.sql

@@ -0,0 +1,70 @@
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "last_output_at" timestamp with time zone;
+--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "last_output_seq" integer DEFAULT 0 NOT NULL;
+--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "last_output_stream" text;
+--> statement-breakpoint
+ALTER TABLE "heartbeat_runs" ADD COLUMN IF NOT EXISTS "last_output_bytes" bigint;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "heartbeat_runs_company_status_last_output_idx"
+  ON "heartbeat_runs" USING btree ("company_id","status","last_output_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "heartbeat_runs_company_status_process_started_idx"
+  ON "heartbeat_runs" USING btree ("company_id","status","process_started_at");
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "heartbeat_run_watchdog_decisions" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "company_id" uuid NOT NULL,
+  "run_id" uuid NOT NULL,
+  "evaluation_issue_id" uuid,
+  "decision" text NOT NULL,
+  "snoozed_until" timestamp with time zone,
+  "reason" text,
+  "created_by_agent_id" uuid,
+  "created_by_user_id" text,
+  "created_by_run_id" uuid,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "heartbeat_run_watchdog_decisions" ADD CONSTRAINT "heartbeat_run_watchdog_decisions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "heartbeat_run_watchdog_decisions" ADD CONSTRAINT "heartbeat_run_watchdog_decisions_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "heartbeat_run_watchdog_decisions" ADD CONSTRAINT "heartbeat_run_watchdog_decisions_evaluation_issue_id_issues_id_fk" FOREIGN KEY ("evaluation_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "heartbeat_run_watchdog_decisions" ADD CONSTRAINT "heartbeat_run_watchdog_decisions_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ ALTER TABLE "heartbeat_run_watchdog_decisions" ADD CONSTRAINT "heartbeat_run_watchdog_decisions_created_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("created_by_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;
+EXCEPTION
+ WHEN duplicate_object THEN null;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "heartbeat_run_watchdog_decisions_company_run_created_idx"
+  ON "heartbeat_run_watchdog_decisions" USING btree ("company_id","run_id","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "heartbeat_run_watchdog_decisions_company_run_snooze_idx"
+  ON "heartbeat_run_watchdog_decisions" USING btree ("company_id","run_id","snoozed_until");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "issues_active_stale_run_evaluation_uq"
+  ON "issues" USING btree ("company_id","origin_kind","origin_id")
+  WHERE "origin_kind" = 'stale_active_run_evaluation'
+    AND "origin_id" IS NOT NULL
+    AND "hidden_at" IS NULL
+    AND "status" NOT IN ('done', 'cancelled');

packages/db/src/migrations/meta/_journal.json

@@ -484,6 +484,20 @@
       "when": 1776959400000,
       "tag": "0068_environment_local_driver_unique",
       "breakpoints": true
+    },
+    {
+      "idx": 69,
+      "version": "7",
+      "when": 1776780003000,
+      "tag": "0069_liveness_recovery_dedupe",
+      "breakpoints": true
+    },
+    {
+      "idx": 70,
+      "version": "7",
+      "when": 1776780004000,
+      "tag": "0070_active_run_output_watchdog",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/heartbeat_run_watchdog_decisions.ts

@@ -0,0 +1,34 @@
+import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issues } from "./issues.js";
+
+export const heartbeatRunWatchdogDecisions = pgTable(
+  "heartbeat_run_watchdog_decisions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    runId: uuid("run_id").notNull().references(() => heartbeatRuns.id, { onDelete: "cascade" }),
+    evaluationIssueId: uuid("evaluation_issue_id").references(() => issues.id, { onDelete: "set null" }),
+    decision: text("decision").notNull(),
+    snoozedUntil: timestamp("snoozed_until", { withTimezone: true }),
+    reason: text("reason"),
+    createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    createdByUserId: text("created_by_user_id"),
+    createdByRunId: uuid("created_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyRunCreatedIdx: index("heartbeat_run_watchdog_decisions_company_run_created_idx").on(
+      table.companyId,
+      table.runId,
+      table.createdAt,
+    ),
+    companyRunSnoozeIdx: index("heartbeat_run_watchdog_decisions_company_run_snooze_idx").on(
+      table.companyId,
+      table.runId,
+      table.snoozedUntil,
+    ),
+  }),
+);

packages/db/src/schema/heartbeat_runs.ts

@@ -34,6 +34,10 @@ export const heartbeatRuns = pgTable(
     processPid: integer("process_pid"),
     processGroupId: integer("process_group_id"),
     processStartedAt: timestamp("process_started_at", { withTimezone: true }),
+    lastOutputAt: timestamp("last_output_at", { withTimezone: true }),
+    lastOutputSeq: integer("last_output_seq").notNull().default(0),
+    lastOutputStream: text("last_output_stream"),
+    lastOutputBytes: bigint("last_output_bytes", { mode: "number" }),
     retryOfRunId: uuid("retry_of_run_id").references((): AnyPgColumn => heartbeatRuns.id, {
       onDelete: "set null",
     }),
@@ -64,5 +68,15 @@ export const heartbeatRuns = pgTable(
       table.livenessState,
       table.createdAt,
     ),
+    companyStatusLastOutputIdx: index("heartbeat_runs_company_status_last_output_idx").on(
+      table.companyId,
+      table.status,
+      table.lastOutputAt,
+    ),
+    companyStatusProcessStartedIdx: index("heartbeat_runs_company_status_process_started_idx").on(
+      table.companyId,
+      table.status,
+      table.processStartedAt,
+    ),
   }),
 );

packages/db/src/schema/index.ts

@@ -53,6 +53,7 @@ export { documentRevisions } from "./document_revisions.js";
 export { issueDocuments } from "./issue_documents.js";
 export { heartbeatRuns } from "./heartbeat_runs.js";
 export { heartbeatRunEvents } from "./heartbeat_run_events.js";
+export { heartbeatRunWatchdogDecisions } from "./heartbeat_run_watchdog_decisions.js";
 export { costEvents } from "./cost_events.js";
 export { financeEvents } from "./finance_events.js";
 export { approvals } from "./approvals.js";

packages/db/src/schema/issues.ts

@@ -91,5 +91,29 @@ export const issues = pgTable(
           and ${table.executionRunId} is not null
           and ${table.status} in ('backlog', 'todo', 'in_progress', 'in_review', 'blocked')`,
       ),
+    activeLivenessRecoveryIncidentIdx: uniqueIndex("issues_active_liveness_recovery_incident_uq")
+      .on(table.companyId, table.originKind, table.originId)
+      .where(
+        sql`${table.originKind} = 'harness_liveness_escalation'
+          and ${table.originId} is not null
+          and ${table.hiddenAt} is null
+          and ${table.status} not in ('done', 'cancelled')`,
+      ),
+    activeLivenessRecoveryLeafIdx: uniqueIndex("issues_active_liveness_recovery_leaf_uq")
+      .on(table.companyId, table.originKind, table.originFingerprint)
+      .where(
+        sql`${table.originKind} = 'harness_liveness_escalation'
+          and ${table.originFingerprint} <> 'default'
+          and ${table.hiddenAt} is null
+          and ${table.status} not in ('done', 'cancelled')`,
+      ),
+    activeStaleRunEvaluationIdx: uniqueIndex("issues_active_stale_run_evaluation_uq")
+      .on(table.companyId, table.originKind, table.originId)
+      .where(
+        sql`${table.originKind} = 'stale_active_run_evaluation'
+          and ${table.originId} is not null
+          and ${table.hiddenAt} is null
+          and ${table.status} not in ('done', 'cancelled')`,
+      ),
   }),
 );

packages/db/src/test-embedded-postgres.ts

@@ -33,77 +33,56 @@ export type EmbeddedPostgresTestDatabase = {
 
 let embeddedPostgresSupportPromise: Promise<EmbeddedPostgresTestSupport> | null = null;
 
+const DEFAULT_PAPERCLIP_EMBEDDED_POSTGRES_PORT = 54329;
+
+function getReservedTestPorts(): Set<number> {
+  const configuredPorts = [
+    DEFAULT_PAPERCLIP_EMBEDDED_POSTGRES_PORT,
+    Number.parseInt(process.env.PAPERCLIP_EMBEDDED_POSTGRES_PORT ?? "", 10),
+    ...String(process.env.PAPERCLIP_TEST_POSTGRES_RESERVED_PORTS ?? "")
+      .split(",")
+      .map((value) => Number.parseInt(value.trim(), 10)),
+  ];
+  return new Set(configuredPorts.filter((port) => Number.isInteger(port) && port > 0 && port <= 65535));
+}
+
 async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
   const mod = await import("embedded-postgres");
   return mod.default as EmbeddedPostgresCtor;
 }
 
 async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
+  const reservedPorts = getReservedTestPorts();
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const port = await new Promise<number>((resolve, reject) => {
+      const server = net.createServer();
+      server.unref();
+      server.on("error", reject);
+      server.listen(0, "127.0.0.1", () => {
+        const address = server.address();
+        if (!address || typeof address === "string") {
+          server.close(() => reject(new Error("Failed to allocate test port")));
+          return;
+        }
+        const { port } = address;
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve(port);
+        });
       });
     });
-  });
-}
 
-function formatEmbeddedPostgresError(error: unknown): string {
-  if (error instanceof Error && error.message.length > 0) return error.message;
-  if (typeof error === "string" && error.length > 0) return error;
-  return "embedded Postgres startup failed";
-}
-
-async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSupport> {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-embedded-postgres-probe-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-
-  try {
-    await instance.initialise();
-    await instance.start();
-    return { supported: true };
-  } catch (error) {
-    return {
-      supported: false,
-      reason: formatEmbeddedPostgresError(error),
-    };
-  } finally {
-    await instance.stop().catch(() => {});
-    fs.rmSync(dataDir, { recursive: true, force: true });
+    if (!reservedPorts.has(port)) return port;
   }
+
+  throw new Error(
+    `Failed to allocate embedded Postgres test port outside reserved Paperclip ports: ${[
+      ...reservedPorts,
+    ].join(", ")}`,
+  );
 }
 
-export async function getEmbeddedPostgresTestSupport(): Promise<EmbeddedPostgresTestSupport> {
-  if (!embeddedPostgresSupportPromise) {
-    embeddedPostgresSupportPromise = probeEmbeddedPostgresSupport();
-  }
-  return await embeddedPostgresSupportPromise;
-}
-
-export async function startEmbeddedPostgresTestDatabase(
-  tempDirPrefix: string,
-): Promise<EmbeddedPostgresTestDatabase> {
+async function createEmbeddedPostgresTestInstance(tempDirPrefix: string) {
   const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), tempDirPrefix));
   const port = await getAvailablePort();
   const EmbeddedPostgres = await getEmbeddedPostgresCtor();
@@ -118,6 +97,51 @@ export async function startEmbeddedPostgresTestDatabase(
     onError: () => {},
   });
 
+  return { dataDir, port, instance };
+}
+
+function cleanupEmbeddedPostgresTestDirs(dataDir: string) {
+  fs.rmSync(dataDir, { recursive: true, force: true });
+}
+
+function formatEmbeddedPostgresError(error: unknown): string {
+  if (error instanceof Error && error.message.length > 0) return error.message;
+  if (typeof error === "string" && error.length > 0) return error;
+  return "embedded Postgres startup failed";
+}
+
+async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSupport> {
+  const { dataDir, instance } = await createEmbeddedPostgresTestInstance(
+    "paperclip-embedded-postgres-probe-",
+  );
+
+  try {
+    await instance.initialise();
+    await instance.start();
+    return { supported: true };
+  } catch (error) {
+    return {
+      supported: false,
+      reason: formatEmbeddedPostgresError(error),
+    };
+  } finally {
+    await instance.stop().catch(() => {});
+    cleanupEmbeddedPostgresTestDirs(dataDir);
+  }
+}
+
+export async function getEmbeddedPostgresTestSupport(): Promise<EmbeddedPostgresTestSupport> {
+  if (!embeddedPostgresSupportPromise) {
+    embeddedPostgresSupportPromise = probeEmbeddedPostgresSupport();
+  }
+  return await embeddedPostgresSupportPromise;
+}
+
+export async function startEmbeddedPostgresTestDatabase(
+  tempDirPrefix: string,
+): Promise<EmbeddedPostgresTestDatabase> {
+  const { dataDir, port, instance } = await createEmbeddedPostgresTestInstance(tempDirPrefix);
+
   try {
     await instance.initialise();
     await instance.start();
@@ -131,12 +155,12 @@ export async function startEmbeddedPostgresTestDatabase(
       connectionString,
       cleanup: async () => {
         await instance.stop().catch(() => {});
-        fs.rmSync(dataDir, { recursive: true, force: true });
+        cleanupEmbeddedPostgresTestDirs(dataDir);
       },
     };
   } catch (error) {
     await instance.stop().catch(() => {});
-    fs.rmSync(dataDir, { recursive: true, force: true });
+    cleanupEmbeddedPostgresTestDirs(dataDir);
     throw new Error(
       `Failed to start embedded PostgreSQL test database: ${formatEmbeddedPostgresError(error)}`,
     );

packages/mcp-server/src/tools.ts

@@ -450,7 +450,7 @@ export function createToolDefinitions(client: PaperclipApiClient): ToolDefinitio
     ),
     makeTool(
       "paperclipUpdateIssue",
-      "Patch an issue, optionally including a comment",
+      "Patch an issue, optionally including a comment; include resume=true when intentionally requesting follow-up on resumable closed work",
       updateIssueToolSchema,
       async ({ issueId, ...body }) =>
         client.requestJson("PATCH", `/issues/${encodeURIComponent(issueId)}`, { body }),
@@ -475,7 +475,7 @@ export function createToolDefinitions(client: PaperclipApiClient): ToolDefinitio
     ),
     makeTool(
       "paperclipAddComment",
-      "Add a comment to an issue",
+      "Add a comment to an issue; include resume=true when intentionally requesting follow-up on resumable closed work",
       addCommentToolSchema,
       async ({ issueId, ...body }) =>
         client.requestJson("POST", `/issues/${encodeURIComponent(issueId)}/comments`, { body }),

packages/plugins/create-paperclip-plugin/src/index.ts

@@ -4,9 +4,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const VALID_TEMPLATES = ["default", "connector", "workspace"] as const;
+const VALID_TEMPLATES = ["default", "connector", "workspace", "environment"] as const;
 type PluginTemplate = (typeof VALID_TEMPLATES)[number];
-const VALID_CATEGORIES = new Set(["connector", "workspace", "automation", "ui"] as const);
+const VALID_CATEGORIES = new Set(["connector", "workspace", "automation", "ui", "environment"] as const);
 
 export interface ScaffoldPluginOptions {
   pluginName: string;
@@ -15,7 +15,7 @@ export interface ScaffoldPluginOptions {
   displayName?: string;
   description?: string;
   author?: string;
-  category?: "connector" | "workspace" | "automation" | "ui";
+  category?: "connector" | "workspace" | "automation" | "ui" | "environment";
   sdkPath?: string;
 }
 
@@ -138,7 +138,7 @@ export function scaffoldPluginProject(options: ScaffoldPluginOptions): string {
   const displayName = options.displayName ?? makeDisplayName(options.pluginName);
   const description = options.description ?? "A Paperclip plugin";
   const author = options.author ?? "Plugin Author";
-  const category = options.category ?? (template === "workspace" ? "workspace" : "connector");
+  const category = options.category ?? (template === "workspace" ? "workspace" : template === "environment" ? "environment" : "connector");
   const manifestId = packageToManifestId(options.pluginName);
   const localSdkPath = path.resolve(options.sdkPath ?? getLocalSdkPackagePath());
   const localSharedPath = getLocalSharedPackagePath(localSdkPath);
@@ -296,9 +296,231 @@ export default defineConfig({
 `,
   );
 
-  writeFile(
-    path.join(outputDir, "src", "manifest.ts"),
-    `import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+  if (template === "environment") {
+    writeFile(
+      path.join(outputDir, "src", "manifest.ts"),
+      `import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: ${quote(manifestId)},
+  apiVersion: 1,
+  version: "0.1.0",
+  displayName: ${quote(displayName)},
+  description: ${quote(description)},
+  author: ${quote(author)},
+  categories: [${quote(category)}],
+  capabilities: [
+    "environment.drivers.register",
+    "plugin.state.read",
+    "plugin.state.write"
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui"
+  },
+  environmentDrivers: [
+    {
+      driverKey: ${quote(manifestId + "-driver")},
+      displayName: ${quote(displayName + " Driver")}
+    }
+  ],
+  ui: {
+    slots: [
+      {
+        type: "dashboardWidget",
+        id: "health-widget",
+        displayName: ${quote(`${displayName} Health`)},
+        exportName: "DashboardWidget"
+      }
+    ]
+  }
+};
+
+export default manifest;
+`,
+    );
+
+    writeFile(
+      path.join(outputDir, "src", "worker.ts"),
+      `import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+import type {
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentExecuteParams,
+} from "@paperclipai/plugin-sdk";
+
+const plugin = definePlugin({
+  async setup(ctx) {
+    ctx.data.register("health", async () => {
+      return { status: "ok", checkedAt: new Date().toISOString() };
+    });
+  },
+
+  async onHealth() {
+    return { status: "ok", message: "Environment plugin worker is running" };
+  },
+
+  async onEnvironmentValidateConfig(params: PluginEnvironmentValidateConfigParams) {
+    if (!params.config || typeof params.config !== "object") {
+      return { ok: false, errors: ["Config must be a non-null object"] };
+    }
+    return { ok: true, normalizedConfig: params.config };
+  },
+
+  async onEnvironmentProbe(_params: PluginEnvironmentProbeParams) {
+    return { ok: true, summary: "Environment is reachable" };
+  },
+
+  async onEnvironmentAcquireLease(params: PluginEnvironmentAcquireLeaseParams) {
+    const providerLeaseId = \`lease-\${params.runId}-\${Date.now()}\`;
+    return {
+      providerLeaseId,
+      metadata: { acquiredAt: new Date().toISOString() },
+    };
+  },
+
+  async onEnvironmentResumeLease(params: PluginEnvironmentResumeLeaseParams) {
+    return {
+      providerLeaseId: params.providerLeaseId,
+      metadata: { ...params.leaseMetadata, resumed: true },
+    };
+  },
+
+  async onEnvironmentReleaseLease(_params: PluginEnvironmentReleaseLeaseParams) {
+    // Release provider-side resources here
+  },
+
+  async onEnvironmentDestroyLease(_params: PluginEnvironmentDestroyLeaseParams) {
+    // Destroy provider-side resources here
+  },
+
+  async onEnvironmentRealizeWorkspace(params: PluginEnvironmentRealizeWorkspaceParams) {
+    const cwd = params.workspace.remotePath ?? params.workspace.localPath ?? "/tmp/workspace";
+    return { cwd, metadata: { realized: true } };
+  },
+
+  async onEnvironmentExecute(params: PluginEnvironmentExecuteParams) {
+    // Replace this with real command execution against your provider
+    return {
+      exitCode: 0,
+      timedOut: false,
+      stdout: \`Executed: \${params.command}\`,
+      stderr: "",
+    };
+  },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
+`,
+    );
+
+    writeFile(
+      path.join(outputDir, "src", "ui", "index.tsx"),
+      `import { usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
+
+type HealthData = {
+  status: "ok" | "degraded" | "error";
+  checkedAt: string;
+};
+
+export function DashboardWidget(_props: PluginWidgetProps) {
+  const { data, loading, error } = usePluginData<HealthData>("health");
+
+  if (loading) return <div>Loading environment health...</div>;
+  if (error) return <div>Plugin error: {error.message}</div>;
+
+  return (
+    <div style={{ display: "grid", gap: "0.5rem" }}>
+      <strong>${displayName}</strong>
+      <div>Health: {data?.status ?? "unknown"}</div>
+      <div>Checked: {data?.checkedAt ?? "never"}</div>
+    </div>
+  );
+}
+`,
+    );
+
+    writeFile(
+      path.join(outputDir, "tests", "plugin.spec.ts"),
+      `import { describe, expect, it } from "vitest";
+import {
+  createEnvironmentTestHarness,
+  createFakeEnvironmentDriver,
+  assertEnvironmentEventOrder,
+  assertLeaseLifecycle,
+} from "@paperclipai/plugin-sdk/testing";
+import manifest from "../src/manifest.js";
+import plugin from "../src/worker.js";
+
+const ENV_ID = "env-test-1";
+const BASE_PARAMS = {
+  driverKey: manifest.environmentDrivers![0].driverKey,
+  companyId: "co-1",
+  environmentId: ENV_ID,
+  config: {},
+};
+
+describe("environment plugin scaffold", () => {
+  it("validates config", async () => {
+    const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
+    const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: BASE_PARAMS.driverKey,
+      config: { host: "test" },
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it("probes the environment", async () => {
+    const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
+    const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await plugin.definition.onEnvironmentProbe!(BASE_PARAMS);
+    expect(result.ok).toBe(true);
+  });
+
+  it("runs a full lease lifecycle through the harness", async () => {
+    const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
+    const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
+    await plugin.definition.setup(harness.ctx);
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    expect(lease.providerLeaseId).toBeTruthy();
+
+    await harness.realizeWorkspace({
+      ...BASE_PARAMS,
+      lease,
+      workspace: { localPath: "/tmp/test" },
+    });
+
+    await harness.releaseLease({
+      ...BASE_PARAMS,
+      providerLeaseId: lease.providerLeaseId,
+    });
+
+    assertEnvironmentEventOrder(harness.environmentEvents, [
+      "acquireLease",
+      "realizeWorkspace",
+      "releaseLease",
+    ]);
+    assertLeaseLifecycle(harness.environmentEvents, ENV_ID);
+  });
+});
+`,
+    );
+  } else {
+    writeFile(
+      path.join(outputDir, "src", "manifest.ts"),
+      `import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
 
 const manifest: PaperclipPluginManifestV1 = {
   id: ${quote(manifestId)},
@@ -331,11 +553,11 @@ const manifest: PaperclipPluginManifestV1 = {
 
 export default manifest;
 `,
-  );
+    );
 
-  writeFile(
-    path.join(outputDir, "src", "worker.ts"),
-    `import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
+    writeFile(
+      path.join(outputDir, "src", "worker.ts"),
+      `import { definePlugin, runWorker } from "@paperclipai/plugin-sdk";
 
 const plugin = definePlugin({
   async setup(ctx) {
@@ -363,11 +585,11 @@ const plugin = definePlugin({
 export default plugin;
 runWorker(plugin, import.meta.url);
 `,
-  );
+    );
 
-  writeFile(
-    path.join(outputDir, "src", "ui", "index.tsx"),
-    `import { usePluginAction, usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
+    writeFile(
+      path.join(outputDir, "src", "ui", "index.tsx"),
+      `import { usePluginAction, usePluginData, type PluginWidgetProps } from "@paperclipai/plugin-sdk/ui";
 
 type HealthData = {
   status: "ok" | "degraded" | "error";
@@ -391,11 +613,11 @@ export function DashboardWidget(_props: PluginWidgetProps) {
   );
 }
 `,
-  );
+    );
 
-  writeFile(
-    path.join(outputDir, "tests", "plugin.spec.ts"),
-    `import { describe, expect, it } from "vitest";
+    writeFile(
+      path.join(outputDir, "tests", "plugin.spec.ts"),
+      `import { describe, expect, it } from "vitest";
 import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
 import manifest from "../src/manifest.js";
 import plugin from "../src/worker.js";
@@ -416,7 +638,8 @@ describe("plugin scaffold", () => {
   });
 });
 `,
-  );
+    );
+  }
 
   writeFile(
     path.join(outputDir, "README.md"),

packages/plugins/paperclip-plugin-fake-sandbox/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@paperclipai/plugin-fake-sandbox",
+  "version": "0.1.0",
+  "description": "First-party deterministic fake sandbox provider plugin for Paperclip environments",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js"
+  },
+  "scripts": {
+    "prebuild": "node ../../../scripts/ensure-plugin-build-deps.mjs",
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "pnpm --filter @paperclipai/plugin-sdk build && tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@paperclipai/plugin-sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  }
+}

packages/plugins/paperclip-plugin-fake-sandbox/src/index.ts

@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as plugin } from "./plugin.js";

packages/plugins/paperclip-plugin-fake-sandbox/src/manifest.ts

@@ -0,0 +1,50 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const PLUGIN_ID = "paperclip.fake-sandbox-provider";
+const PLUGIN_VERSION = "0.1.0";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: PLUGIN_VERSION,
+  displayName: "Fake Sandbox Provider",
+  description:
+    "First-party deterministic sandbox provider plugin for exercising Paperclip provider-plugin integration without external infrastructure.",
+  author: "Paperclip",
+  categories: ["automation"],
+  capabilities: ["environment.drivers.register"],
+  entrypoints: {
+    worker: "./dist/worker.js",
+  },
+  environmentDrivers: [
+    {
+      driverKey: "fake-plugin",
+      kind: "sandbox_provider",
+      displayName: "Fake Sandbox Provider",
+      description:
+        "Runs commands in an isolated local temporary directory while exercising the sandbox provider plugin lifecycle.",
+      configSchema: {
+        type: "object",
+        properties: {
+          image: {
+            type: "string",
+            description: "Deterministic fake image label for metadata and matching.",
+            default: "fake:latest",
+          },
+          timeoutMs: {
+            type: "number",
+            description: "Command timeout in milliseconds.",
+            default: 300000,
+          },
+          reuseLease: {
+            type: "boolean",
+            description: "Whether to reuse fake leases by environment id.",
+            default: false,
+          },
+        },
+      },
+    },
+  ],
+};
+
+export default manifest;

packages/plugins/paperclip-plugin-fake-sandbox/src/plugin.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it } from "vitest";
+import {
+  assertEnvironmentEventOrder,
+  createEnvironmentTestHarness,
+} from "@paperclipai/plugin-sdk/testing";
+import manifest from "./manifest.js";
+import plugin from "./plugin.js";
+
+describe("fake sandbox provider plugin", () => {
+  it("runs a deterministic provider lifecycle through environment hooks", async () => {
+    const definition = plugin.definition;
+    const harness = createEnvironmentTestHarness({
+      manifest,
+      environmentDriver: {
+        driverKey: "fake-plugin",
+        onValidateConfig: definition.onEnvironmentValidateConfig,
+        onProbe: definition.onEnvironmentProbe,
+        onAcquireLease: definition.onEnvironmentAcquireLease,
+        onResumeLease: definition.onEnvironmentResumeLease,
+        onReleaseLease: definition.onEnvironmentReleaseLease,
+        onDestroyLease: definition.onEnvironmentDestroyLease,
+        onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+        onExecute: definition.onEnvironmentExecute,
+      },
+    });
+    const base = {
+      driverKey: "fake-plugin",
+      companyId: "company-1",
+      environmentId: "env-1",
+      config: { image: "fake:test", reuseLease: false },
+    };
+
+    const validation = await harness.validateConfig({
+      driverKey: "fake-plugin",
+      config: base.config,
+    });
+    expect(validation).toMatchObject({
+      ok: true,
+      normalizedConfig: { image: "fake:test", reuseLease: false },
+    });
+
+    const probe = await harness.probe(base);
+    expect(probe).toMatchObject({
+      ok: true,
+      metadata: { provider: "fake-plugin", image: "fake:test" },
+    });
+
+    const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+    expect(lease.providerLeaseId).toContain("fake-plugin://run-1/");
+
+    const realized = await harness.realizeWorkspace({
+      ...base,
+      lease,
+      workspace: { mode: "isolated_workspace" },
+    });
+    expect(realized.cwd).toContain("paperclip-fake-sandbox-");
+
+    const executed = await harness.execute({
+      ...base,
+      lease,
+      command: "sh",
+      args: ["-lc", "printf fake-plugin-ok"],
+      cwd: realized.cwd,
+      timeoutMs: 10_000,
+    });
+    expect(executed).toMatchObject({
+      exitCode: 0,
+      timedOut: false,
+      stdout: "fake-plugin-ok",
+    });
+
+    await harness.destroyLease({
+      ...base,
+      providerLeaseId: lease.providerLeaseId,
+    });
+
+    assertEnvironmentEventOrder(harness.environmentEvents, [
+      "validateConfig",
+      "probe",
+      "acquireLease",
+      "realizeWorkspace",
+      "execute",
+      "destroyLease",
+    ]);
+  });
+
+  it("does not expose host-only environment variables to executed commands", async () => {
+    const previousSecret = process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET;
+    process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET = "should-not-leak";
+    try {
+      const definition = plugin.definition;
+      const harness = createEnvironmentTestHarness({
+        manifest,
+        environmentDriver: {
+          driverKey: "fake-plugin",
+          onAcquireLease: definition.onEnvironmentAcquireLease,
+          onDestroyLease: definition.onEnvironmentDestroyLease,
+          onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+          onExecute: definition.onEnvironmentExecute,
+        },
+      });
+      const base = {
+        driverKey: "fake-plugin",
+        companyId: "company-1",
+        environmentId: "env-1",
+        config: { image: "fake:test", reuseLease: false },
+      };
+      const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+      const realized = await harness.realizeWorkspace({
+        ...base,
+        lease,
+        workspace: { mode: "isolated_workspace" },
+      });
+
+      const executed = await harness.execute({
+        ...base,
+        lease,
+        command: "sh",
+        args: ["-lc", "test -z \"${PAPERCLIP_FAKE_PLUGIN_HOST_SECRET+x}\" && printf \"$EXPLICIT_ONLY\""],
+        cwd: realized.cwd,
+        env: { EXPLICIT_ONLY: "visible" },
+        timeoutMs: 10_000,
+      });
+
+      expect(executed).toMatchObject({
+        exitCode: 0,
+        timedOut: false,
+        stdout: "visible",
+      });
+
+      await harness.destroyLease({
+        ...base,
+        providerLeaseId: lease.providerLeaseId,
+      });
+    } finally {
+      if (previousSecret === undefined) {
+        delete process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET;
+      } else {
+        process.env.PAPERCLIP_FAKE_PLUGIN_HOST_SECRET = previousSecret;
+      }
+    }
+  });
+
+  it("includes /usr/local/bin in the default PATH when no PATH override is provided", async () => {
+    const definition = plugin.definition;
+    const harness = createEnvironmentTestHarness({
+      manifest,
+      environmentDriver: {
+        driverKey: "fake-plugin",
+        onAcquireLease: definition.onEnvironmentAcquireLease,
+        onDestroyLease: definition.onEnvironmentDestroyLease,
+        onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+        onExecute: definition.onEnvironmentExecute,
+      },
+    });
+    const base = {
+      driverKey: "fake-plugin",
+      companyId: "company-1",
+      environmentId: "env-1",
+      config: { image: "fake:test", reuseLease: false },
+    };
+    const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+    const realized = await harness.realizeWorkspace({
+      ...base,
+      lease,
+      workspace: { mode: "isolated_workspace" },
+    });
+
+    const executed = await harness.execute({
+      ...base,
+      lease,
+      command: "sh",
+      args: ["-lc", "printf %s \"$PATH\""],
+      cwd: realized.cwd,
+      timeoutMs: 10_000,
+    });
+
+    expect(executed.stdout).toContain("/usr/local/bin");
+
+    await harness.destroyLease({
+      ...base,
+      providerLeaseId: lease.providerLeaseId,
+    });
+  });
+
+  it("escalates to SIGKILL after timeout if the child ignores SIGTERM", async () => {
+    const definition = plugin.definition;
+    const harness = createEnvironmentTestHarness({
+      manifest,
+      environmentDriver: {
+        driverKey: "fake-plugin",
+        onAcquireLease: definition.onEnvironmentAcquireLease,
+        onDestroyLease: definition.onEnvironmentDestroyLease,
+        onRealizeWorkspace: definition.onEnvironmentRealizeWorkspace,
+        onExecute: definition.onEnvironmentExecute,
+      },
+    });
+    const base = {
+      driverKey: "fake-plugin",
+      companyId: "company-1",
+      environmentId: "env-1",
+      config: { image: "fake:test", reuseLease: false },
+    };
+    const lease = await harness.acquireLease({ ...base, runId: "run-1" });
+    const realized = await harness.realizeWorkspace({
+      ...base,
+      lease,
+      workspace: { mode: "isolated_workspace" },
+    });
+
+    const executed = await harness.execute({
+      ...base,
+      lease,
+      command: "sh",
+      args: ["-lc", "trap '' TERM; while :; do sleep 1; done"],
+      cwd: realized.cwd,
+      timeoutMs: 100,
+    });
+
+    expect(executed.timedOut).toBe(true);
+    expect(executed.exitCode).toBeNull();
+
+    await harness.destroyLease({
+      ...base,
+      providerLeaseId: lease.providerLeaseId,
+    });
+  });
+});

packages/plugins/paperclip-plugin-fake-sandbox/src/plugin.ts

@@ -0,0 +1,282 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { definePlugin } from "@paperclipai/plugin-sdk";
+import type {
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentExecuteResult,
+  PluginEnvironmentLease,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentProbeResult,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentRealizeWorkspaceResult,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentValidationResult,
+} from "@paperclipai/plugin-sdk";
+
+interface FakeDriverConfig {
+  image: string;
+  timeoutMs: number;
+  reuseLease: boolean;
+}
+
+interface FakeLeaseState {
+  providerLeaseId: string;
+  rootDir: string;
+  remoteCwd: string;
+  image: string;
+  reuseLease: boolean;
+}
+
+const leases = new Map<string, FakeLeaseState>();
+const DEFAULT_FAKE_SANDBOX_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+const FAKE_SANDBOX_SIGKILL_GRACE_MS = 250;
+
+function parseConfig(raw: Record<string, unknown>): FakeDriverConfig {
+  return {
+    image: typeof raw.image === "string" && raw.image.trim().length > 0 ? raw.image.trim() : "fake:latest",
+    timeoutMs: typeof raw.timeoutMs === "number" && Number.isFinite(raw.timeoutMs) ? raw.timeoutMs : 300_000,
+    reuseLease: raw.reuseLease === true,
+  };
+}
+
+async function createLeaseState(input: {
+  providerLeaseId: string;
+  image: string;
+  reuseLease: boolean;
+}): Promise<FakeLeaseState> {
+  const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-fake-sandbox-"));
+  const remoteCwd = path.join(rootDir, "workspace");
+  await mkdir(remoteCwd, { recursive: true });
+  const state = {
+    providerLeaseId: input.providerLeaseId,
+    rootDir,
+    remoteCwd,
+    image: input.image,
+    reuseLease: input.reuseLease,
+  };
+  leases.set(input.providerLeaseId, state);
+  return state;
+}
+
+function leaseMetadata(state: FakeLeaseState) {
+  return {
+    provider: "fake-plugin",
+    image: state.image,
+    reuseLease: state.reuseLease,
+    remoteCwd: state.remoteCwd,
+    fakeRootDir: state.rootDir,
+  };
+}
+
+async function removeLease(providerLeaseId: string | null | undefined): Promise<void> {
+  if (!providerLeaseId) return;
+  const state = leases.get(providerLeaseId);
+  leases.delete(providerLeaseId);
+  if (state) {
+    await rm(state.rootDir, { recursive: true, force: true });
+  }
+}
+
+function buildCommandLine(command: string, args: string[] | undefined): string {
+  return [command, ...(args ?? [])].join(" ");
+}
+
+function buildCommandEnvironment(explicitEnv: Record<string, string> | undefined): Record<string, string> {
+  return {
+    PATH: explicitEnv?.PATH ?? DEFAULT_FAKE_SANDBOX_PATH,
+    ...(explicitEnv ?? {}),
+  };
+}
+
+async function runCommand(params: PluginEnvironmentExecuteParams, timeoutMs: number): Promise<PluginEnvironmentExecuteResult> {
+  const cwd = typeof params.cwd === "string" && params.cwd.length > 0 ? params.cwd : process.cwd();
+  const startedAt = new Date().toISOString();
+
+  return await new Promise((resolve, reject) => {
+    const child = spawn(params.command, params.args ?? [], {
+      cwd,
+      env: buildCommandEnvironment(params.env),
+      shell: false,
+      stdio: [params.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let killTimer: NodeJS.Timeout | null = null;
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          child.kill("SIGTERM");
+          killTimer = setTimeout(() => {
+            child.kill("SIGKILL");
+          }, FAKE_SANDBOX_SIGKILL_GRACE_MS);
+        }, timeoutMs)
+      : null;
+
+    child.stdout?.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      if (timer) clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve({
+        exitCode: timedOut ? null : code,
+        signal,
+        timedOut,
+        stdout,
+        stderr,
+        metadata: {
+          startedAt,
+          commandLine: buildCommandLine(params.command, params.args),
+        },
+      });
+    });
+
+    if (params.stdin != null && child.stdin) {
+      child.stdin.write(params.stdin);
+      child.stdin.end();
+    }
+  });
+}
+
+const plugin = definePlugin({
+  async setup(ctx) {
+    ctx.logger.info("Fake sandbox provider plugin ready");
+  },
+
+  async onHealth() {
+    return { status: "ok", message: "Fake sandbox provider plugin healthy" };
+  },
+
+  async onEnvironmentValidateConfig(
+    params: PluginEnvironmentValidateConfigParams,
+  ): Promise<PluginEnvironmentValidationResult> {
+    const config = parseConfig(params.config);
+    return {
+      ok: true,
+      normalizedConfig: { ...config },
+    };
+  },
+
+  async onEnvironmentProbe(
+    params: PluginEnvironmentProbeParams,
+  ): Promise<PluginEnvironmentProbeResult> {
+    const config = parseConfig(params.config);
+    return {
+      ok: true,
+      summary: `Fake sandbox provider is ready for image ${config.image}.`,
+      metadata: {
+        provider: "fake-plugin",
+        image: config.image,
+        timeoutMs: config.timeoutMs,
+        reuseLease: config.reuseLease,
+      },
+    };
+  },
+
+  async onEnvironmentAcquireLease(
+    params: PluginEnvironmentAcquireLeaseParams,
+  ): Promise<PluginEnvironmentLease> {
+    const config = parseConfig(params.config);
+    const providerLeaseId = config.reuseLease
+      ? `fake-plugin://${params.environmentId}`
+      : `fake-plugin://${params.runId}/${randomUUID()}`;
+    const existing = leases.get(providerLeaseId);
+    const state = existing ?? await createLeaseState({
+      providerLeaseId,
+      image: config.image,
+      reuseLease: config.reuseLease,
+    });
+
+    return {
+      providerLeaseId,
+      metadata: {
+        ...leaseMetadata(state),
+        resumedLease: Boolean(existing),
+      },
+    };
+  },
+
+  async onEnvironmentResumeLease(
+    params: PluginEnvironmentResumeLeaseParams,
+  ): Promise<PluginEnvironmentLease> {
+    const config = parseConfig(params.config);
+    const existing = leases.get(params.providerLeaseId);
+    const state = existing ?? await createLeaseState({
+      providerLeaseId: params.providerLeaseId,
+      image: config.image,
+      reuseLease: config.reuseLease,
+    });
+
+    return {
+      providerLeaseId: state.providerLeaseId,
+      metadata: {
+        ...leaseMetadata(state),
+        resumedLease: true,
+      },
+    };
+  },
+
+  async onEnvironmentReleaseLease(
+    params: PluginEnvironmentReleaseLeaseParams,
+  ): Promise<void> {
+    const config = parseConfig(params.config);
+    if (!config.reuseLease) {
+      await removeLease(params.providerLeaseId);
+    }
+  },
+
+  async onEnvironmentDestroyLease(
+    params: PluginEnvironmentDestroyLeaseParams,
+  ): Promise<void> {
+    await removeLease(params.providerLeaseId);
+  },
+
+  async onEnvironmentRealizeWorkspace(
+    params: PluginEnvironmentRealizeWorkspaceParams,
+  ): Promise<PluginEnvironmentRealizeWorkspaceResult> {
+    const state = params.lease.providerLeaseId
+      ? leases.get(params.lease.providerLeaseId)
+      : null;
+    const remoteCwd =
+      state?.remoteCwd ??
+      (typeof params.lease.metadata?.remoteCwd === "string" ? params.lease.metadata.remoteCwd : null) ??
+      params.workspace.remotePath ??
+      params.workspace.localPath ??
+      path.join(os.tmpdir(), "paperclip-fake-sandbox-workspace");
+
+    await mkdir(remoteCwd, { recursive: true });
+
+    return {
+      cwd: remoteCwd,
+      metadata: {
+        provider: "fake-plugin",
+        remoteCwd,
+      },
+    };
+  },
+
+  async onEnvironmentExecute(
+    params: PluginEnvironmentExecuteParams,
+  ): Promise<PluginEnvironmentExecuteResult> {
+    const config = parseConfig(params.config);
+    return await runCommand(params, params.timeoutMs ?? config.timeoutMs);
+  },
+});
+
+export default plugin;

packages/plugins/paperclip-plugin-fake-sandbox/src/worker.ts

@@ -0,0 +1,5 @@
+import { runWorker } from "@paperclipai/plugin-sdk";
+import plugin from "./plugin.js";
+
+export default plugin;
+runWorker(plugin, import.meta.url);

packages/plugins/paperclip-plugin-fake-sandbox/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2023"],
+    "types": ["node", "vitest"]
+  },
+  "include": ["src"]
+}

packages/plugins/paperclip-plugin-fake-sandbox/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    environment: "node",
+  },
+});

packages/plugins/sdk/README.md

@@ -337,6 +337,7 @@ Declare in `manifest.capabilities`. Grouped by scope:
 | | `api.routes.register` |
 | | `http.outbound` |
 | | `secrets.read-ref` |
+| | `environment.drivers.register` |
 | **Agent** | `agent.tools.register` |
 | | `agents.invoke` |
 | | `agent.sessions.create` |

packages/plugins/sdk/src/define-plugin.ts

@@ -48,6 +48,21 @@
  */
 
 import type { PluginContext } from "./types.js";
+import type {
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentExecuteResult,
+  PluginEnvironmentLease,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentProbeResult,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentRealizeWorkspaceResult,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentValidationResult,
+} from "./protocol.js";
 
 // ---------------------------------------------------------------------------
 // Health check result
@@ -228,6 +243,48 @@ export interface PluginDefinition {
    * access, capabilities, and checkout policy.
    */
   onApiRequest?(input: PluginApiRequestInput): Promise<PluginApiResponse>;
+  /**
+   * Called to validate provider-specific configuration for a plugin-hosted
+   * environment driver.
+   */
+  onEnvironmentValidateConfig?(
+    params: PluginEnvironmentValidateConfigParams,
+  ): Promise<PluginEnvironmentValidationResult>;
+
+  /** Called to test reachability or readiness of a plugin-hosted environment. */
+  onEnvironmentProbe?(
+    params: PluginEnvironmentProbeParams,
+  ): Promise<PluginEnvironmentProbeResult>;
+
+  /** Called before a run starts to acquire a provider lease. */
+  onEnvironmentAcquireLease?(
+    params: PluginEnvironmentAcquireLeaseParams,
+  ): Promise<PluginEnvironmentLease>;
+
+  /** Called to reconnect to a previously acquired provider lease. */
+  onEnvironmentResumeLease?(
+    params: PluginEnvironmentResumeLeaseParams,
+  ): Promise<PluginEnvironmentLease>;
+
+  /** Called when a run finishes and the provider lease can be released. */
+  onEnvironmentReleaseLease?(
+    params: PluginEnvironmentReleaseLeaseParams,
+  ): Promise<void>;
+
+  /** Called when the host needs to force-destroy provider state. */
+  onEnvironmentDestroyLease?(
+    params: PluginEnvironmentDestroyLeaseParams,
+  ): Promise<void>;
+
+  /** Called to materialize the run workspace inside the provider lease. */
+  onEnvironmentRealizeWorkspace?(
+    params: PluginEnvironmentRealizeWorkspaceParams,
+  ): Promise<PluginEnvironmentRealizeWorkspaceResult>;
+
+  /** Called to execute a command inside the provider lease. */
+  onEnvironmentExecute?(
+    params: PluginEnvironmentExecuteParams,
+  ): Promise<PluginEnvironmentExecuteResult>;
 }
 
 // ---------------------------------------------------------------------------

packages/plugins/sdk/src/index.ts

@@ -50,7 +50,7 @@
 // ---------------------------------------------------------------------------
 
 export { definePlugin } from "./define-plugin.js";
-export { createTestHarness } from "./testing.js";
+export { createTestHarness, createEnvironmentTestHarness, createFakeEnvironmentDriver, filterEnvironmentEvents, assertEnvironmentEventOrder, assertLeaseLifecycle, assertWorkspaceRealizationLifecycle, assertExecutionLifecycle, assertEnvironmentError } from "./testing.js";
 export { createPluginBundlerPresets } from "./bundlers.js";
 export { startPluginDevServer, getUiBuildSnapshot } from "./dev-server.js";
 export { startWorkerRpcHost, runWorker } from "./worker-rpc-host.js";
@@ -102,6 +102,10 @@ export type {
   TestHarness,
   TestHarnessOptions,
   TestHarnessLogEntry,
+  EnvironmentTestHarness,
+  EnvironmentTestHarnessOptions,
+  EnvironmentEventRecord,
+  FakeEnvironmentDriverOptions,
 } from "./testing.js";
 export type {
   PluginBundlerPresetInput,
@@ -142,6 +146,21 @@ export type {
   GetDataParams,
   PerformActionParams,
   ExecuteToolParams,
+  PluginEnvironmentDiagnostic,
+  PluginEnvironmentDriverBaseParams,
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentValidationResult,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentProbeResult,
+  PluginEnvironmentLease,
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentRealizeWorkspaceResult,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentExecuteResult,
   PluginModalBoundsRequest,
   PluginRenderCloseEvent,
   PluginLauncherRenderContextSnapshot,
@@ -235,6 +254,7 @@ export type {
   PluginJobDeclaration,
   PluginWebhookDeclaration,
   PluginToolDeclaration,
+  PluginEnvironmentDriverDeclaration,
   PluginUiSlotDeclaration,
   PluginUiDeclaration,
   PluginLauncherActionDeclaration,

packages/plugins/sdk/src/protocol.ts

@@ -325,6 +325,99 @@ export interface ExecuteToolParams {
   runContext: ToolRunContext;
 }
 
+export interface PluginEnvironmentDiagnostic {
+  severity: "info" | "warning" | "error";
+  message: string;
+  code?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentDriverBaseParams {
+  driverKey: string;
+  companyId: string;
+  environmentId: string;
+  config: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentValidateConfigParams {
+  driverKey: string;
+  config: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentValidationResult {
+  ok: boolean;
+  warnings?: string[];
+  errors?: string[];
+  normalizedConfig?: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentProbeParams extends PluginEnvironmentDriverBaseParams {}
+
+export interface PluginEnvironmentProbeResult {
+  ok: boolean;
+  summary?: string;
+  diagnostics?: PluginEnvironmentDiagnostic[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentLease {
+  providerLeaseId: string | null;
+  metadata?: Record<string, unknown>;
+  expiresAt?: string | null;
+}
+
+export interface PluginEnvironmentAcquireLeaseParams extends PluginEnvironmentDriverBaseParams {
+  runId: string;
+  workspaceMode?: string;
+  requestedCwd?: string;
+}
+
+export interface PluginEnvironmentResumeLeaseParams extends PluginEnvironmentDriverBaseParams {
+  providerLeaseId: string;
+  leaseMetadata?: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentReleaseLeaseParams extends PluginEnvironmentDriverBaseParams {
+  providerLeaseId: string | null;
+  leaseMetadata?: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentDestroyLeaseParams extends PluginEnvironmentReleaseLeaseParams {}
+
+export interface PluginEnvironmentRealizeWorkspaceParams extends PluginEnvironmentDriverBaseParams {
+  lease: PluginEnvironmentLease;
+  workspace: {
+    localPath?: string;
+    remotePath?: string;
+    mode?: string;
+    metadata?: Record<string, unknown>;
+  };
+}
+
+export interface PluginEnvironmentRealizeWorkspaceResult {
+  cwd: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PluginEnvironmentExecuteParams extends PluginEnvironmentDriverBaseParams {
+  lease: PluginEnvironmentLease;
+  command: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+  timeoutMs?: number;
+}
+
+export interface PluginEnvironmentExecuteResult {
+  exitCode: number | null;
+  signal?: string | null;
+  timedOut: boolean;
+  stdout: string;
+  stderr: string;
+  metadata?: Record<string, unknown>;
+}
+
 // ---------------------------------------------------------------------------
 // UI launcher / modal host interaction payloads
 // ---------------------------------------------------------------------------
@@ -394,6 +487,38 @@ export interface HostToWorkerMethods {
   performAction: [params: PerformActionParams, result: unknown];
   /** @see PLUGIN_SPEC.md §13.10 */
   executeTool: [params: ExecuteToolParams, result: ToolResult];
+  environmentValidateConfig: [
+    params: PluginEnvironmentValidateConfigParams,
+    result: PluginEnvironmentValidationResult,
+  ];
+  environmentProbe: [
+    params: PluginEnvironmentProbeParams,
+    result: PluginEnvironmentProbeResult,
+  ];
+  environmentAcquireLease: [
+    params: PluginEnvironmentAcquireLeaseParams,
+    result: PluginEnvironmentLease,
+  ];
+  environmentResumeLease: [
+    params: PluginEnvironmentResumeLeaseParams,
+    result: PluginEnvironmentLease,
+  ];
+  environmentReleaseLease: [
+    params: PluginEnvironmentReleaseLeaseParams,
+    result: void,
+  ];
+  environmentDestroyLease: [
+    params: PluginEnvironmentDestroyLeaseParams,
+    result: void,
+  ];
+  environmentRealizeWorkspace: [
+    params: PluginEnvironmentRealizeWorkspaceParams,
+    result: PluginEnvironmentRealizeWorkspaceResult,
+  ];
+  environmentExecute: [
+    params: PluginEnvironmentExecuteParams,
+    result: PluginEnvironmentExecuteResult,
+  ];
 }
 
 /** Union of all host→worker method names. */
@@ -417,6 +542,14 @@ export const HOST_TO_WORKER_OPTIONAL_METHODS: readonly HostToWorkerMethodName[]
   "getData",
   "performAction",
   "executeTool",
+  "environmentValidateConfig",
+  "environmentProbe",
+  "environmentAcquireLease",
+  "environmentResumeLease",
+  "environmentReleaseLease",
+  "environmentDestroyLease",
+  "environmentRealizeWorkspace",
+  "environmentExecute",
 ] as const;
 
 // ---------------------------------------------------------------------------

packages/plugins/sdk/src/testing.ts

@@ -29,6 +29,21 @@ import type {
   AgentSession,
   AgentSessionEvent,
 } from "./types.js";
+import type {
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentValidationResult,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentProbeResult,
+  PluginEnvironmentLease,
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentRealizeWorkspaceResult,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentExecuteResult,
+} from "./protocol.js";
 
 export interface TestHarnessOptions {
   /** Plugin manifest used to seed capability checks and metadata. */
@@ -80,6 +95,262 @@ export interface TestHarness {
   dbExecutes: Array<{ sql: string; params?: unknown[] }>;
 }
 
+// ---------------------------------------------------------------------------
+// Environment test harness types
+// ---------------------------------------------------------------------------
+
+/** Recorded environment lifecycle event for assertion helpers. */
+export interface EnvironmentEventRecord {
+  type:
+    | "validateConfig"
+    | "probe"
+    | "acquireLease"
+    | "resumeLease"
+    | "releaseLease"
+    | "destroyLease"
+    | "realizeWorkspace"
+    | "execute";
+  driverKey: string;
+  environmentId: string;
+  timestamp: string;
+  params: Record<string, unknown>;
+  result?: unknown;
+  error?: string;
+}
+
+/** Options for creating an environment-aware test harness. */
+export interface EnvironmentTestHarnessOptions extends TestHarnessOptions {
+  /** Environment driver hooks provided by the plugin under test. */
+  environmentDriver: {
+    driverKey: string;
+    onValidateConfig?: (params: PluginEnvironmentValidateConfigParams) => Promise<PluginEnvironmentValidationResult>;
+    onProbe?: (params: PluginEnvironmentProbeParams) => Promise<PluginEnvironmentProbeResult>;
+    onAcquireLease?: (params: PluginEnvironmentAcquireLeaseParams) => Promise<PluginEnvironmentLease>;
+    onResumeLease?: (params: PluginEnvironmentResumeLeaseParams) => Promise<PluginEnvironmentLease>;
+    onReleaseLease?: (params: PluginEnvironmentReleaseLeaseParams) => Promise<void>;
+    onDestroyLease?: (params: PluginEnvironmentDestroyLeaseParams) => Promise<void>;
+    onRealizeWorkspace?: (params: PluginEnvironmentRealizeWorkspaceParams) => Promise<PluginEnvironmentRealizeWorkspaceResult>;
+    onExecute?: (params: PluginEnvironmentExecuteParams) => Promise<PluginEnvironmentExecuteResult>;
+  };
+}
+
+/** Extended test harness with environment driver simulation. */
+export interface EnvironmentTestHarness extends TestHarness {
+  /** Recorded environment lifecycle events for assertion. */
+  environmentEvents: EnvironmentEventRecord[];
+  /** Invoke the environment driver's validateConfig hook. */
+  validateConfig(params: PluginEnvironmentValidateConfigParams): Promise<PluginEnvironmentValidationResult>;
+  /** Invoke the environment driver's probe hook. */
+  probe(params: PluginEnvironmentProbeParams): Promise<PluginEnvironmentProbeResult>;
+  /** Invoke the environment driver's acquireLease hook. */
+  acquireLease(params: PluginEnvironmentAcquireLeaseParams): Promise<PluginEnvironmentLease>;
+  /** Invoke the environment driver's resumeLease hook. */
+  resumeLease(params: PluginEnvironmentResumeLeaseParams): Promise<PluginEnvironmentLease>;
+  /** Invoke the environment driver's releaseLease hook. */
+  releaseLease(params: PluginEnvironmentReleaseLeaseParams): Promise<void>;
+  /** Invoke the environment driver's destroyLease hook. */
+  destroyLease(params: PluginEnvironmentDestroyLeaseParams): Promise<void>;
+  /** Invoke the environment driver's realizeWorkspace hook. */
+  realizeWorkspace(params: PluginEnvironmentRealizeWorkspaceParams): Promise<PluginEnvironmentRealizeWorkspaceResult>;
+  /** Invoke the environment driver's execute hook. */
+  execute(params: PluginEnvironmentExecuteParams): Promise<PluginEnvironmentExecuteResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Environment event assertion helpers
+// ---------------------------------------------------------------------------
+
+/** Filter environment events by type. */
+export function filterEnvironmentEvents(
+  events: EnvironmentEventRecord[],
+  type: EnvironmentEventRecord["type"],
+): EnvironmentEventRecord[] {
+  return events.filter((e) => e.type === type);
+}
+
+/** Assert that environment events occurred in the expected order. */
+export function assertEnvironmentEventOrder(
+  events: EnvironmentEventRecord[],
+  expectedOrder: EnvironmentEventRecord["type"][],
+): void {
+  const actual = events.map((e) => e.type);
+  const matched: EnvironmentEventRecord["type"][] = [];
+  let cursor = 0;
+  for (const eventType of actual) {
+    if (cursor < expectedOrder.length && eventType === expectedOrder[cursor]) {
+      matched.push(eventType);
+      cursor++;
+    }
+  }
+  if (matched.length !== expectedOrder.length) {
+    throw new Error(
+      `Environment event order mismatch.\nExpected: ${JSON.stringify(expectedOrder)}\nActual:   ${JSON.stringify(actual)}`,
+    );
+  }
+}
+
+/** Assert that a full lease lifecycle (acquire → release) occurred for an environment. */
+export function assertLeaseLifecycle(
+  events: EnvironmentEventRecord[],
+  environmentId: string,
+): { acquire: EnvironmentEventRecord; release: EnvironmentEventRecord } {
+  const acquire = events.find((e) => e.type === "acquireLease" && e.environmentId === environmentId);
+  const release = events.find((e) => (e.type === "releaseLease" || e.type === "destroyLease") && e.environmentId === environmentId);
+  if (!acquire) throw new Error(`No acquireLease event found for environment ${environmentId}`);
+  if (!release) throw new Error(`No releaseLease/destroyLease event found for environment ${environmentId}`);
+  if (acquire.timestamp > release.timestamp) {
+    throw new Error(`acquireLease occurred after release for environment ${environmentId}`);
+  }
+  return { acquire, release };
+}
+
+/** Assert that workspace realization occurred between lease acquire and release. */
+export function assertWorkspaceRealizationLifecycle(
+  events: EnvironmentEventRecord[],
+  environmentId: string,
+): EnvironmentEventRecord {
+  const lifecycle = assertLeaseLifecycle(events, environmentId);
+  const realize = events.find(
+    (e) => e.type === "realizeWorkspace" && e.environmentId === environmentId,
+  );
+  if (!realize) throw new Error(`No realizeWorkspace event found for environment ${environmentId}`);
+  if (realize.timestamp < lifecycle.acquire.timestamp) {
+    throw new Error(`realizeWorkspace occurred before acquireLease for environment ${environmentId}`);
+  }
+  if (realize.timestamp > lifecycle.release.timestamp) {
+    throw new Error(`realizeWorkspace occurred after release for environment ${environmentId}`);
+  }
+  return realize;
+}
+
+/** Assert that an execute call occurred within the lease lifecycle. */
+export function assertExecutionLifecycle(
+  events: EnvironmentEventRecord[],
+  environmentId: string,
+): EnvironmentEventRecord[] {
+  const lifecycle = assertLeaseLifecycle(events, environmentId);
+  const execEvents = events.filter(
+    (e) => e.type === "execute" && e.environmentId === environmentId,
+  );
+  if (execEvents.length === 0) {
+    throw new Error(`No execute events found for environment ${environmentId}`);
+  }
+  for (const exec of execEvents) {
+    if (exec.timestamp < lifecycle.acquire.timestamp || exec.timestamp > lifecycle.release.timestamp) {
+      throw new Error(`Execute event occurred outside lease lifecycle for environment ${environmentId}`);
+    }
+  }
+  return execEvents;
+}
+
+/** Assert that an event recorded an error. */
+export function assertEnvironmentError(
+  events: EnvironmentEventRecord[],
+  type: EnvironmentEventRecord["type"],
+  environmentId?: string,
+): EnvironmentEventRecord {
+  const match = events.find(
+    (e) => e.type === type && e.error != null && (!environmentId || e.environmentId === environmentId),
+  );
+  if (!match) {
+    throw new Error(`No error event of type '${type}'${environmentId ? ` for environment ${environmentId}` : ""}`);
+  }
+  return match;
+}
+
+// ---------------------------------------------------------------------------
+// Fake environment plugin driver
+// ---------------------------------------------------------------------------
+
+/** Options for creating a fake environment driver for contract testing. */
+export interface FakeEnvironmentDriverOptions {
+  driverKey?: string;
+  /** Simulated acquire delay in ms. */
+  acquireDelayMs?: number;
+  /** If true, probe will return `ok: false`. */
+  probeFailure?: boolean;
+  /** If true, acquireLease will throw. */
+  acquireFailure?: string;
+  /** If true, execute will return a non-zero exit code. */
+  executeFailure?: boolean;
+  /** Custom metadata returned on lease acquire. */
+  leaseMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Create a fake environment driver suitable for contract testing.
+ *
+ * This returns a driver hooks object compatible with `EnvironmentTestHarnessOptions.environmentDriver`.
+ * It simulates the full environment lifecycle with configurable failure injection.
+ */
+export function createFakeEnvironmentDriver(options: FakeEnvironmentDriverOptions = {}): EnvironmentTestHarnessOptions["environmentDriver"] {
+  const driverKey = options.driverKey ?? "fake";
+  const leases = new Map<string, { providerLeaseId: string; metadata: Record<string, unknown> }>();
+  let leaseCounter = 0;
+
+  return {
+    driverKey,
+    async onValidateConfig(params) {
+      if (!params.config || typeof params.config !== "object") {
+        return { ok: false, errors: ["Config must be an object"] };
+      }
+      return { ok: true, normalizedConfig: params.config };
+    },
+    async onProbe(_params) {
+      if (options.probeFailure) {
+        return { ok: false, summary: "Simulated probe failure", diagnostics: [{ severity: "error", message: "Probe failed" }] };
+      }
+      return { ok: true, summary: "Fake environment is healthy" };
+    },
+    async onAcquireLease(params) {
+      if (options.acquireFailure) {
+        throw new Error(options.acquireFailure);
+      }
+      if (options.acquireDelayMs) {
+        await new Promise((resolve) => setTimeout(resolve, options.acquireDelayMs));
+      }
+      const providerLeaseId = `fake-lease-${++leaseCounter}`;
+      const metadata = { ...options.leaseMetadata, acquiredAt: new Date().toISOString(), runId: params.runId };
+      leases.set(providerLeaseId, { providerLeaseId, metadata });
+      return { providerLeaseId, metadata };
+    },
+    async onResumeLease(params) {
+      const existing = leases.get(params.providerLeaseId);
+      if (!existing) {
+        throw new Error(`Lease ${params.providerLeaseId} not found — cannot resume`);
+      }
+      return { providerLeaseId: existing.providerLeaseId, metadata: { ...existing.metadata, resumed: true } };
+    },
+    async onReleaseLease(params) {
+      if (params.providerLeaseId) {
+        leases.delete(params.providerLeaseId);
+      }
+    },
+    async onDestroyLease(params) {
+      if (params.providerLeaseId) {
+        leases.delete(params.providerLeaseId);
+      }
+    },
+    async onRealizeWorkspace(params) {
+      return {
+        cwd: params.workspace.localPath ?? params.workspace.remotePath ?? "/tmp/fake-workspace",
+        metadata: { realized: true },
+      };
+    },
+    async onExecute(params) {
+      if (options.executeFailure) {
+        return { exitCode: 1, timedOut: false, stdout: "", stderr: "Simulated execution failure" };
+      }
+      return {
+        exitCode: 0,
+        timedOut: false,
+        stdout: `Executed: ${params.command} ${(params.args ?? []).join(" ")}`.trim(),
+        stderr: "",
+      };
+    },
+  };
+}
+
 type EventRegistration = {
   name: PluginEventType | `plugin.${string}`;
   filter?: EventFilter;
@@ -1036,3 +1307,89 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
 
   return harness;
 }
+
+/**
+ * Create an environment-aware test harness that wraps the base harness with
+ * environment driver simulation and lifecycle event recording.
+ *
+ * Use this to test environment plugins through the full host contract:
+ * validateConfig → probe → acquireLease → realizeWorkspace → execute → releaseLease.
+ */
+export function createEnvironmentTestHarness(options: EnvironmentTestHarnessOptions): EnvironmentTestHarness {
+  const base = createTestHarness(options);
+  const environmentEvents: EnvironmentEventRecord[] = [];
+  const driver = options.environmentDriver;
+
+  function record(
+    type: EnvironmentEventRecord["type"],
+    params: Record<string, unknown>,
+    result?: unknown,
+    error?: string,
+  ): EnvironmentEventRecord {
+    const event: EnvironmentEventRecord = {
+      type,
+      driverKey: (params as { driverKey?: string }).driverKey ?? driver.driverKey,
+      environmentId: (params as { environmentId?: string }).environmentId ?? "unknown",
+      timestamp: new Date().toISOString(),
+      params,
+      result,
+      error,
+    };
+    environmentEvents.push(event);
+    return event;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async function callHook<R>(
+    type: EnvironmentEventRecord["type"],
+    hook: ((...args: any[]) => Promise<R>) | undefined,
+    params: unknown,
+    hookName: string,
+  ): Promise<R> {
+    if (!hook) {
+      const err = `Environment driver '${driver.driverKey}' does not implement ${hookName}`;
+      record(type, params as Record<string, unknown>, undefined, err);
+      throw new Error(err);
+    }
+    try {
+      const result = await hook(params);
+      record(type, params as Record<string, unknown>, result);
+      return result;
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      record(type, params as Record<string, unknown>, undefined, msg);
+      throw e;
+    }
+  }
+
+  const envHarness: EnvironmentTestHarness = {
+    ...base,
+    environmentEvents,
+    async validateConfig(params) {
+      return callHook("validateConfig", driver.onValidateConfig, params, "onValidateConfig");
+    },
+    async probe(params) {
+      return callHook("probe", driver.onProbe, params, "onProbe");
+    },
+    async acquireLease(params) {
+      return callHook("acquireLease", driver.onAcquireLease, params, "onAcquireLease");
+    },
+    async resumeLease(params) {
+      return callHook("resumeLease", driver.onResumeLease, params, "onResumeLease");
+    },
+    async releaseLease(params) {
+      return callHook("releaseLease", driver.onReleaseLease, params, "onReleaseLease");
+    },
+    async destroyLease(params) {
+      return callHook("destroyLease", driver.onDestroyLease, params, "onDestroyLease");
+    },
+    async realizeWorkspace(params) {
+      return callHook("realizeWorkspace", driver.onRealizeWorkspace, params, "onRealizeWorkspace");
+    },
+    async execute(params) {
+      return callHook("execute", driver.onExecute, params, "onExecute");
+    },
+  };
+
+  return envHarness;
+}

packages/plugins/sdk/src/types.ts

@@ -41,6 +41,7 @@ export type {
   PluginJobDeclaration,
   PluginWebhookDeclaration,
   PluginToolDeclaration,
+  PluginEnvironmentDriverDeclaration,
   PluginUiSlotDeclaration,
   PluginUiDeclaration,
   PluginLauncherActionDeclaration,

packages/plugins/sdk/src/worker-rpc-host.ts

@@ -76,6 +76,14 @@ import type {
   GetDataParams,
   PerformActionParams,
   ExecuteToolParams,
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentDestroyLeaseParams,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentResumeLeaseParams,
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentProbeParams,
   WorkerToHostMethodName,
   WorkerToHostMethods,
 } from "./protocol.js";
@@ -1079,6 +1087,30 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
       case "executeTool":
         return handleExecuteTool(params as ExecuteToolParams);
 
+      case "environmentValidateConfig":
+        return handleEnvironmentValidateConfig(params as PluginEnvironmentValidateConfigParams);
+
+      case "environmentProbe":
+        return handleEnvironmentProbe(params as PluginEnvironmentProbeParams);
+
+      case "environmentAcquireLease":
+        return handleEnvironmentAcquireLease(params as PluginEnvironmentAcquireLeaseParams);
+
+      case "environmentResumeLease":
+        return handleEnvironmentResumeLease(params as PluginEnvironmentResumeLeaseParams);
+
+      case "environmentReleaseLease":
+        return handleEnvironmentReleaseLease(params as PluginEnvironmentReleaseLeaseParams);
+
+      case "environmentDestroyLease":
+        return handleEnvironmentDestroyLease(params as PluginEnvironmentDestroyLeaseParams);
+
+      case "environmentRealizeWorkspace":
+        return handleEnvironmentRealizeWorkspace(params as PluginEnvironmentRealizeWorkspaceParams);
+
+      case "environmentExecute":
+        return handleEnvironmentExecute(params as PluginEnvironmentExecuteParams);
+
       default:
         throw Object.assign(
           new Error(`Unknown method: ${method}`),
@@ -1112,6 +1144,14 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
     if (plugin.definition.onHealth) supportedMethods.push("health");
     if (plugin.definition.onShutdown) supportedMethods.push("shutdown");
     if (plugin.definition.onApiRequest) supportedMethods.push("handleApiRequest");
+    if (plugin.definition.onEnvironmentValidateConfig) supportedMethods.push("environmentValidateConfig");
+    if (plugin.definition.onEnvironmentProbe) supportedMethods.push("environmentProbe");
+    if (plugin.definition.onEnvironmentAcquireLease) supportedMethods.push("environmentAcquireLease");
+    if (plugin.definition.onEnvironmentResumeLease) supportedMethods.push("environmentResumeLease");
+    if (plugin.definition.onEnvironmentReleaseLease) supportedMethods.push("environmentReleaseLease");
+    if (plugin.definition.onEnvironmentDestroyLease) supportedMethods.push("environmentDestroyLease");
+    if (plugin.definition.onEnvironmentRealizeWorkspace) supportedMethods.push("environmentRealizeWorkspace");
+    if (plugin.definition.onEnvironmentExecute) supportedMethods.push("environmentExecute");
 
     return { ok: true, supportedMethods };
   }
@@ -1255,6 +1295,71 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
     return entry.fn(params.parameters, params.runContext);
   }
 
+  function methodNotImplemented(method: string): Error & { code: number } {
+    return Object.assign(
+      new Error(`${method} is not implemented by this plugin`),
+      { code: PLUGIN_RPC_ERROR_CODES.METHOD_NOT_IMPLEMENTED },
+    );
+  }
+
+  async function handleEnvironmentValidateConfig(
+    params: PluginEnvironmentValidateConfigParams,
+  ) {
+    if (!plugin.definition.onEnvironmentValidateConfig) {
+      throw methodNotImplemented("environmentValidateConfig");
+    }
+    return plugin.definition.onEnvironmentValidateConfig(params);
+  }
+
+  async function handleEnvironmentProbe(params: PluginEnvironmentProbeParams) {
+    if (!plugin.definition.onEnvironmentProbe) {
+      throw methodNotImplemented("environmentProbe");
+    }
+    return plugin.definition.onEnvironmentProbe(params);
+  }
+
+  async function handleEnvironmentAcquireLease(params: PluginEnvironmentAcquireLeaseParams) {
+    if (!plugin.definition.onEnvironmentAcquireLease) {
+      throw methodNotImplemented("environmentAcquireLease");
+    }
+    return plugin.definition.onEnvironmentAcquireLease(params);
+  }
+
+  async function handleEnvironmentResumeLease(params: PluginEnvironmentResumeLeaseParams) {
+    if (!plugin.definition.onEnvironmentResumeLease) {
+      throw methodNotImplemented("environmentResumeLease");
+    }
+    return plugin.definition.onEnvironmentResumeLease(params);
+  }
+
+  async function handleEnvironmentReleaseLease(params: PluginEnvironmentReleaseLeaseParams) {
+    if (!plugin.definition.onEnvironmentReleaseLease) {
+      throw methodNotImplemented("environmentReleaseLease");
+    }
+    return plugin.definition.onEnvironmentReleaseLease(params);
+  }
+
+  async function handleEnvironmentDestroyLease(params: PluginEnvironmentDestroyLeaseParams) {
+    if (!plugin.definition.onEnvironmentDestroyLease) {
+      throw methodNotImplemented("environmentDestroyLease");
+    }
+    return plugin.definition.onEnvironmentDestroyLease(params);
+  }
+
+  async function handleEnvironmentRealizeWorkspace(params: PluginEnvironmentRealizeWorkspaceParams) {
+    if (!plugin.definition.onEnvironmentRealizeWorkspace) {
+      throw methodNotImplemented("environmentRealizeWorkspace");
+    }
+    return plugin.definition.onEnvironmentRealizeWorkspace(params);
+  }
+
+  async function handleEnvironmentExecute(params: PluginEnvironmentExecuteParams) {
+    if (!plugin.definition.onEnvironmentExecute) {
+      throw methodNotImplemented("environmentExecute");
+    }
+    return plugin.definition.onEnvironmentExecute(params);
+  }
+
   // -----------------------------------------------------------------------
   // Event filter helper
   // -----------------------------------------------------------------------

packages/shared/src/constants.ts

@@ -162,7 +162,7 @@ export const ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES = [
 export type IssueThreadInteractionContinuationPolicy =
   (typeof ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES)[number];
 
-export const ISSUE_ORIGIN_KINDS = ["manual", "routine_execution"] as const;
+export const ISSUE_ORIGIN_KINDS = ["manual", "routine_execution", "stale_active_run_evaluation"] as const;
 export type BuiltInIssueOriginKind = (typeof ISSUE_ORIGIN_KINDS)[number];
 export type PluginIssueOriginKind = `plugin:${string}`;
 export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;
@@ -218,16 +218,21 @@ export const PROJECT_STATUSES = [
 ] as const;
 export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
 
-export const ENVIRONMENT_DRIVERS = ["local", "ssh"] as const;
+export const ENVIRONMENT_DRIVERS = ["local", "ssh", "sandbox", "plugin"] as const;
 export type EnvironmentDriver = (typeof ENVIRONMENT_DRIVERS)[number];
 
 export const ENVIRONMENT_STATUSES = ["active", "archived"] as const;
 export type EnvironmentStatus = (typeof ENVIRONMENT_STATUSES)[number];
 
-export const ENVIRONMENT_LEASE_STATUSES = ["active", "released", "expired", "failed"] as const;
+export const ENVIRONMENT_LEASE_STATUSES = ["active", "released", "expired", "failed", "retained"] as const;
 export type EnvironmentLeaseStatus = (typeof ENVIRONMENT_LEASE_STATUSES)[number];
 
-export const ENVIRONMENT_LEASE_POLICIES = ["ephemeral"] as const;
+export const ENVIRONMENT_LEASE_POLICIES = [
+  "ephemeral",
+  "reuse_by_environment",
+  "reuse_by_execution_workspace",
+  "retain_on_failure",
+] as const;
 export type EnvironmentLeasePolicy = (typeof ENVIRONMENT_LEASE_POLICIES)[number];
 
 export const ENVIRONMENT_LEASE_CLEANUP_STATUSES = ["pending", "success", "failed"] as const;
@@ -480,13 +485,13 @@ export type JoinRequestStatus = (typeof JOIN_REQUEST_STATUSES)[number];
 
 export const PERMISSION_KEYS = [
   "agents:create",
+  "environments:manage",
   "users:invite",
   "users:manage_permissions",
   "tasks:assign",
   "tasks:assign_scope",
   "tasks:manage_active_checkouts",
   "joins:approve",
-  "environments:manage",
 ] as const;
 export type PermissionKey = (typeof PERMISSION_KEYS)[number];
 
@@ -598,6 +603,7 @@ export const PLUGIN_CAPABILITIES = [
   "api.routes.register",
   "http.outbound",
   "secrets.read-ref",
+  "environment.drivers.register",
   // Agent Tools
   "agent.tools.register",
   // UI

packages/shared/src/environment-support.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { isSandboxProviderSupportedForAdapter } from "./environment-support.js";
+
+describe("isSandboxProviderSupportedForAdapter", () => {
+  it("accepts additional sandbox providers for remote-managed adapters", () => {
+    expect(
+      isSandboxProviderSupportedForAdapter("codex_local", "fake-plugin", ["fake-plugin"]),
+    ).toBe(true);
+  });
+
+  it("rejects providers for adapters without remote-managed environment support", () => {
+    expect(
+      isSandboxProviderSupportedForAdapter("openclaw", "fake-plugin", ["fake-plugin"]),
+    ).toBe(false);
+  });
+});

packages/shared/src/environment-support.ts

@@ -1,15 +1,33 @@
 import type { AgentAdapterType, EnvironmentDriver } from "./constants.js";
+import type { SandboxEnvironmentProvider } from "./types/environment.js";
+import type { JsonSchema } from "./types/plugin.js";
 
 export type EnvironmentSupportStatus = "supported" | "unsupported";
 
 export interface AdapterEnvironmentSupport {
   adapterType: AgentAdapterType;
   drivers: Record<EnvironmentDriver, EnvironmentSupportStatus>;
+  sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentSupportStatus>;
+}
+
+export interface EnvironmentProviderCapability {
+  status: EnvironmentSupportStatus;
+  supportsSavedProbe: boolean;
+  supportsUnsavedProbe: boolean;
+  supportsRunExecution: boolean;
+  supportsReusableLeases: boolean;
+  displayName?: string;
+  description?: string;
+  source?: "builtin" | "plugin";
+  pluginKey?: string;
+  pluginId?: string;
+  configSchema?: JsonSchema;
 }
 
 export interface EnvironmentCapabilities {
   adapters: AdapterEnvironmentSupport[];
   drivers: Record<EnvironmentDriver, EnvironmentSupportStatus>;
+  sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentProviderCapability>;
 }
 
 const REMOTE_MANAGED_ADAPTERS = new Set<AgentAdapterType>([
@@ -27,10 +45,19 @@ export function adapterSupportsRemoteManagedEnvironments(adapterType: string): b
 
 export function supportedEnvironmentDriversForAdapter(adapterType: string): EnvironmentDriver[] {
   return adapterSupportsRemoteManagedEnvironments(adapterType)
-    ? ["local", "ssh"]
+    ? ["local", "ssh", "sandbox"]
     : ["local"];
 }
 
+export function supportedSandboxProvidersForAdapter(
+  adapterType: string,
+  additionalProviders: readonly string[] = [],
+): SandboxEnvironmentProvider[] {
+  return adapterSupportsRemoteManagedEnvironments(adapterType)
+    ? Array.from(new Set(additionalProviders)) as SandboxEnvironmentProvider[]
+    : [];
+}
+
 export function isEnvironmentDriverSupportedForAdapter(
   adapterType: string,
   driver: string,
@@ -38,27 +65,84 @@ export function isEnvironmentDriverSupportedForAdapter(
   return supportedEnvironmentDriversForAdapter(adapterType).includes(driver as EnvironmentDriver);
 }
 
+export function isSandboxProviderSupportedForAdapter(
+  adapterType: string,
+  provider: string | null | undefined,
+  additionalProviders: readonly string[] = [],
+): boolean {
+  if (!provider) return false;
+  return supportedSandboxProvidersForAdapter(adapterType, additionalProviders).includes(
+    provider as SandboxEnvironmentProvider,
+  );
+}
+
 export function getAdapterEnvironmentSupport(
   adapterType: AgentAdapterType,
+  additionalSandboxProviders: readonly string[] = [],
 ): AdapterEnvironmentSupport {
   const supportedDrivers = new Set(supportedEnvironmentDriversForAdapter(adapterType));
+  const supportedProviders = new Set(supportedSandboxProvidersForAdapter(adapterType, additionalSandboxProviders));
+  const sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentSupportStatus> = {
+    fake: "unsupported",
+  };
+  for (const provider of additionalSandboxProviders) {
+    sandboxProviders[provider as SandboxEnvironmentProvider] = supportedProviders.has(provider as SandboxEnvironmentProvider)
+      ? "supported"
+      : "unsupported";
+  }
   return {
     adapterType,
     drivers: {
       local: supportedDrivers.has("local") ? "supported" : "unsupported",
       ssh: supportedDrivers.has("ssh") ? "supported" : "unsupported",
+      sandbox: supportedDrivers.has("sandbox") ? "supported" : "unsupported",
+      plugin: supportedDrivers.has("plugin") ? "supported" : "unsupported",
     },
+    sandboxProviders,
   };
 }
 
 export function getEnvironmentCapabilities(
   adapterTypes: readonly AgentAdapterType[],
+  options: {
+    sandboxProviders?: Record<string, Partial<EnvironmentProviderCapability>>;
+  } = {},
 ): EnvironmentCapabilities {
+  const pluginProviderKeys = Object.keys(options.sandboxProviders ?? {});
+  const sandboxProviders: Record<SandboxEnvironmentProvider, EnvironmentProviderCapability> = {
+    fake: {
+      status: "unsupported",
+      supportsSavedProbe: true,
+      supportsUnsavedProbe: true,
+      supportsRunExecution: false,
+      supportsReusableLeases: true,
+      displayName: "Fake",
+      source: "builtin",
+    },
+  };
+  for (const [provider, capability] of Object.entries(options.sandboxProviders ?? {})) {
+    sandboxProviders[provider as SandboxEnvironmentProvider] = {
+      status: capability.status ?? "supported",
+      supportsSavedProbe: capability.supportsSavedProbe ?? true,
+      supportsUnsavedProbe: capability.supportsUnsavedProbe ?? true,
+      supportsRunExecution: capability.supportsRunExecution ?? true,
+      supportsReusableLeases: capability.supportsReusableLeases ?? true,
+      displayName: capability.displayName,
+      description: capability.description,
+      source: capability.source ?? "plugin",
+      pluginKey: capability.pluginKey,
+      pluginId: capability.pluginId,
+      configSchema: capability.configSchema,
+    };
+  }
   return {
-    adapters: adapterTypes.map((adapterType) => getAdapterEnvironmentSupport(adapterType)),
+    adapters: adapterTypes.map((adapterType) => getAdapterEnvironmentSupport(adapterType, pluginProviderKeys)),
     drivers: {
       local: "supported",
       ssh: "supported",
+      sandbox: "supported",
+      plugin: "unsupported",
     },
+    sandboxProviders,
   };
 }

packages/shared/src/index.ts

@@ -219,7 +219,12 @@ export type {
   Environment,
   EnvironmentLease,
   EnvironmentProbeResult,
+  FakeSandboxEnvironmentConfig,
   LocalEnvironmentConfig,
+  PluginSandboxEnvironmentConfig,
+  PluginEnvironmentConfig,
+  SandboxEnvironmentConfig,
+  SandboxEnvironmentProvider,
   SshEnvironmentConfig,
   FeedbackVote,
   FeedbackDataSharingPreference,
@@ -300,6 +305,10 @@ export type {
   WorkspaceOperationPhase,
   WorkspaceOperationStatus,
   WorkspaceRuntimeDesiredState,
+  WorkspaceRealizationRecord,
+  WorkspaceRealizationRequest,
+  WorkspaceRealizationSyncStrategy,
+  WorkspaceRealizationTransport,
   ExecutionWorkspaceStrategyType,
   ExecutionWorkspaceMode,
   ExecutionWorkspaceProviderType,
@@ -315,6 +324,9 @@ export type {
   IssueWorkProductReviewState,
   Issue,
   IssueAssigneeAdapterOverrides,
+  IssueBlockerAttention,
+  IssueBlockerAttentionReason,
+  IssueBlockerAttentionState,
   IssueReferenceSource,
   IssueRelatedWorkItem,
   IssueRelatedWorkSummary,
@@ -471,6 +483,7 @@ export type {
   PluginJobDeclaration,
   PluginWebhookDeclaration,
   PluginToolDeclaration,
+  PluginEnvironmentDriverDeclaration,
   PluginUiSlotDeclaration,
   PluginLauncherActionDeclaration,
   PluginLauncherRenderDeclaration,
@@ -542,17 +555,6 @@ export {
   isClosedIsolatedExecutionWorkspace,
 } from "./execution-workspace-guards.js";
 
-export {
-  adapterSupportsRemoteManagedEnvironments,
-  getAdapterEnvironmentSupport,
-  getEnvironmentCapabilities,
-  isEnvironmentDriverSupportedForAdapter,
-  supportedEnvironmentDriversForAdapter,
-  type AdapterEnvironmentSupport,
-  type EnvironmentCapabilities,
-  type EnvironmentSupportStatus,
-} from "./environment-support.js";
-
 export {
   instanceGeneralSettingsSchema,
   patchInstanceGeneralSettingsSchema,
@@ -824,6 +826,7 @@ export {
   pluginJobDeclarationSchema,
   pluginWebhookDeclarationSchema,
   pluginToolDeclarationSchema,
+  pluginEnvironmentDriverDeclarationSchema,
   pluginUiSlotDeclarationSchema,
   pluginLauncherActionDeclarationSchema,
   pluginLauncherRenderDeclarationSchema,
@@ -842,6 +845,7 @@ export {
   type PluginJobDeclarationInput,
   type PluginWebhookDeclarationInput,
   type PluginToolDeclarationInput,
+  type PluginEnvironmentDriverDeclarationInput,
   type PluginUiSlotDeclarationInput,
   type PluginLauncherActionDeclarationInput,
   type PluginLauncherRenderDeclarationInput,
@@ -926,3 +930,20 @@ export {
   type SecretsLocalEncryptedConfig,
   type ConfigMeta,
 } from "./config-schema.js";
+
+export {
+  adapterSupportsRemoteManagedEnvironments,
+  getEnvironmentCapabilities,
+  getAdapterEnvironmentSupport,
+  isEnvironmentDriverSupportedForAdapter,
+  isSandboxProviderSupportedForAdapter,
+  supportedEnvironmentDriversForAdapter,
+  supportedSandboxProvidersForAdapter,
+} from "./environment-support.js";
+
+export type {
+  AdapterEnvironmentSupport,
+  EnvironmentCapabilities,
+  EnvironmentProviderCapability,
+  EnvironmentSupportStatus,
+} from "./environment-support.js";

packages/shared/src/types/environment.ts

@@ -22,6 +22,31 @@ export interface SshEnvironmentConfig {
   strictHostKeyChecking: boolean;
 }
 
+export type SandboxEnvironmentProvider = "fake" | (string & {});
+
+export interface FakeSandboxEnvironmentConfig {
+  provider: "fake";
+  image: string;
+  reuseLease: boolean;
+}
+
+export interface PluginSandboxEnvironmentConfig {
+  provider: SandboxEnvironmentProvider;
+  reuseLease: boolean;
+  timeoutMs?: number;
+  [key: string]: unknown;
+}
+
+export type SandboxEnvironmentConfig =
+  | FakeSandboxEnvironmentConfig
+  | PluginSandboxEnvironmentConfig;
+
+export interface PluginEnvironmentConfig {
+  pluginKey: string;
+  driverKey: string;
+  driverConfig: Record<string, unknown>;
+}
+
 export interface EnvironmentProbeResult {
   ok: boolean;
   driver: EnvironmentDriver;

packages/shared/src/types/heartbeat.ts

@@ -37,6 +37,10 @@ export interface HeartbeatRun {
   processPid: number | null;
   processGroupId?: number | null;
   processStartedAt: Date | null;
+  lastOutputAt: Date | null;
+  lastOutputSeq: number;
+  lastOutputStream: "stdout" | "stderr" | null;
+  lastOutputBytes: number | null;
   retryOfRunId: string | null;
   processLossRetryCount: number;
   scheduledRetryAt?: Date | null;
@@ -51,6 +55,29 @@ export interface HeartbeatRun {
   contextSnapshot: Record<string, unknown> | null;
   createdAt: Date;
   updatedAt: Date;
+  outputSilence?: HeartbeatRunOutputSilence;
+}
+
+export type HeartbeatRunOutputSilenceLevel =
+  | "not_applicable"
+  | "ok"
+  | "suspicious"
+  | "critical"
+  | "snoozed";
+
+export interface HeartbeatRunOutputSilence {
+  lastOutputAt: Date | string | null;
+  lastOutputSeq: number;
+  lastOutputStream: "stdout" | "stderr" | null;
+  silenceStartedAt: Date | string | null;
+  silenceAgeMs: number | null;
+  level: HeartbeatRunOutputSilenceLevel;
+  suspicionThresholdMs: number;
+  criticalThresholdMs: number;
+  snoozedUntil: Date | string | null;
+  evaluationIssueId: string | null;
+  evaluationIssueIdentifier: string | null;
+  evaluationIssueAssigneeAgentId: string | null;
 }
 
 export interface AgentWakeupSkipped {

packages/shared/src/types/index.ts

@@ -3,7 +3,12 @@ export type {
   Environment,
   EnvironmentLease,
   EnvironmentProbeResult,
+  FakeSandboxEnvironmentConfig,
   LocalEnvironmentConfig,
+  PluginSandboxEnvironmentConfig,
+  PluginEnvironmentConfig,
+  SandboxEnvironmentConfig,
+  SandboxEnvironmentProvider,
   SshEnvironmentConfig,
 } from "./environment.js";
 export type {
@@ -85,6 +90,10 @@ export type {
   WorkspaceRuntimeService,
   WorkspaceRuntimeServiceStateMap,
   WorkspaceRuntimeDesiredState,
+  WorkspaceRealizationRecord,
+  WorkspaceRealizationRequest,
+  WorkspaceRealizationSyncStrategy,
+  WorkspaceRealizationTransport,
   ExecutionWorkspaceStrategyType,
   ExecutionWorkspaceMode,
   ExecutionWorkspaceProviderType,
@@ -109,6 +118,9 @@ export type {
 export type {
   Issue,
   IssueAssigneeAdapterOverrides,
+  IssueBlockerAttention,
+  IssueBlockerAttentionReason,
+  IssueBlockerAttentionState,
   IssueReferenceSource,
   IssueRelatedWorkItem,
   IssueRelatedWorkSummary,
@@ -281,6 +293,7 @@ export type {
   PluginJobDeclaration,
   PluginWebhookDeclaration,
   PluginToolDeclaration,
+  PluginEnvironmentDriverDeclaration,
   PluginUiSlotDeclaration,
   PluginLauncherActionDeclaration,
   PluginLauncherRenderDeclaration,

packages/shared/src/types/instance.ts

@@ -27,6 +27,7 @@ export interface InstanceExperimentalSettings {
   enableEnvironments: boolean;
   enableIsolatedWorkspaces: boolean;
   autoRestartDevServerWhenIdle: boolean;
+  enableIssueGraphLivenessAutoRecovery: boolean;
 }
 
 export interface InstanceSettings {

packages/shared/src/types/issue.ts

@@ -116,6 +116,24 @@ export interface IssueRelationIssueSummary {
   priority: IssuePriority;
   assigneeAgentId: string | null;
   assigneeUserId: string | null;
+  terminalBlockers?: IssueRelationIssueSummary[];
+}
+
+export type IssueBlockerAttentionState = "none" | "covered" | "needs_attention";
+
+export type IssueBlockerAttentionReason =
+  | "active_child"
+  | "active_dependency"
+  | "attention_required"
+  | null;
+
+export interface IssueBlockerAttention {
+  state: IssueBlockerAttentionState;
+  reason: IssueBlockerAttentionReason;
+  unresolvedBlockerCount: number;
+  coveredBlockerCount: number;
+  attentionBlockerCount: number;
+  sampleBlockerIdentifier: string | null;
 }
 
 export interface IssueRelation {
@@ -242,6 +260,7 @@ export interface Issue {
   labels?: IssueLabel[];
   blockedBy?: IssueRelationIssueSummary[];
   blocks?: IssueRelationIssueSummary[];
+  blockerAttention?: IssueBlockerAttention;
   relatedWork?: IssueRelatedWorkSummary;
   referencedIssueIdentifiers?: string[];
   planDocument?: IssueDocument | null;
@@ -267,6 +286,7 @@ export interface IssueComment {
   authorAgentId: string | null;
   authorUserId: string | null;
   body: string;
+  followUpRequested?: boolean;
   createdAt: Date;
   updatedAt: Date;
 }

packages/shared/src/types/plugin.ts

@@ -89,6 +89,30 @@ export interface PluginToolDeclaration {
   parametersSchema: JsonSchema;
 }
 
+/**
+ * Declares an environment runtime driver contributed by the plugin.
+ *
+ * Requires the `environment.drivers.register` capability.
+ */
+export interface PluginEnvironmentDriverDeclaration {
+  /** Stable driver key, unique within the plugin. Namespaced by plugin ID at runtime. */
+  driverKey: string;
+  /**
+   * Driver classification.
+   *
+   * `environment_driver` is used by core `driver: "plugin"` environments.
+   * `sandbox_provider` is used by core `driver: "sandbox"` environments whose
+   * provider key is implemented by a plugin.
+   */
+  kind?: "environment_driver" | "sandbox_provider";
+  /** Human-readable name shown in environment configuration UI. */
+  displayName: string;
+  /** Optional description for operator-facing docs or UI affordances. */
+  description?: string;
+  /** JSON Schema describing the driver's provider-specific configuration. */
+  configSchema: JsonSchema;
+}
+
 /**
  * Declares a UI extension slot the plugin fills with a React component.
  *
@@ -296,6 +320,8 @@ export interface PaperclipPluginManifestV1 {
   database?: PluginDatabaseDeclaration;
   /** Scoped JSON API routes mounted under `/api/plugins/:pluginId/api/*`. */
   apiRoutes?: PluginApiRouteDeclaration[];
+  /** Environment drivers this plugin contributes. Requires `environment.drivers.register` capability. */
+  environmentDrivers?: PluginEnvironmentDriverDeclaration[];
   /**
    * Legacy top-level launcher declarations.
    * Prefer `ui.launchers` for new manifests.

packages/shared/src/types/workspace-runtime.ts

@@ -231,11 +231,13 @@ export interface WorkspaceRuntimeService {
   updatedAt: Date;
 }
 
-export type WorkspaceRealizationTransport = "local" | "ssh";
+export type WorkspaceRealizationTransport = "local" | "ssh" | "sandbox" | "plugin";
 
 export type WorkspaceRealizationSyncStrategy =
   | "none"
-  | "ssh_git_import_export";
+  | "ssh_git_import_export"
+  | "sandbox_archive_upload_download"
+  | "provider_defined";
 
 export interface WorkspaceRealizationRequest {
   version: 1;
@@ -288,6 +290,7 @@ export interface WorkspaceRealizationRecord {
     host?: string | null;
     port?: number | null;
     username?: string | null;
+    sandboxId?: string | null;
   };
   sync: {
     strategy: WorkspaceRealizationSyncStrategy;

packages/shared/src/validators/approval.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import {
+  addApprovalCommentSchema,
+  requestApprovalRevisionSchema,
+  resolveApprovalSchema,
+} from "./approval.js";
+
+describe("approval validators", () => {
+  it("passes real line breaks through unchanged", () => {
+    expect(addApprovalCommentSchema.parse({ body: "Looks good\n\nApproved." }).body)
+      .toBe("Looks good\n\nApproved.");
+    expect(resolveApprovalSchema.parse({ decisionNote: "Decision\n\nApproved." }).decisionNote)
+      .toBe("Decision\n\nApproved.");
+  });
+
+  it("accepts null and omitted optional decision notes", () => {
+    expect(resolveApprovalSchema.parse({ decisionNote: null }).decisionNote).toBeNull();
+    expect(resolveApprovalSchema.parse({}).decisionNote).toBeUndefined();
+    expect(requestApprovalRevisionSchema.parse({ decisionNote: null }).decisionNote).toBeNull();
+    expect(requestApprovalRevisionSchema.parse({}).decisionNote).toBeUndefined();
+  });
+
+  it("normalizes escaped line breaks in approval comments and decision notes", () => {
+    expect(addApprovalCommentSchema.parse({ body: "Looks good\\n\\nApproved." }).body)
+      .toBe("Looks good\n\nApproved.");
+    expect(resolveApprovalSchema.parse({ decisionNote: "Decision\\n\\nApproved." }).decisionNote)
+      .toBe("Decision\n\nApproved.");
+    expect(requestApprovalRevisionSchema.parse({ decisionNote: "Decision\\r\\nRevise." }).decisionNote)
+      .toBe("Decision\nRevise.");
+  });
+});

packages/shared/src/validators/approval.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { APPROVAL_TYPES } from "../constants.js";
+import { multilineTextSchema } from "./text.js";
 
 export const createApprovalSchema = z.object({
   type: z.enum(APPROVAL_TYPES),
@@ -11,13 +12,13 @@ export const createApprovalSchema = z.object({
 export type CreateApproval = z.infer<typeof createApprovalSchema>;
 
 export const resolveApprovalSchema = z.object({
-  decisionNote: z.string().optional().nullable(),
+  decisionNote: multilineTextSchema.optional().nullable(),
 });
 
 export type ResolveApproval = z.infer<typeof resolveApprovalSchema>;
 
 export const requestApprovalRevisionSchema = z.object({
-  decisionNote: z.string().optional().nullable(),
+  decisionNote: multilineTextSchema.optional().nullable(),
 });
 
 export type RequestApprovalRevision = z.infer<typeof requestApprovalRevisionSchema>;
@@ -29,7 +30,7 @@ export const resubmitApprovalSchema = z.object({
 export type ResubmitApproval = z.infer<typeof resubmitApprovalSchema>;
 
 export const addApprovalCommentSchema = z.object({
-  body: z.string().min(1),
+  body: multilineTextSchema.pipe(z.string().min(1)),
 });
 
 export type AddApprovalComment = z.infer<typeof addApprovalCommentSchema>;

packages/shared/src/validators/index.ts

@@ -344,6 +344,7 @@ export {
   pluginJobDeclarationSchema,
   pluginWebhookDeclarationSchema,
   pluginToolDeclarationSchema,
+  pluginEnvironmentDriverDeclarationSchema,
   pluginUiSlotDeclarationSchema,
   pluginLauncherActionDeclarationSchema,
   pluginLauncherRenderDeclarationSchema,
@@ -362,6 +363,7 @@ export {
   type PluginJobDeclarationInput,
   type PluginWebhookDeclarationInput,
   type PluginToolDeclarationInput,
+  type PluginEnvironmentDriverDeclarationInput,
   type PluginUiSlotDeclarationInput,
   type PluginLauncherActionDeclarationInput,
   type PluginLauncherRenderDeclarationInput,

packages/shared/src/validators/instance.ts

@@ -36,6 +36,7 @@ export const instanceExperimentalSettingsSchema = z.object({
   enableEnvironments: z.boolean().default(false),
   enableIsolatedWorkspaces: z.boolean().default(false),
   autoRestartDevServerWhenIdle: z.boolean().default(false),
+  enableIssueGraphLivenessAutoRecovery: z.boolean().default(false),
 }).strict();
 
 export const patchInstanceExperimentalSettingsSchema = instanceExperimentalSettingsSchema.partial();

packages/shared/src/validators/issue.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import {
+  addIssueCommentSchema,
+  createIssueSchema,
+  respondIssueThreadInteractionSchema,
+  suggestedTaskDraftSchema,
+  updateIssueSchema,
+  upsertIssueDocumentSchema,
+} from "./issue.js";
+
+describe("issue validators", () => {
+  it("passes real line breaks through unchanged", () => {
+    const parsed = createIssueSchema.parse({
+      title: "Follow up PR",
+      description: "Line 1\n\nLine 2",
+    });
+
+    expect(parsed.description).toBe("Line 1\n\nLine 2");
+  });
+
+  it("accepts null and omitted optional multiline issue fields", () => {
+    expect(createIssueSchema.parse({ title: "Follow up PR", description: null }).description)
+      .toBeNull();
+    expect(createIssueSchema.parse({ title: "Follow up PR" }).description)
+      .toBeUndefined();
+    expect(updateIssueSchema.parse({ comment: undefined }).comment)
+      .toBeUndefined();
+  });
+
+  it("normalizes JSON-escaped line breaks in issue descriptions", () => {
+    const parsed = createIssueSchema.parse({
+      title: "Follow up PR",
+      description: "PR: https://example.com/pr/1\\n\\nShip the follow-up.",
+    });
+
+    expect(parsed.description).toBe("PR: https://example.com/pr/1\n\nShip the follow-up.");
+  });
+
+  it("normalizes escaped line breaks in issue update comments", () => {
+    const parsed = updateIssueSchema.parse({
+      comment: "Done\\n\\n- Verified the route",
+    });
+
+    expect(parsed.comment).toBe("Done\n\n- Verified the route");
+  });
+
+  it("normalizes escaped line breaks in issue comment bodies", () => {
+    const parsed = addIssueCommentSchema.parse({
+      body: "Progress update\\r\\n\\r\\nNext action.",
+    });
+
+    expect(parsed.body).toBe("Progress update\n\nNext action.");
+  });
+
+  it("normalizes escaped line breaks in generated task drafts", () => {
+    const parsed = suggestedTaskDraftSchema.parse({
+      clientKey: "task-1",
+      title: "Follow up",
+      description: "Line 1\\n\\nLine 2",
+    });
+
+    expect(parsed.description).toBe("Line 1\n\nLine 2");
+  });
+
+  it("normalizes escaped line breaks in thread summaries and documents", () => {
+    const response = respondIssueThreadInteractionSchema.parse({
+      answers: [],
+      summaryMarkdown: "Summary\\n\\nNext action",
+    });
+    const document = upsertIssueDocumentSchema.parse({
+      format: "markdown",
+      body: "# Plan\\n\\nShip it",
+    });
+
+    expect(response.summaryMarkdown).toBe("Summary\n\nNext action");
+    expect(document.body).toBe("# Plan\n\nShip it");
+  });
+});

packages/shared/src/validators/issue.ts

@@ -10,6 +10,7 @@ import {
   ISSUE_THREAD_INTERACTION_KINDS,
   ISSUE_THREAD_INTERACTION_STATUSES,
 } from "../constants.js";
+import { multilineTextSchema } from "./text.js";
 
 export const ISSUE_EXECUTION_WORKSPACE_PREFERENCES = [
   "inherit",
@@ -130,7 +131,7 @@ export const createIssueSchema = z.object({
   blockedByIssueIds: z.array(z.string().uuid()).optional(),
   inheritExecutionWorkspaceFromIssueId: z.string().uuid().optional().nullable(),
   title: z.string().min(1),
-  description: z.string().optional().nullable(),
+  description: multilineTextSchema.optional().nullable(),
   status: z.enum(ISSUE_STATUSES).optional().default("backlog"),
   priority: z.enum(ISSUE_PRIORITIES).optional().default("medium"),
   assigneeAgentId: z.string().uuid().optional().nullable(),
@@ -168,9 +169,10 @@ export type CreateIssueLabel = z.infer<typeof createIssueLabelSchema>;
 
 export const updateIssueSchema = createIssueSchema.partial().extend({
   assigneeAgentId: z.string().trim().min(1).optional().nullable(),
-  comment: z.string().min(1).optional(),
+  comment: multilineTextSchema.pipe(z.string().min(1)).optional(),
   reviewRequest: issueReviewRequestSchema.optional().nullable(),
   reopen: z.boolean().optional(),
+  resume: z.boolean().optional(),
   interrupt: z.boolean().optional(),
   hiddenAt: z.string().datetime().nullable().optional(),
 });
@@ -186,8 +188,9 @@ export const checkoutIssueSchema = z.object({
 export type CheckoutIssue = z.infer<typeof checkoutIssueSchema>;
 
 export const addIssueCommentSchema = z.object({
-  body: z.string().min(1),
+  body: multilineTextSchema.pipe(z.string().min(1)),
   reopen: z.boolean().optional(),
+  resume: z.boolean().optional(),
   interrupt: z.boolean().optional(),
 });
 
@@ -211,7 +214,7 @@ export const suggestedTaskDraftSchema = z.object({
   parentClientKey: z.string().trim().min(1).max(120).nullable().optional(),
   parentId: z.string().uuid().nullable().optional(),
   title: z.string().trim().min(1).max(240),
-  description: z.string().trim().max(20000).nullable().optional(),
+  description: multilineTextSchema.pipe(z.string().trim().max(20000)).nullable().optional(),
   priority: z.enum(ISSUE_PRIORITIES).nullable().optional(),
   assigneeAgentId: z.string().uuid().nullable().optional(),
   assigneeUserId: z.string().trim().min(1).nullable().optional(),
@@ -437,7 +440,7 @@ export type RejectIssueThreadInteraction = z.infer<typeof rejectIssueThreadInter
 
 export const respondIssueThreadInteractionSchema = z.object({
   answers: z.array(askUserQuestionsAnswerSchema).max(20),
-  summaryMarkdown: z.string().max(20000).nullable().optional(),
+  summaryMarkdown: multilineTextSchema.pipe(z.string().max(20000)).nullable().optional(),
 });
 export type RespondIssueThreadInteraction = z.infer<typeof respondIssueThreadInteractionSchema>;
 
@@ -460,7 +463,7 @@ export const issueDocumentFormatSchema = z.enum(ISSUE_DOCUMENT_FORMATS);
 export const upsertIssueDocumentSchema = z.object({
   title: z.string().trim().max(200).nullable().optional(),
   format: issueDocumentFormatSchema,
-  body: z.string().max(524288),
+  body: multilineTextSchema.pipe(z.string().max(524288)),
   changeSummary: z.string().trim().max(500).nullable().optional(),
   baseRevisionId: z.string().uuid().nullable().optional(),
 });

packages/shared/src/validators/plugin.ts

@@ -107,6 +107,21 @@ export const pluginToolDeclarationSchema = z.object({
   parametersSchema: jsonSchemaSchema,
 });
 
+export const pluginEnvironmentDriverDeclarationSchema = z.object({
+  driverKey: z.string().min(1).regex(
+    /^[a-z0-9][a-z0-9._-]*$/,
+    "Environment driver key must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, hyphens, or underscores",
+  ),
+  kind: z.enum(["environment_driver", "sandbox_provider"]).optional(),
+  displayName: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  configSchema: jsonSchemaSchema,
+});
+
+export type PluginEnvironmentDriverDeclarationInput = z.infer<
+  typeof pluginEnvironmentDriverDeclarationSchema
+>;
+
 export type PluginToolDeclarationInput = z.infer<typeof pluginToolDeclarationSchema>;
 
 /**
@@ -410,11 +425,13 @@ export type PluginApiRouteDeclarationInput = z.infer<typeof pluginApiRouteDeclar
  * Cross-field rules enforced via `superRefine`:
  * - `entrypoints.ui` required when `ui.slots` declared
  * - `agent.tools.register` capability required when `tools` declared
+ * - `environment.drivers.register` capability required when `environmentDrivers` declared
  * - `jobs.schedule` capability required when `jobs` declared
  * - `webhooks.receive` capability required when `webhooks` declared
  * - duplicate `jobs[].jobKey` values are rejected
  * - duplicate `webhooks[].endpointKey` values are rejected
  * - duplicate `tools[].name` values are rejected
+ * - duplicate `environmentDrivers[].driverKey` values are rejected
  * - duplicate `ui.slots[].id` values are rejected
  *
  * @see PLUGIN_SPEC.md §10.1 — Manifest shape
@@ -453,6 +470,7 @@ export const pluginManifestV1Schema = z.object({
   tools: z.array(pluginToolDeclarationSchema).optional(),
   database: pluginDatabaseDeclarationSchema.optional(),
   apiRoutes: z.array(pluginApiRouteDeclarationSchema).optional(),
+  environmentDrivers: z.array(pluginEnvironmentDriverDeclarationSchema).optional(),
   launchers: z.array(pluginLauncherDeclarationSchema).optional(),
   ui: z.object({
     slots: z.array(pluginUiSlotDeclarationSchema).min(1).optional(),
@@ -500,6 +518,17 @@ export const pluginManifestV1Schema = z.object({
     }
   }
 
+  // environment drivers require environment.drivers.register
+  if (manifest.environmentDrivers && manifest.environmentDrivers.length > 0) {
+    if (!manifest.capabilities.includes("environment.drivers.register")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Capability 'environment.drivers.register' is required when environmentDrivers are declared",
+        path: ["capabilities"],
+      });
+    }
+  }
+
   // jobs require jobs.schedule (PLUGIN_SPEC.md §17)
   if (manifest.jobs && manifest.jobs.length > 0) {
     if (!manifest.capabilities.includes("jobs.schedule")) {
@@ -622,6 +651,19 @@ export const pluginManifestV1Schema = z.object({
     }
   }
 
+  // environment driver keys must be unique within the plugin
+  if (manifest.environmentDrivers) {
+    const driverKeys = manifest.environmentDrivers.map((d) => d.driverKey);
+    const duplicates = driverKeys.filter((key, i) => driverKeys.indexOf(key) !== i);
+    if (duplicates.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate environment driver keys: ${[...new Set(duplicates)].join(", ")}`,
+        path: ["environmentDrivers"],
+      });
+    }
+  }
+
   // UI slot ids must be unique within the plugin (namespaced at runtime)
   if (manifest.ui) {
     if (manifest.ui.slots) {

packages/shared/src/validators/text.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export function normalizeEscapedLineBreaks(value: string): string {
+  return value
+    .replace(/\\r\\n/g, "\n")
+    .replace(/\\n/g, "\n")
+    .replace(/\\r/g, "\n");
+}
+
+export const multilineTextSchema = z.string().transform(normalizeEscapedLineBreaks);

pnpm-lock.yaml

@@ -428,6 +428,22 @@ importers:
         specifier: ^5.7.3
         version: 5.9.3
 
+  packages/plugins/paperclip-plugin-fake-sandbox:
+    dependencies:
+      '@paperclipai/plugin-sdk':
+        specifier: workspace:*
+        version: link:../sdk
+    devDependencies:
+      '@types/node':
+        specifier: ^24.6.0
+        version: 24.12.0
+      typescript:
+        specifier: ^5.7.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.2.4
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@24.12.0)(jiti@2.6.1)(jsdom@28.1.0(@noble/hashes@2.0.1))(lightningcss@1.30.2)(tsx@4.21.0)
+
   packages/plugins/sdk:
     dependencies:
       '@paperclipai/shared':

scripts/kill-agent-browsers.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# Kill all "Google Chrome for Testing" processes (agent headless browsers).
+# Kill all agent headless browser processes.
 #
 # Usage:
 #   scripts/kill-agent-browsers.sh        # kill all
@@ -22,14 +22,14 @@ while IFS= read -r line; do
   pid=$(echo "$line" | awk '{print $2}')
   pids+=("$pid")
   lines+=("$line")
-done < <(ps aux | grep 'Google Chrome for Testing' | grep -v grep || true)
+done < <(ps aux | grep -E 'Google Chrome for Testing|chrome-headless-shell' | grep -v grep || true)
 
 if [[ ${#pids[@]} -eq 0 ]]; then
-  echo "No Google Chrome for Testing processes found."
+  echo "No agent headless browser processes found."
   exit 0
 fi
 
-echo "Found ${#pids[@]} Google Chrome for Testing process(es):"
+echo "Found ${#pids[@]} agent headless browser process(es):"
 echo ""
 
 for i in "${!pids[@]}"; do

scripts/run-vitest-stable.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const repoRoot = process.cwd();
+const serverRoot = path.join(repoRoot, "server");
+const serverTestsDir = path.join(repoRoot, "server", "src", "__tests__");
+const nonServerProjects = [
+  "@paperclipai/shared",
+  "@paperclipai/db",
+  "@paperclipai/adapter-utils",
+  "@paperclipai/adapter-codex-local",
+  "@paperclipai/adapter-opencode-local",
+  "@paperclipai/ui",
+  "paperclipai",
+];
+const routeTestPattern = /[^/]*(?:route|routes|authz)[^/]*\.test\.ts$/;
+const additionalSerializedServerTests = new Set([
+  "server/src/__tests__/approval-routes-idempotency.test.ts",
+  "server/src/__tests__/assets.test.ts",
+  "server/src/__tests__/authz-company-access.test.ts",
+  "server/src/__tests__/companies-route-path-guard.test.ts",
+  "server/src/__tests__/company-portability.test.ts",
+  "server/src/__tests__/costs-service.test.ts",
+  "server/src/__tests__/express5-auth-wildcard.test.ts",
+  "server/src/__tests__/health-dev-server-token.test.ts",
+  "server/src/__tests__/health.test.ts",
+  "server/src/__tests__/heartbeat-dependency-scheduling.test.ts",
+  "server/src/__tests__/heartbeat-issue-liveness-escalation.test.ts",
+  "server/src/__tests__/heartbeat-process-recovery.test.ts",
+  "server/src/__tests__/invite-accept-existing-member.test.ts",
+  "server/src/__tests__/invite-accept-gateway-defaults.test.ts",
+  "server/src/__tests__/invite-accept-replay.test.ts",
+  "server/src/__tests__/invite-expiry.test.ts",
+  "server/src/__tests__/invite-join-manager.test.ts",
+  "server/src/__tests__/invite-onboarding-text.test.ts",
+  "server/src/__tests__/issues-checkout-wakeup.test.ts",
+  "server/src/__tests__/issues-service.test.ts",
+  "server/src/__tests__/opencode-local-adapter-environment.test.ts",
+  "server/src/__tests__/project-routes-env.test.ts",
+  "server/src/__tests__/redaction.test.ts",
+  "server/src/__tests__/routines-e2e.test.ts",
+]);
+let invocationIndex = 0;
+
+function walk(dir) {
+  const entries = readdirSync(dir);
+  const files = [];
+  for (const entry of entries) {
+    const absolute = path.join(dir, entry);
+    const stats = statSync(absolute);
+    if (stats.isDirectory()) {
+      files.push(...walk(absolute));
+    } else if (stats.isFile()) {
+      files.push(absolute);
+    }
+  }
+  return files;
+}
+
+function toRepoPath(file) {
+  return path.relative(repoRoot, file).split(path.sep).join("/");
+}
+
+function toServerPath(file) {
+  return path.relative(serverRoot, file).split(path.sep).join("/");
+}
+
+function isRouteOrAuthzTest(file) {
+  if (routeTestPattern.test(file)) {
+    return true;
+  }
+
+  return additionalSerializedServerTests.has(file);
+}
+
+function runVitest(args, label) {
+  console.log(`\n[test:run] ${label}`);
+  invocationIndex += 1;
+  const testRoot = mkdtempSync(path.join(os.tmpdir(), `paperclip-vitest-${process.pid}-${invocationIndex}-`));
+  const env = {
+    ...process.env,
+    PAPERCLIP_HOME: path.join(testRoot, "home"),
+    PAPERCLIP_INSTANCE_ID: `vitest-${process.pid}-${invocationIndex}`,
+    TMPDIR: path.join(testRoot, "tmp"),
+  };
+  mkdirSync(env.PAPERCLIP_HOME, { recursive: true });
+  mkdirSync(env.TMPDIR, { recursive: true });
+  const result = spawnSync("pnpm", ["exec", "vitest", "run", ...args], {
+    cwd: repoRoot,
+    env,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    console.error(`[test:run] Failed to start Vitest: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+const routeTests = walk(serverTestsDir)
+  .filter((file) => isRouteOrAuthzTest(toRepoPath(file)))
+  .map((file) => ({
+    repoPath: toRepoPath(file),
+    serverPath: toServerPath(file),
+  }))
+  .sort((a, b) => a.repoPath.localeCompare(b.repoPath));
+
+const excludeRouteArgs = routeTests.flatMap((file) => ["--exclude", file.serverPath]);
+for (const project of nonServerProjects) {
+  runVitest(["--project", project], `non-server project ${project}`);
+}
+
+runVitest(
+  ["--project", "@paperclipai/server", ...excludeRouteArgs],
+  `server suites excluding ${routeTests.length} serialized suites`,
+);
+
+for (const routeTest of routeTests) {
+  runVitest(
+    [
+      "--project",
+      "@paperclipai/server",
+      routeTest.repoPath,
+      "--pool=forks",
+      "--poolOptions.forks.isolate=true",
+    ],
+    routeTest.repoPath,
+  );
+}

server/src/__tests__/README.md

@@ -0,0 +1,10 @@
+# Server Tests
+
+Server tests that need a real PostgreSQL process must use
+`./helpers/embedded-postgres.ts` instead of constructing `embedded-postgres`
+directly.
+
+The shared helper creates a throwaway data directory and a reserved-safe
+loopback port for each test database. This protects the live Paperclip
+control-plane Postgres from server vitest runs; see PAP-2033 for the incident
+that introduced this guard.

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

@@ -1,7 +1,6 @@
-import type { Server } from "node:http";
 import express from "express";
 import request from "supertest";
-import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mockActivityService = vi.hoisted(() => ({
   list: vi.fn(),
@@ -33,8 +32,6 @@ vi.mock("../services/index.js", () => ({
   heartbeatService: () => mockHeartbeatService,
 }));
 
-let server: Server | null = null;
-
 async function createApp(
   actor: Record<string, unknown> = {
     type: "board",
@@ -44,44 +41,64 @@ async function createApp(
     isInstanceAdmin: false,
   },
 ) {
+  vi.resetModules();
   const [{ errorHandler }, { activityRoutes }] = await Promise.all([
-    import("../middleware/index.js"),
-    import("../routes/activity.js"),
+    import("../middleware/index.js") as Promise<typeof import("../middleware/index.js")>,
+    import("../routes/activity.js") as Promise<typeof import("../routes/activity.js")>,
   ]);
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
-    (req as any).actor = actor;
+    (req as any).actor = {
+      ...actor,
+      companyIds: Array.isArray(actor.companyIds) ? [...actor.companyIds] : actor.companyIds,
+    };
     next();
   });
   app.use("/api", activityRoutes({} as any));
   app.use(errorHandler);
-  server = app.listen(0);
-  return server;
+  return app;
 }
 
-describe("activity routes", () => {
-  afterAll(async () => {
-    if (!server) return;
-    await new Promise<void>((resolve, reject) => {
-      server?.close((err) => {
-        if (err) reject(err);
-        else resolve();
-      });
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
     });
-    server = null;
-  });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
 
+describe.sequential("activity routes", () => {
   beforeEach(() => {
-    vi.resetModules();
-    vi.clearAllMocks();
+    for (const mock of Object.values(mockActivityService)) mock.mockReset();
+    for (const mock of Object.values(mockHeartbeatService)) mock.mockReset();
+    for (const mock of Object.values(mockIssueService)) mock.mockReset();
   });
 
   it("limits company activity lists by default", async () => {
     mockActivityService.list.mockResolvedValue([]);
 
     const app = await createApp();
-    const res = await request(app).get("/api/companies/company-1/activity");
+    const res = await requestApp(app, (baseUrl) => request(baseUrl).get("/api/companies/company-1/activity"));
 
     expect(res.status).toBe(200);
     expect(mockActivityService.list).toHaveBeenCalledWith({
@@ -97,7 +114,9 @@ describe("activity routes", () => {
     mockActivityService.list.mockResolvedValue([]);
 
     const app = await createApp();
-    const res = await request(app).get("/api/companies/company-1/activity?limit=5000&entityType=issue");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl).get("/api/companies/company-1/activity?limit=5000&entityType=issue"),
+    );
 
     expect(res.status).toBe(200);
     expect(mockActivityService.list).toHaveBeenCalledWith({
@@ -122,7 +141,7 @@ describe("activity routes", () => {
     ]);
 
     const app = await createApp();
-    const res = await request(app).get("/api/issues/PAP-475/runs");
+    const res = await requestApp(app, (baseUrl) => request(baseUrl).get("/api/issues/PAP-475/runs"));
 
     expect(res.status).toBe(200);
     expect(mockIssueService.getByIdentifier).toHaveBeenCalledWith("PAP-475");
@@ -133,14 +152,14 @@ describe("activity routes", () => {
 
   it("requires company access before creating activity events", async () => {
     const app = await createApp();
-    const res = await request(app)
+    const res = await requestApp(app, (baseUrl) => request(baseUrl)
       .post("/api/companies/company-2/activity")
       .send({
         actorId: "user-1",
         action: "test.event",
         entityType: "issue",
         entityId: "issue-1",
-      });
+      }));
 
     expect(res.status).toBe(403);
     expect(mockActivityService.create).not.toHaveBeenCalled();
@@ -153,7 +172,7 @@ describe("activity routes", () => {
     });
 
     const app = await createApp();
-    const res = await request(app).get("/api/heartbeat-runs/run-2/issues");
+    const res = await requestApp(app, (baseUrl) => request(baseUrl).get("/api/heartbeat-runs/run-2/issues"));
 
     expect(res.status).toBe(403);
     expect(mockActivityService.issuesForRun).not.toHaveBeenCalled();
@@ -161,7 +180,7 @@ describe("activity routes", () => {
 
   it("rejects anonymous heartbeat run issue lookups before run existence checks", async () => {
     const app = await createApp({ type: "none", source: "none" });
-    const res = await request(app).get("/api/heartbeat-runs/missing-run/issues");
+    const res = await requestApp(app, (baseUrl) => request(baseUrl).get("/api/heartbeat-runs/missing-run/issues"));
 
     expect(res.status).toBe(401);
     expect(mockHeartbeatService.getRun).not.toHaveBeenCalled();

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

@@ -424,7 +424,7 @@ describeEmbeddedPostgres("activity service", () => {
     expect(backfilledRun).toMatchObject({
       runId,
       livenessState: "plan_only",
-      livenessReason: "Run described future work without concrete action evidence",
+      livenessReason: "Run described runnable future work without concrete action evidence",
       lastUsefulActionAt: null,
     });
   });
@@ -530,7 +530,7 @@ describeEmbeddedPostgres("activity service", () => {
     expect(backfilledRun).toMatchObject({
       runId,
       livenessState: "plan_only",
-      livenessReason: "Run described future work without concrete action evidence",
+      livenessReason: "Run described runnable future work without concrete action evidence",
       lastUsefulActionAt: null,
     });
   });

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

@@ -1,6 +1,6 @@
 import express from "express";
 import request from "supertest";
-import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ServerAdapterModule } from "../adapters/index.js";
 
 const mocks = vi.hoisted(() => {
@@ -121,7 +121,13 @@ function createApp(actor: Express.Request["actor"]) {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
-    req.actor = actor;
+    req.actor = {
+      ...actor,
+      companyIds: Array.isArray(actor.companyIds) ? [...actor.companyIds] : actor.companyIds,
+      memberships: Array.isArray(actor.memberships)
+        ? actor.memberships.map((membership) => ({ ...membership }))
+        : actor.memberships,
+    } as Express.Request["actor"];
     next();
   });
   app.use("/api", adapterRoutes());
@@ -129,6 +135,33 @@ function createApp(actor: Express.Request["actor"]) {
   return app;
 }
 
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
 function boardMember(membershipRole: "admin" | "operator" | "viewer"): Express.Request["actor"] {
   return {
     type: "board",
@@ -162,23 +195,29 @@ const instanceAdmin: Express.Request["actor"] = {
 function sendMutatingRequest(app: express.Express, name: string) {
   switch (name) {
     case "install":
-      return request(app)
-        .post("/api/adapters/install")
-        .send({ packageName: EXTERNAL_PACKAGE_NAME });
+      return requestApp(app, (baseUrl) =>
+        request(baseUrl)
+          .post("/api/adapters/install")
+          .send({ packageName: EXTERNAL_PACKAGE_NAME }),
+      );
     case "disable":
-      return request(app)
-        .patch(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}`)
-        .send({ disabled: true });
+      return requestApp(app, (baseUrl) =>
+        request(baseUrl)
+          .patch(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}`)
+          .send({ disabled: true }),
+      );
     case "override":
-      return request(app)
-        .patch("/api/adapters/claude_local/override")
-        .send({ paused: true });
+      return requestApp(app, (baseUrl) =>
+        request(baseUrl)
+          .patch("/api/adapters/claude_local/override")
+          .send({ paused: true }),
+      );
     case "delete":
-      return request(app).delete(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}`);
+      return requestApp(app, (baseUrl) => request(baseUrl).delete(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}`));
     case "reload":
-      return request(app).post(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}/reload`);
+      return requestApp(app, (baseUrl) => request(baseUrl).post(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}/reload`));
     case "reinstall":
-      return request(app).post(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}/reinstall`);
+      return requestApp(app, (baseUrl) => request(baseUrl).post(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}/reinstall`));
     default:
       throw new Error(`Unknown mutating adapter route: ${name}`);
   }
@@ -190,7 +229,13 @@ function seedInstalledExternalAdapter() {
   registerServerAdapter(createAdapter());
 }
 
-describe("adapter management route authorization", () => {
+function resetInstalledExternalAdapterState() {
+  mocks.externalRecords.clear();
+  unregisterServerAdapter(EXTERNAL_ADAPTER_TYPE);
+  setOverridePaused("claude_local", false);
+}
+
+describe.sequential("adapter management route authorization", () => {
   beforeEach(async () => {
     vi.resetModules();
     vi.doUnmock("node:child_process");
@@ -232,50 +277,61 @@ describe("adapter management route authorization", () => {
     setOverridePaused("claude_local", false);
   });
 
-  it.each([
-    "install",
-    "disable",
-    "override",
-    "delete",
-    "reload",
-    "reinstall",
-  ])("rejects %s for a non-instance-admin board user with company membership", async (routeName) => {
-    seedInstalledExternalAdapter();
-    const app = createApp(boardMember("admin"));
+  it("rejects mutating adapter routes for a non-instance-admin board user with company membership", async () => {
+    for (const routeName of [
+      "install",
+      "disable",
+      "override",
+      "delete",
+      "reload",
+      "reinstall",
+    ]) {
+      resetInstalledExternalAdapterState();
+      seedInstalledExternalAdapter();
+      const app = createApp(boardMember("admin"));
 
-    const res = await sendMutatingRequest(app, routeName);
+      const res = await sendMutatingRequest(app, routeName);
 
-    expect(res.status, JSON.stringify(res.body)).toBe(403);
+      expect(res.status, `${routeName}: ${JSON.stringify(res.body)}`).toBe(403);
+    }
   });
 
-  it.each([
-    ["install", 201],
-    ["disable", 200],
-    ["override", 200],
-    ["delete", 200],
-    ["reload", 200],
-    ["reinstall", 200],
-  ] as const)("allows instance admins to reach %s", async (routeName, expectedStatus) => {
-    if (routeName !== "install") {
-      seedInstalledExternalAdapter();
+  it("allows instance admins to reach mutating adapter routes", async () => {
+    for (const [routeName, expectedStatus] of [
+      ["install", 201],
+      ["disable", 200],
+      ["override", 200],
+      ["delete", 200],
+      ["reload", 200],
+      ["reinstall", 200],
+    ] as const) {
+      resetInstalledExternalAdapterState();
+      if (routeName !== "install") {
+        seedInstalledExternalAdapter();
+      }
+      const app = createApp(instanceAdmin);
+
+      const res = await sendMutatingRequest(app, routeName);
+
+      expect(res.status, `${routeName}: ${JSON.stringify(res.body)}`).toBe(expectedStatus);
     }
-    const app = createApp(instanceAdmin);
-
-    const res = await sendMutatingRequest(app, routeName);
-
-    expect(res.status, JSON.stringify(res.body)).toBe(expectedStatus);
   });
 
   it.each(["viewer", "operator"] as const)(
     "does not let a company %s trigger adapter npm install or reload",
     async (membershipRole) => {
       seedInstalledExternalAdapter();
-      const app = createApp(boardMember(membershipRole));
+      const installApp = createApp(boardMember(membershipRole));
+      const reloadApp = createApp(boardMember(membershipRole));
 
-      const install = await request(app)
-        .post("/api/adapters/install")
-        .send({ packageName: EXTERNAL_PACKAGE_NAME });
-      const reload = await request(app).post(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}/reload`);
+      const install = await requestApp(installApp, (baseUrl) =>
+        request(baseUrl)
+          .post("/api/adapters/install")
+          .send({ packageName: EXTERNAL_PACKAGE_NAME }),
+      );
+      const reload = await requestApp(reloadApp, (baseUrl) =>
+        request(baseUrl).post(`/api/adapters/${EXTERNAL_ADAPTER_TYPE}/reload`),
+      );
 
       expect(install.status, JSON.stringify(install.body)).toBe(403);
       expect(reload.status, JSON.stringify(reload.body)).toBe(403);

server/src/__tests__/agent-adapter-validation-routes.test.ts

@@ -148,6 +148,33 @@ async function createApp() {
   return app;
 }
 
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
 async function unregisterTestAdapter(type: string) {
   const { unregisterServerAdapter } = await import("../adapters/index.js");
   unregisterServerAdapter(type);
@@ -161,7 +188,7 @@ describe("agent routes adapter validation", () => {
     vi.doUnmock("../middleware/index.js");
     vi.doUnmock("../routes/agents.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     mockCompanySkillService.listRuntimeSkillEntries.mockResolvedValue([]);
     mockCompanySkillService.resolveRequestedSkillKeys.mockResolvedValue([]);
     mockAccessService.canUser.mockResolvedValue(true);
@@ -207,12 +234,14 @@ describe("agent routes adapter validation", () => {
     registerServerAdapter(externalAdapter);
 
     const app = await createApp();
-    const res = await request(app)
-      .post("/api/companies/company-1/agents")
-      .send({
-        name: "External Agent",
-        adapterType: "external_test",
-      });
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/agents")
+        .send({
+          name: "External Agent",
+          adapterType: "external_test",
+        }),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(201);
     expect(res.body.adapterType).toBe("external_test");
@@ -220,12 +249,14 @@ describe("agent routes adapter validation", () => {
 
   it("rejects unknown adapter types even when schema accepts arbitrary strings", async () => {
     const app = await createApp();
-    const res = await request(app)
-      .post("/api/companies/company-1/agents")
-      .send({
-        name: "Missing Adapter",
-        adapterType: missingAdapterType,
-      });
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/agents")
+        .send({
+          name: "Missing Adapter",
+          adapterType: missingAdapterType,
+        }),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(422);
     expect(String(res.body.error ?? res.body.message ?? "")).toContain(`Unknown adapter type: ${missingAdapterType}`);

server/src/__tests__/agent-cross-tenant-authz-routes.test.ts

@@ -1,8 +1,9 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { errorHandler } from "../middleware/index.js";
-import { agentRoutes } from "../routes/agents.js";
+
+vi.unmock("http");
+vi.unmock("node:http");
 
 const agentId = "11111111-1111-4111-8111-111111111111";
 const companyId = "22222222-2222-4222-8222-222222222222";
@@ -42,6 +43,9 @@ const baseKey = {
   revokedAt: null,
 };
 
+let currentKeyAgentId = agentId;
+let currentAccessCanUser = false;
+
 const mockAgentService = vi.hoisted(() => ({
   getById: vi.fn(),
   pause: vi.fn(),
@@ -111,6 +115,66 @@ vi.mock("../telemetry.js", () => ({
   getTelemetryClient: mockGetTelemetryClient,
 }));
 
+vi.mock("../routes/authz.js", async () => {
+  const { forbidden, unauthorized } = await vi.importActual<typeof import("../errors.js")>("../errors.js");
+  function assertAuthenticated(req: Express.Request) {
+    if (req.actor.type === "none") {
+      throw unauthorized();
+    }
+  }
+
+  function assertBoard(req: Express.Request) {
+    if (req.actor.type !== "board") {
+      throw forbidden("Board access required");
+    }
+  }
+
+  function assertCompanyAccess(req: Express.Request, expectedCompanyId: string) {
+    assertAuthenticated(req);
+    if (req.actor.type === "agent" && req.actor.companyId !== expectedCompanyId) {
+      throw forbidden("Agent key cannot access another company");
+    }
+    if (req.actor.type === "board" && req.actor.source !== "local_implicit") {
+      const allowedCompanies = req.actor.companyIds ?? [];
+      if (!allowedCompanies.includes(expectedCompanyId)) {
+        throw forbidden("User does not have access to this company");
+      }
+    }
+  }
+
+  function assertInstanceAdmin(req: Express.Request) {
+    assertBoard(req);
+    if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return;
+    throw forbidden("Instance admin access required");
+  }
+
+  function getActorInfo(req: Express.Request) {
+    assertAuthenticated(req);
+    if (req.actor.type === "agent") {
+      return {
+        actorType: "agent" as const,
+        actorId: req.actor.agentId ?? "unknown-agent",
+        agentId: req.actor.agentId ?? null,
+        runId: req.actor.runId ?? null,
+      };
+    }
+    return {
+      actorType: "user" as const,
+      actorId: req.actor.userId ?? "board",
+      agentId: null,
+      runId: req.actor.runId ?? null,
+    };
+  }
+
+  return {
+    assertAuthenticated,
+    assertBoard,
+    assertCompanyAccess,
+    assertInstanceAdmin,
+    getActorInfo,
+  };
+});
+
 vi.mock("../services/index.js", () => ({
   agentService: () => mockAgentService,
   agentInstructionsService: () => mockAgentInstructionsService,
@@ -133,11 +197,30 @@ vi.mock("../services/instance-settings.js", () => ({
   }),
 }));
 
-function createApp(actor: Record<string, unknown>) {
+let routeModules:
+  | Promise<[
+    typeof import("../middleware/index.js"),
+    typeof import("../routes/agents.js"),
+  ]>
+  | null = null;
+
+async function loadRouteModules() {
+  routeModules ??= Promise.all([
+    import("../middleware/index.js"),
+    import("../routes/agents.js"),
+  ]);
+  return routeModules;
+}
+
+async function createApp(actor: Record<string, unknown>) {
+  const [{ errorHandler }, { agentRoutes }] = await loadRouteModules();
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
-    (req as any).actor = actor;
+    (req as any).actor = {
+      ...actor,
+      companyIds: Array.isArray(actor.companyIds) ? [...actor.companyIds] : actor.companyIds,
+    };
     next();
   });
   app.use("/api", agentRoutes({} as any));
@@ -145,111 +228,138 @@ function createApp(actor: Record<string, unknown>) {
   return app;
 }
 
-describe("agent cross-tenant route authorization", () => {
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
+function resetMockDefaults() {
+  vi.clearAllMocks();
+  for (const mock of Object.values(mockAgentService)) mock.mockReset();
+  for (const mock of Object.values(mockAccessService)) mock.mockReset();
+  for (const mock of Object.values(mockApprovalService)) mock.mockReset();
+  for (const mock of Object.values(mockBudgetService)) mock.mockReset();
+  for (const mock of Object.values(mockHeartbeatService)) mock.mockReset();
+  for (const mock of Object.values(mockIssueApprovalService)) mock.mockReset();
+  for (const mock of Object.values(mockIssueService)) mock.mockReset();
+  for (const mock of Object.values(mockSecretService)) mock.mockReset();
+  for (const mock of Object.values(mockAgentInstructionsService)) mock.mockReset();
+  for (const mock of Object.values(mockCompanySkillService)) mock.mockReset();
+  mockLogActivity.mockReset();
+  mockGetTelemetryClient.mockReset();
+  mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
+  currentKeyAgentId = agentId;
+  currentAccessCanUser = false;
+  mockAgentService.getById.mockImplementation(async () => ({ ...baseAgent }));
+  mockAgentService.pause.mockImplementation(async () => ({ ...baseAgent }));
+  mockAgentService.resume.mockImplementation(async () => ({ ...baseAgent }));
+  mockAgentService.terminate.mockImplementation(async () => ({ ...baseAgent }));
+  mockAgentService.remove.mockImplementation(async () => ({ ...baseAgent }));
+  mockAgentService.listKeys.mockImplementation(async () => []);
+  mockAgentService.createApiKey.mockImplementation(async () => ({
+    id: keyId,
+    name: baseKey.name,
+    token: "pcp_test_token",
+    createdAt: baseKey.createdAt,
+  }));
+  mockAgentService.getKeyById.mockImplementation(async () => ({
+    ...baseKey,
+    agentId: currentKeyAgentId,
+  }));
+  mockAgentService.revokeKey.mockImplementation(async () => ({
+    ...baseKey,
+    revokedAt: new Date("2026-04-11T00:05:00.000Z"),
+  }));
+  mockAccessService.canUser.mockImplementation(async () => currentAccessCanUser);
+  mockAccessService.hasPermission.mockImplementation(async () => false);
+  mockAccessService.getMembership.mockImplementation(async () => null);
+  mockAccessService.listPrincipalGrants.mockImplementation(async () => []);
+  mockAccessService.ensureMembership.mockImplementation(async () => undefined);
+  mockAccessService.setPrincipalPermission.mockImplementation(async () => undefined);
+  mockHeartbeatService.cancelActiveForAgent.mockImplementation(async () => undefined);
+  mockLogActivity.mockImplementation(async () => undefined);
+}
+
+describe.sequential("agent cross-tenant route authorization", () => {
   beforeEach(() => {
-    vi.clearAllMocks();
-    mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
-    mockAgentService.getById.mockResolvedValue(baseAgent);
-    mockAgentService.pause.mockResolvedValue(baseAgent);
-    mockAgentService.resume.mockResolvedValue(baseAgent);
-    mockAgentService.terminate.mockResolvedValue(baseAgent);
-    mockAgentService.remove.mockResolvedValue(baseAgent);
-    mockAgentService.listKeys.mockResolvedValue([]);
-    mockAgentService.createApiKey.mockResolvedValue({
-      id: keyId,
-      name: baseKey.name,
-      token: "pcp_test_token",
-      createdAt: baseKey.createdAt,
-    });
-    mockAgentService.getKeyById.mockResolvedValue(baseKey);
-    mockAgentService.revokeKey.mockResolvedValue({
-      ...baseKey,
-      revokedAt: new Date("2026-04-11T00:05:00.000Z"),
-    });
-    mockHeartbeatService.cancelActiveForAgent.mockResolvedValue(undefined);
-    mockLogActivity.mockResolvedValue(undefined);
+    resetMockDefaults();
   });
 
-  it("rejects cross-tenant board pause before mutating the agent", async () => {
-    const app = createApp({
+  it("enforces company boundaries before mutating or reading agent keys", async () => {
+    const crossTenantActor = {
       type: "board",
       userId: "mallory",
       companyIds: [],
       source: "session",
       isInstanceAdmin: false,
-    });
+    };
+    const deniedCases = [
+      {
+        label: "pause",
+        request: (app: express.Express) =>
+          requestApp(app, (baseUrl) => request(baseUrl).post(`/api/agents/${agentId}/pause`).send({})),
+        untouched: [mockAgentService.pause, mockHeartbeatService.cancelActiveForAgent],
+      },
+      {
+        label: "list keys",
+        request: (app: express.Express) =>
+          requestApp(app, (baseUrl) => request(baseUrl).get(`/api/agents/${agentId}/keys`)),
+        untouched: [mockAgentService.listKeys],
+      },
+      {
+        label: "create key",
+        request: (app: express.Express) =>
+          requestApp(app, (baseUrl) => request(baseUrl).post(`/api/agents/${agentId}/keys`).send({ name: "exploit" })),
+        untouched: [mockAgentService.createApiKey],
+      },
+      {
+        label: "revoke key",
+        request: (app: express.Express) =>
+          requestApp(app, (baseUrl) => request(baseUrl).delete(`/api/agents/${agentId}/keys/${keyId}`)),
+        untouched: [mockAgentService.getKeyById, mockAgentService.revokeKey],
+      },
+    ];
 
-    const res = await request(app).post(`/api/agents/${agentId}/pause`).send({});
+    for (const deniedCase of deniedCases) {
+      resetMockDefaults();
+      const app = await createApp(crossTenantActor);
+      const res = await deniedCase.request(app);
 
-    expect(res.status).toBe(403);
-    expect(res.body.error).toContain("User does not have access to this company");
-    expect(mockAgentService.getById).toHaveBeenCalledWith(agentId);
-    expect(mockAgentService.pause).not.toHaveBeenCalled();
-    expect(mockHeartbeatService.cancelActiveForAgent).not.toHaveBeenCalled();
-  });
+      expect(res.status, `${deniedCase.label}: ${JSON.stringify(res.body)}`).toBe(403);
+      expect(res.body.error).toContain("User does not have access to this company");
+      expect(mockAgentService.getById).toHaveBeenCalledWith(agentId);
+      for (const mock of deniedCase.untouched) {
+        expect(mock).not.toHaveBeenCalled();
+      }
+    }
 
-  it("rejects cross-tenant board key listing before reading any keys", async () => {
-    const app = createApp({
-      type: "board",
-      userId: "mallory",
-      companyIds: [],
-      source: "session",
-      isInstanceAdmin: false,
-    });
+    resetMockDefaults();
+    currentKeyAgentId = "44444444-4444-4444-8444-444444444444";
+    currentAccessCanUser = true;
 
-    const res = await request(app).get(`/api/agents/${agentId}/keys`);
-
-    expect(res.status).toBe(403);
-    expect(res.body.error).toContain("User does not have access to this company");
-    expect(mockAgentService.getById).toHaveBeenCalledWith(agentId);
-    expect(mockAgentService.listKeys).not.toHaveBeenCalled();
-  });
-
-  it("rejects cross-tenant board key creation before minting a token", async () => {
-    const app = createApp({
-      type: "board",
-      userId: "mallory",
-      companyIds: [],
-      source: "session",
-      isInstanceAdmin: false,
-    });
-
-    const res = await request(app)
-      .post(`/api/agents/${agentId}/keys`)
-      .send({ name: "exploit" });
-
-    expect(res.status).toBe(403);
-    expect(res.body.error).toContain("User does not have access to this company");
-    expect(mockAgentService.getById).toHaveBeenCalledWith(agentId);
-    expect(mockAgentService.createApiKey).not.toHaveBeenCalled();
-  });
-
-  it("rejects cross-tenant board key revocation before touching the key", async () => {
-    const app = createApp({
-      type: "board",
-      userId: "mallory",
-      companyIds: [],
-      source: "session",
-      isInstanceAdmin: false,
-    });
-
-    const res = await request(app).delete(`/api/agents/${agentId}/keys/${keyId}`);
-
-    expect(res.status).toBe(403);
-    expect(res.body.error).toContain("User does not have access to this company");
-    expect(mockAgentService.getById).toHaveBeenCalledWith(agentId);
-    expect(mockAgentService.getKeyById).not.toHaveBeenCalled();
-    expect(mockAgentService.revokeKey).not.toHaveBeenCalled();
-  });
-
-  it("requires the key to belong to the route agent before revocation", async () => {
-    mockAgentService.getKeyById.mockResolvedValue({
-      ...baseKey,
-      agentId: "44444444-4444-4444-8444-444444444444",
-    });
-    mockAccessService.canUser.mockResolvedValue(true);
-
-    const app = createApp({
+    const app = await createApp({
       type: "board",
       userId: "board-user",
       companyIds: [companyId],
@@ -257,7 +367,7 @@ describe("agent cross-tenant route authorization", () => {
       isInstanceAdmin: false,
     });
 
-    const res = await request(app).delete(`/api/agents/${agentId}/keys/${keyId}`);
+    const res = await requestApp(app, (baseUrl) => request(baseUrl).delete(`/api/agents/${agentId}/keys/${keyId}`));
 
     expect(res.status).toBe(404);
     expect(res.body.error).toContain("Key not found");

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

@@ -103,6 +103,33 @@ async function createApp() {
   return app;
 }
 
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
 function makeAgent() {
   return {
     id: "11111111-1111-4111-8111-111111111111",
@@ -129,7 +156,7 @@ describe("agent instructions bundle routes", () => {
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     mockSyncInstructionsBundleConfigFromFilePath.mockImplementation((_agent, config) => config);
     mockFindServerAdapter.mockImplementation((_type: string) => ({ type: _type }));
     mockAgentService.getById.mockResolvedValue(makeAgent());
@@ -194,8 +221,11 @@ describe("agent instructions bundle routes", () => {
   });
 
   it("returns bundle metadata", async () => {
-    const res = await request(await createApp())
-      .get("/api/agents/11111111-1111-4111-8111-111111111111/instructions-bundle?companyId=company-1");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl)
+        .get("/api/agents/11111111-1111-4111-8111-111111111111/instructions-bundle?companyId=company-1"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(res.body).toMatchObject({
@@ -208,13 +238,13 @@ describe("agent instructions bundle routes", () => {
   });
 
   it("writes a bundle file and persists compatibility config", async () => {
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .put("/api/agents/11111111-1111-4111-8111-111111111111/instructions-bundle/file?companyId=company-1")
       .send({
         path: "AGENTS.md",
         content: "# Updated Agent\n",
         clearLegacyPromptTemplate: true,
-      });
+      }));
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockAgentInstructionsService.writeFile).toHaveBeenCalledWith(
@@ -250,14 +280,14 @@ describe("agent instructions bundle routes", () => {
       },
     });
 
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .patch("/api/agents/11111111-1111-4111-8111-111111111111?companyId=company-1")
       .send({
         adapterType: "claude_local",
         adapterConfig: {
           model: "claude-sonnet-4",
         },
-      });
+      }));
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockAgentService.update).toHaveBeenCalledWith(
@@ -289,13 +319,13 @@ describe("agent instructions bundle routes", () => {
       },
     });
 
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .patch("/api/agents/11111111-1111-4111-8111-111111111111?companyId=company-1")
       .send({
         adapterConfig: {
           command: "codex --profile engineer",
         },
-      });
+      }));
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockAgentService.update).toHaveBeenCalledWith(
@@ -327,14 +357,14 @@ describe("agent instructions bundle routes", () => {
       },
     });
 
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .patch("/api/agents/11111111-1111-4111-8111-111111111111?companyId=company-1")
       .send({
         replaceAdapterConfig: true,
         adapterConfig: {
           command: "codex --profile engineer",
         },
-      });
+      }));
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(res.body.adapterConfig).toMatchObject({

server/src/__tests__/agent-live-run-routes.test.ts

@@ -7,8 +7,10 @@ const mockAgentService = vi.hoisted(() => ({
 }));
 
 const mockHeartbeatService = vi.hoisted(() => ({
+  buildRunOutputSilence: vi.fn(),
   getRunIssueSummary: vi.fn(),
   getActiveRunIssueSummaryForAgent: vi.fn(),
+  buildRunOutputSilence: vi.fn(),
   getRunLogAccess: vi.fn(),
   readLog: vi.fn(),
 }));
@@ -91,6 +93,33 @@ async function createApp() {
   return app;
 }
 
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
 describe("agent live run routes", () => {
   beforeEach(() => {
     vi.resetModules();
@@ -104,7 +133,7 @@ describe("agent live run routes", () => {
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     mockIssueService.getByIdentifier.mockResolvedValue({
       id: "issue-1",
       companyId: "company-1",
@@ -132,6 +161,7 @@ describe("agent live run routes", () => {
       feedbackDataSharingPreference: "prompt",
     });
     mockInstanceSettingsService.listCompanyIds.mockResolvedValue(["company-1"]);
+    mockHeartbeatService.buildRunOutputSilence.mockResolvedValue(null);
     mockHeartbeatService.getRunIssueSummary.mockResolvedValue({
       id: "run-1",
       status: "running",
@@ -144,6 +174,7 @@ describe("agent live run routes", () => {
       issueId: "issue-1",
     });
     mockHeartbeatService.getActiveRunIssueSummaryForAgent.mockResolvedValue(null);
+    mockHeartbeatService.buildRunOutputSilence.mockResolvedValue(null);
     mockHeartbeatService.getRunLogAccess.mockResolvedValue({
       id: "run-1",
       companyId: "company-1",
@@ -160,12 +191,15 @@ describe("agent live run routes", () => {
   });
 
   it("returns a compact active run payload for issue polling", async () => {
-    const res = await request(await createApp()).get("/api/issues/PAP-1295/active-run");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl).get("/api/issues/PAP-1295/active-run"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockIssueService.getByIdentifier).toHaveBeenCalledWith("PAP-1295");
     expect(mockHeartbeatService.getRunIssueSummary).toHaveBeenCalledWith("run-1");
-    expect(res.body).toEqual({
+    expect(res.body).toMatchObject({
       id: "run-1",
       status: "running",
       invocationSource: "on_demand",
@@ -177,6 +211,7 @@ describe("agent live run routes", () => {
       issueId: "issue-1",
       agentName: "Builder",
       adapterType: "codex_local",
+      outputSilence: null,
     });
     expect(res.body).not.toHaveProperty("resultJson");
     expect(res.body).not.toHaveProperty("contextSnapshot");
@@ -207,7 +242,10 @@ describe("agent live run routes", () => {
       issueId: "issue-1",
     });
 
-    const res = await request(await createApp()).get("/api/issues/PAP-1295/active-run");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl).get("/api/issues/PAP-1295/active-run"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockHeartbeatService.getRunIssueSummary).toHaveBeenCalledWith("run-1");
@@ -222,7 +260,10 @@ describe("agent live run routes", () => {
   });
 
   it("uses narrow run log metadata lookups for log polling", async () => {
-    const res = await request(await createApp()).get("/api/heartbeat-runs/run-1/log?offset=12&limitBytes=64");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl).get("/api/heartbeat-runs/run-1/log?offset=12&limitBytes=64"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockHeartbeatService.getRunLogAccess).toHaveBeenCalledWith("run-1");

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

@@ -165,6 +165,33 @@ async function createApp(db: Record<string, unknown> = createDb()) {
   return app;
 }
 
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
 function makeAgent(adapterType: string) {
   return {
     id: "11111111-1111-4111-8111-111111111111",
@@ -184,14 +211,27 @@ function makeAgent(adapterType: string) {
   };
 }
 
-describe("agent skill routes", () => {
+describe.sequential("agent skill routes", () => {
   beforeEach(() => {
     vi.resetModules();
     vi.doUnmock("../routes/agents.js");
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
+    for (const mock of Object.values(mockAgentService)) mock.mockReset();
+    for (const mock of Object.values(mockAccessService)) mock.mockReset();
+    for (const mock of Object.values(mockApprovalService)) mock.mockReset();
+    for (const mock of Object.values(mockIssueApprovalService)) mock.mockReset();
+    for (const mock of Object.values(mockAgentInstructionsService)) mock.mockReset();
+    for (const mock of Object.values(mockCompanySkillService)) mock.mockReset();
+    for (const mock of Object.values(mockSecretService)) mock.mockReset();
+    mockLogActivity.mockReset();
+    mockTrackAgentCreated.mockReset();
+    mockGetTelemetryClient.mockReset();
+    mockSyncInstructionsBundleConfigFromFilePath.mockReset();
+    mockAdapter.listSkills.mockReset();
+    mockAdapter.syncSkills.mockReset();
     mockSyncInstructionsBundleConfigFromFilePath.mockImplementation((_agent, config) => config);
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockAgentService.resolveByReference.mockResolvedValue({
@@ -276,8 +316,11 @@ describe("agent skill routes", () => {
   it("skips runtime materialization when listing Claude skills", async () => {
     mockAgentService.getById.mockResolvedValue(makeAgent("claude_local"));
 
-    const res = await request(await createApp())
-      .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl)
+        .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockAdapter.listSkills).toHaveBeenCalledWith(
@@ -301,8 +344,11 @@ describe("agent skill routes", () => {
       warnings: [],
     });
 
-    const res = await request(await createApp())
-      .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl)
+        .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
   });
@@ -318,8 +364,11 @@ describe("agent skill routes", () => {
       warnings: [],
     });
 
-    const res = await request(await createApp())
-      .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1");
+    const res = await requestApp(
+      await createApp(),
+      (baseUrl) => request(baseUrl)
+        .get("/api/agents/11111111-1111-4111-8111-111111111111/skills?companyId=company-1"),
+    );
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
   });
@@ -327,9 +376,9 @@ describe("agent skill routes", () => {
   it("skips runtime materialization when syncing Claude skills", async () => {
     mockAgentService.getById.mockResolvedValue(makeAgent("claude_local"));
 
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .post("/api/agents/11111111-1111-4111-8111-111111111111/skills/sync?companyId=company-1")
-      .send({ desiredSkills: ["paperclipai/paperclip/paperclip"] });
+      .send({ desiredSkills: ["paperclipai/paperclip/paperclip"] }));
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockAdapter.syncSkills).toHaveBeenCalled();
@@ -338,9 +387,9 @@ describe("agent skill routes", () => {
   it("canonicalizes desired skill references before syncing", async () => {
     mockAgentService.getById.mockResolvedValue(makeAgent("claude_local"));
 
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .post("/api/agents/11111111-1111-4111-8111-111111111111/skills/sync?companyId=company-1")
-      .send({ desiredSkills: ["paperclip"] });
+      .send({ desiredSkills: ["paperclip"] }));
 
     expect(res.status, JSON.stringify(res.body)).toBe(200);
     expect(mockAgentService.update).toHaveBeenCalledWith(
@@ -357,7 +406,7 @@ describe("agent skill routes", () => {
   });
 
   it("persists canonical desired skills when creating an agent directly", async () => {
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .post("/api/companies/company-1/agents")
       .send({
         name: "QA Agent",
@@ -365,7 +414,7 @@ describe("agent skill routes", () => {
         adapterType: "claude_local",
         desiredSkills: ["paperclip"],
         adapterConfig: {},
-      });
+      }));
 
     expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(mockAgentService.create).toHaveBeenCalledWith(
@@ -388,7 +437,7 @@ describe("agent skill routes", () => {
   });
 
   it("materializes a managed AGENTS.md for directly created local agents", async () => {
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .post("/api/companies/company-1/agents")
       .send({
         name: "QA Agent",
@@ -397,7 +446,7 @@ describe("agent skill routes", () => {
         adapterConfig: {
           promptTemplate: "You are QA.",
         },
-      });
+      }));
 
     expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(mockAgentService.update).toHaveBeenCalledWith(
@@ -418,14 +467,14 @@ describe("agent skill routes", () => {
   });
 
   it("materializes the bundled CEO instruction set for default CEO agents", async () => {
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .post("/api/companies/company-1/agents")
       .send({
         name: "CEO",
         role: "ceo",
         adapterType: "claude_local",
         adapterConfig: {},
-      });
+      }));
 
     expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(mockAgentInstructionsService.materializeManagedBundle).toHaveBeenCalledWith(
@@ -445,14 +494,14 @@ describe("agent skill routes", () => {
   });
 
   it("materializes the bundled default instruction set for non-CEO agents with no prompt template", async () => {
-    const res = await request(await createApp())
+    const res = await requestApp(await createApp(), (baseUrl) => request(baseUrl)
       .post("/api/companies/company-1/agents")
       .send({
         name: "Engineer",
         role: "engineer",
         adapterType: "claude_local",
         adapterConfig: {},
-      });
+      }));
 
     expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     await vi.waitFor(() => {
@@ -511,6 +560,53 @@ describe("agent skill routes", () => {
     );
   });
 
+  it("preserves hire source issues, icons, desired skills, and approval payload details", async () => {
+    const db = createDb(true);
+    const sourceIssueId = "22222222-2222-4222-8222-222222222222";
+
+    const res = await request(await createApp(db))
+      .post("/api/companies/company-1/agent-hires")
+      .send({
+        name: "Security Engineer",
+        role: "engineer",
+        icon: "crown",
+        adapterType: "claude_local",
+        desiredSkills: ["paperclip"],
+        adapterConfig: {},
+        sourceIssueId,
+      });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(201);
+    expect(mockAgentService.create).toHaveBeenCalledWith(
+      "company-1",
+      expect.objectContaining({
+        icon: "crown",
+        adapterConfig: expect.objectContaining({
+          paperclipSkillSync: expect.objectContaining({
+            desiredSkills: ["paperclipai/paperclip/paperclip"],
+          }),
+        }),
+      }),
+    );
+    expect(mockApprovalService.create).toHaveBeenCalledWith(
+      "company-1",
+      expect.objectContaining({
+        payload: expect.objectContaining({
+          icon: "crown",
+          desiredSkills: ["paperclipai/paperclip/paperclip"],
+          requestedConfigurationSnapshot: expect.objectContaining({
+            desiredSkills: ["paperclipai/paperclip/paperclip"],
+          }),
+        }),
+      }),
+    );
+    expect(mockIssueApprovalService.linkManyForApproval).toHaveBeenCalledWith(
+      "approval-1",
+      [sourceIssueId],
+      { agentId: null, userId: "local-board" },
+    );
+  });
+
   it("uses managed AGENTS config in hire approval payloads", async () => {
     const res = await request(await createApp(createDb(true)))
       .post("/api/companies/company-1/agent-hires")

server/src/__tests__/approval-routes-idempotency.test.ts

@@ -92,7 +92,7 @@ describe("approval routes idempotent retries", () => {
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     mockApprovalService.list.mockReset();
     mockApprovalService.getById.mockReset();
     mockApprovalService.create.mockReset();

server/src/__tests__/assets.test.ts

@@ -106,6 +106,33 @@ async function createApp(storage: ReturnType<typeof createStorageService>) {
   return app;
 }
 
+async function requestApp(
+  app: express.Express,
+  buildRequest: (baseUrl: string) => request.Test,
+) {
+  const { createServer } = await vi.importActual<typeof import("node:http")>("node:http");
+  const server = createServer(app);
+  try {
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected HTTP server to listen on a TCP port");
+    }
+    return await buildRequest(`http://127.0.0.1:${address.port}`);
+  } finally {
+    if (server.listening) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) reject(error);
+          else resolve();
+        });
+      });
+    }
+  }
+}
+
 describe("POST /api/companies/:companyId/assets/images", () => {
   beforeEach(() => {
     vi.resetModules();
@@ -116,7 +143,7 @@ describe("POST /api/companies/:companyId/assets/images", () => {
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     createAssetMock.mockReset();
     getAssetByIdMock.mockReset();
     logActivityMock.mockReset();
@@ -128,10 +155,12 @@ describe("POST /api/companies/:companyId/assets/images", () => {
 
     createAssetMock.mockResolvedValue(createAsset());
 
-    const res = await request(app)
-      .post("/api/companies/company-1/assets/images")
-      .field("namespace", "goals")
-      .attach("file", Buffer.from("png"), "logo.png");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/assets/images")
+        .field("namespace", "goals")
+        .attach("file", Buffer.from("png"), "logo.png"),
+    );
 
     expect([200, 201], JSON.stringify(res.body)).toContain(res.status);
     expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
@@ -155,10 +184,12 @@ describe("POST /api/companies/:companyId/assets/images", () => {
       originalFilename: "note.txt",
     });
 
-    const res = await request(app)
-      .post("/api/companies/company-1/assets/images")
-      .field("namespace", "issues/drafts")
-      .attach("file", Buffer.from("hello"), { filename: "note.txt", contentType: "text/plain" });
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/assets/images")
+        .field("namespace", "issues/drafts")
+        .attach("file", Buffer.from("hello"), { filename: "note.txt", contentType: "text/plain" }),
+    );
 
     expect([200, 201]).toContain(res.status);
     expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
@@ -174,7 +205,7 @@ describe("POST /api/companies/:companyId/logo", () => {
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     createAssetMock.mockReset();
     getAssetByIdMock.mockReset();
     logActivityMock.mockReset();
@@ -186,11 +217,13 @@ describe("POST /api/companies/:companyId/logo", () => {
 
     createAssetMock.mockResolvedValue(createAsset());
 
-    const res = await request(app)
-      .post("/api/companies/company-1/logo")
-      .attach("file", Buffer.from("png"), "logo.png");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/logo")
+        .attach("file", Buffer.from("png"), "logo.png"),
+    );
 
-    expect(res.status).toBe(201);
+    expect(res.status, JSON.stringify({ body: res.body, text: res.text, createCalls: createAssetMock.mock.calls.length })).toBe(201);
     expect(res.body.contentPath).toBe("/api/assets/asset-1/content");
     expect(createAssetMock).toHaveBeenCalledTimes(1);
     expect(png.__calls.putFileInputs[0]).toMatchObject({
@@ -212,17 +245,19 @@ describe("POST /api/companies/:companyId/logo", () => {
       originalFilename: "logo.svg",
     });
 
-    const res = await request(app)
-      .post("/api/companies/company-1/logo")
-      .attach(
-        "file",
-        Buffer.from(
-          "<svg xmlns='http://www.w3.org/2000/svg' onload='alert(1)'><script>alert(1)</script><a href='https://evil.example/'><circle cx='12' cy='12' r='10'/></a></svg>",
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/logo")
+        .attach(
+          "file",
+          Buffer.from(
+            "<svg xmlns='http://www.w3.org/2000/svg' onload='alert(1)'><script>alert(1)</script><a href='https://evil.example/'><circle cx='12' cy='12' r='10'/></a></svg>",
+          ),
+          "logo.svg",
         ),
-        "logo.svg",
-      );
+    );
 
-    expect(res.status).toBe(201);
+    expect(res.status, JSON.stringify({ body: res.body, text: res.text, createCalls: createAssetMock.mock.calls.length })).toBe(201);
     expect(svg.__calls.putFileInputs).toHaveLength(1);
     const stored = svg.__calls.putFileInputs[0];
     expect(stored.contentType).toBe("image/svg+xml");
@@ -241,11 +276,13 @@ describe("POST /api/companies/:companyId/logo", () => {
     createAssetMock.mockResolvedValue(createAsset());
 
     const file = Buffer.alloc(150 * 1024, "a");
-    const res = await request(app)
-      .post("/api/companies/company-1/logo")
-      .attach("file", file, "within-limit.png");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/logo")
+        .attach("file", file, "within-limit.png"),
+    );
 
-    expect(res.status).toBe(201);
+    expect(res.status, JSON.stringify({ body: res.body, text: res.text, createCalls: createAssetMock.mock.calls.length })).toBe(201);
   });
 
   it("rejects logo files larger than the general attachment limit", async () => {
@@ -253,9 +290,11 @@ describe("POST /api/companies/:companyId/logo", () => {
     createAssetMock.mockResolvedValue(createAsset());
 
     const file = Buffer.alloc(MAX_ATTACHMENT_BYTES + 1, "a");
-    const res = await request(app)
-      .post("/api/companies/company-1/logo")
-      .attach("file", file, "too-large.png");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/logo")
+        .attach("file", file, "too-large.png"),
+    );
 
     expect(res.status).toBe(422);
     expect(res.body.error).toBe(`Image exceeds ${MAX_ATTACHMENT_BYTES} bytes`);
@@ -265,9 +304,11 @@ describe("POST /api/companies/:companyId/logo", () => {
     const app = await createApp(createStorageService("text/plain"));
     createAssetMock.mockResolvedValue(createAsset());
 
-    const res = await request(app)
-      .post("/api/companies/company-1/logo")
-      .attach("file", Buffer.from("not an image"), "note.txt");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/logo")
+        .attach("file", Buffer.from("not an image"), "note.txt"),
+    );
 
     expect(res.status).toBe(422);
     expect(res.body.error).toBe("Unsupported image type: text/plain");
@@ -278,9 +319,11 @@ describe("POST /api/companies/:companyId/logo", () => {
     const app = await createApp(createStorageService("image/svg+xml"));
     createAssetMock.mockResolvedValue(createAsset());
 
-    const res = await request(app)
-      .post("/api/companies/company-1/logo")
-      .attach("file", Buffer.from("not actually svg"), "logo.svg");
+    const res = await requestApp(app, (baseUrl) =>
+      request(baseUrl)
+        .post("/api/companies/company-1/logo")
+        .attach("file", Buffer.from("not actually svg"), "logo.svg"),
+    );
 
     expect(res.status).toBe(422);
     expect(res.body.error).toBe("SVG could not be sanitized");

server/src/__tests__/auth-routes.test.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { authRoutes } from "../routes/auth.js";
 
 function createSelectChain(rows: unknown[]) {
   return {
@@ -32,16 +34,12 @@ function createUpdateChain(row: unknown) {
 
 function createDb(row: Record<string, unknown>) {
   return {
-    select: vi.fn(() => createSelectChain([row])),
-    update: vi.fn(() => createUpdateChain(row)),
+    select: () => createSelectChain([row]),
+    update: () => createUpdateChain(row),
   } as any;
 }
 
-async function createApp(actor: Express.Request["actor"], row: Record<string, unknown>) {
-  const [{ authRoutes }, { errorHandler }] = await Promise.all([
-    import("../routes/auth.js"),
-    import("../middleware/index.js"),
-  ]);
+function createApp(actor: Express.Request["actor"], row: Record<string, unknown>) {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -53,7 +51,7 @@ async function createApp(actor: Express.Request["actor"], row: Record<string, un
   return app;
 }
 
-describe("auth routes", () => {
+describe.sequential("auth routes", () => {
   const baseUser = {
     id: "user-1",
     name: "Jane Example",
@@ -61,10 +59,6 @@ describe("auth routes", () => {
     image: "https://example.com/jane.png",
   };
 
-  beforeEach(() => {
-    vi.resetModules();
-  });
-
   it("returns the persisted user profile in the session payload", async () => {
     const app = await createApp(
       {

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

@@ -415,7 +415,7 @@ describe("claude execute", () => {
     const previousPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
     process.env.HOME = root;
     process.env.PAPERCLIP_HOME = paperclipHome;
-    process.env.PAPERCLIP_INSTANCE_ID = "default";
+    delete process.env.PAPERCLIP_INSTANCE_ID;
 
     try {
       const first = await execute({
@@ -574,7 +574,7 @@ describe("claude execute", () => {
     const previousPaperclipInstanceId = process.env.PAPERCLIP_INSTANCE_ID;
     process.env.HOME = root;
     process.env.PAPERCLIP_HOME = paperclipHome;
-    process.env.PAPERCLIP_INSTANCE_ID = "default";
+    delete process.env.PAPERCLIP_INSTANCE_ID;
 
     try {
       const first = await execute({
@@ -711,8 +711,9 @@ describe("claude execute", () => {
       expect(result.exitCode).toBe(1);
       expect(result.errorCode).toBe("claude_transient_upstream");
       expect(result.errorFamily).toBe("transient_upstream");
-      expect(result.retryNotBefore).toBe("2026-04-22T21:00:00.000Z");
-      expect(result.resultJson?.retryNotBefore).toBe("2026-04-22T21:00:00.000Z");
+      const expectedRetryNotBefore = "2026-04-22T21:00:00.000Z";
+      expect(result.retryNotBefore).toBe(expectedRetryNotBefore);
+      expect(result.resultJson?.retryNotBefore).toBe(expectedRetryNotBefore);
       expect(result.errorMessage ?? "").toContain("extra usage");
       expect(new Date(String(result.resultJson?.transientRetryNotBefore)).getTime()).toBe(
         new Date("2026-04-22T21:00:00.000Z").getTime(),

server/src/__tests__/cli-auth-routes.test.ts

@@ -1,7 +1,6 @@
-import type { Server } from "node:http";
 import express from "express";
 import request from "supertest";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mockAccessService = vi.hoisted(() => ({
   isInstanceAdmin: vi.fn(),
@@ -35,20 +34,6 @@ vi.mock("../services/index.js", () => ({
   deduplicateAgentName: vi.fn((name: string) => name),
 }));
 
-let currentServer: Server | null = null;
-
-async function closeCurrentServer() {
-  if (!currentServer) return;
-  const server = currentServer;
-  currentServer = null;
-  await new Promise<void>((resolve, reject) => {
-    server.close((err) => {
-      if (err) reject(err);
-      else resolve();
-    });
-  });
-}
-
 function registerModuleMocks() {
   vi.doMock("../routes/authz.js", async () => vi.importActual("../routes/authz.js"));
 
@@ -62,16 +47,31 @@ function registerModuleMocks() {
   }));
 }
 
+let appImportCounter = 0;
+
 async function createApp(actor: any, db: any = {} as any) {
-  await closeCurrentServer();
+  appImportCounter += 1;
+  const routeModulePath = `../routes/access.js?cli-auth-routes-${appImportCounter}`;
+  const middlewareModulePath = `../middleware/index.js?cli-auth-routes-${appImportCounter}`;
   const [{ accessRoutes }, { errorHandler }] = await Promise.all([
-    vi.importActual<typeof import("../routes/access.js")>("../routes/access.js"),
-    vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
+    import(routeModulePath) as Promise<typeof import("../routes/access.js")>,
+    import(middlewareModulePath) as Promise<typeof import("../middleware/index.js")>,
   ]);
+
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
-    req.actor = actor;
+    req.actor = {
+      ...actor,
+      companyIds: Array.isArray(actor.companyIds) ? [...actor.companyIds] : actor.companyIds,
+      memberships: Array.isArray(actor.memberships)
+        ? actor.memberships.map((membership: unknown) =>
+            typeof membership === "object" && membership !== null
+              ? { ...membership }
+              : membership,
+          )
+        : actor.memberships,
+    };
     next();
   });
   app.use(
@@ -84,13 +84,10 @@ async function createApp(actor: any, db: any = {} as any) {
     }),
   );
   app.use(errorHandler);
-  currentServer = app.listen(0);
-  return currentServer;
+  return app;
 }
 
-describe("cli auth routes", () => {
-  afterEach(closeCurrentServer);
-
+describe.sequential("cli auth routes", () => {
   beforeEach(() => {
     vi.resetModules();
     vi.doUnmock("../services/index.js");
@@ -101,7 +98,7 @@ describe("cli auth routes", () => {
     vi.resetAllMocks();
   });
 
-  it("creates a CLI auth challenge with approval metadata", async () => {
+  it.sequential("creates a CLI auth challenge with approval metadata", async () => {
     mockBoardAuthService.createCliAuthChallenge.mockResolvedValue({
       challenge: {
         id: "challenge-1",
@@ -120,7 +117,7 @@ describe("cli auth routes", () => {
         requestedAccess: "board",
       });
 
-    expect(res.status).toBe(201);
+    expect(res.status, res.text || JSON.stringify(res.body)).toBe(201);
     expect(res.body).toMatchObject({
       id: "challenge-1",
       token: "pcp_cli_auth_secret",
@@ -132,18 +129,18 @@ describe("cli auth routes", () => {
     expect(res.body.approvalUrl).toContain("/cli-auth/challenge-1?token=pcp_cli_auth_secret");
   });
 
-  it("rejects anonymous access to generic skill documents", async () => {
-    const app = await createApp({ type: "none", source: "none" });
-    const [indexRes, skillRes] = await Promise.all([
-      request(app).get("/api/skills/index"),
-      request(app).get("/api/skills/paperclip"),
-    ]);
+  it.sequential("rejects anonymous access to generic skill documents", async () => {
+    const indexApp = await createApp({ type: "none", source: "none" });
+    const skillApp = await createApp({ type: "none", source: "none" });
 
-    expect(indexRes.status).toBe(401);
-    expect(skillRes.status).toBe(401);
+    const indexRes = await request(indexApp).get("/api/skills/index");
+    const skillRes = await request(skillApp).get("/api/skills/paperclip");
+
+    expect(indexRes.status, JSON.stringify(indexRes.body)).toBe(401);
+    expect(skillRes.status, skillRes.text || JSON.stringify(skillRes.body)).toBe(401);
   });
 
-  it("serves the invite-scoped paperclip skill anonymously for active invites", async () => {
+  it.sequential("serves the invite-scoped paperclip skill anonymously for active invites", async () => {
     const invite = {
       id: "invite-1",
       companyId: "company-1",
@@ -174,7 +171,7 @@ describe("cli auth routes", () => {
     expect(res.text).toContain("# Paperclip Skill");
   });
 
-  it("marks challenge status as requiring sign-in for anonymous viewers", async () => {
+  it.sequential("marks challenge status as requiring sign-in for anonymous viewers", async () => {
     mockBoardAuthService.describeCliAuthChallenge.mockResolvedValue({
       id: "challenge-1",
       status: "pending",
@@ -197,7 +194,7 @@ describe("cli auth routes", () => {
     expect(res.body.canApprove).toBe(false);
   });
 
-  it("approves a CLI auth challenge for a signed-in board user", async () => {
+  it.sequential("approves a CLI auth challenge for a signed-in board user", async () => {
     mockBoardAuthService.approveCliAuthChallenge.mockResolvedValue({
       status: "approved",
       challenge: {
@@ -242,7 +239,7 @@ describe("cli auth routes", () => {
     );
   });
 
-  it("logs approve activity for instance admins without company memberships", async () => {
+  it.sequential("logs approve activity for instance admins without company memberships", async () => {
     mockBoardAuthService.approveCliAuthChallenge.mockResolvedValue({
       status: "approved",
       challenge: {
@@ -275,7 +272,7 @@ describe("cli auth routes", () => {
     expect(mockLogActivity).toHaveBeenCalledTimes(2);
   });
 
-  it("logs revoke activity with resolved audit company ids", async () => {
+  it.sequential("logs revoke activity with resolved audit company ids", async () => {
     mockBoardAuthService.assertCurrentBoardKey.mockResolvedValue({
       id: "board-key-3",
       userId: "admin-2",

server/src/__tests__/codex-local-skill-injection.test.ts

@@ -32,6 +32,7 @@ async function createCustomSkill(root: string, skillName: string) {
 
 describe("codex local adapter skill injection", () => {
   const paperclipKey = "paperclipai/paperclip/paperclip";
+  const createAgentKey = "paperclipai/paperclip/paperclip-create-agent";
   const cleanupDirs = new Set<string>();
 
   afterEach(async () => {
@@ -48,6 +49,7 @@ describe("codex local adapter skill injection", () => {
     cleanupDirs.add(skillsHome);
 
     await createPaperclipRepoSkill(currentRepo, "paperclip");
+    await createPaperclipRepoSkill(currentRepo, "paperclip-create-agent");
     await createPaperclipRepoSkill(oldRepo, "paperclip");
     await fs.symlink(path.join(oldRepo, "skills", "paperclip"), path.join(skillsHome, "paperclip"));
 
@@ -58,23 +60,39 @@ describe("codex local adapter skill injection", () => {
       },
       {
         skillsHome,
-        skillsEntries: [{
-          key: paperclipKey,
-          runtimeName: "paperclip",
-          source: path.join(currentRepo, "skills", "paperclip"),
-        }],
+        skillsEntries: [
+          {
+            key: paperclipKey,
+            runtimeName: "paperclip",
+            source: path.join(currentRepo, "skills", "paperclip"),
+          },
+          {
+            key: createAgentKey,
+            runtimeName: "paperclip-create-agent",
+            source: path.join(currentRepo, "skills", "paperclip-create-agent"),
+          },
+        ],
       },
     );
 
     expect(await fs.realpath(path.join(skillsHome, "paperclip"))).toBe(
       await fs.realpath(path.join(currentRepo, "skills", "paperclip")),
     );
+    expect(await fs.realpath(path.join(skillsHome, "paperclip-create-agent"))).toBe(
+      await fs.realpath(path.join(currentRepo, "skills", "paperclip-create-agent")),
+    );
     expect(logs).toContainEqual(
       expect.objectContaining({
         stream: "stdout",
         chunk: expect.stringContaining('Repaired Codex skill "paperclip"'),
       }),
     );
+    expect(logs).toContainEqual(
+      expect.objectContaining({
+        stream: "stdout",
+        chunk: expect.stringContaining('Injected Codex skill "paperclip-create-agent"'),
+      }),
+    );
   });
 
   it("preserves a custom Codex skill symlink outside Paperclip repo checkouts", async () => {

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

@@ -13,6 +13,7 @@ async function makeTempDir(prefix: string): Promise<string> {
 
 describe("codex local skill sync", () => {
   const paperclipKey = "paperclipai/paperclip/paperclip";
+  const createAgentKey = "paperclipai/paperclip/paperclip-create-agent";
   const cleanupDirs = new Set<string>();
 
   afterEach(async () => {
@@ -41,8 +42,11 @@ describe("codex local skill sync", () => {
     const before = await listCodexSkills(ctx);
     expect(before.mode).toBe("ephemeral");
     expect(before.desiredSkills).toContain(paperclipKey);
+    expect(before.desiredSkills).toContain(createAgentKey);
     expect(before.entries.find((entry) => entry.key === paperclipKey)?.required).toBe(true);
     expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");
+    expect(before.entries.find((entry) => entry.key === createAgentKey)?.required).toBe(true);
+    expect(before.entries.find((entry) => entry.key === createAgentKey)?.state).toBe("configured");
     expect(before.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("CODEX_HOME/skills/");
   });
 
@@ -92,7 +96,9 @@ describe("codex local skill sync", () => {
 
     const after = await syncCodexSkills(configuredCtx, []);
     expect(after.desiredSkills).toContain(paperclipKey);
+    expect(after.desiredSkills).toContain(createAgentKey);
     expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");
+    expect(after.entries.find((entry) => entry.key === createAgentKey)?.state).toBe("configured");
   });
 
   it("normalizes legacy flat Paperclip skill refs before reporting configured state", async () => {

server/src/__tests__/company-branding-route.test.ts

@@ -91,7 +91,7 @@ describe("PATCH /api/companies/:companyId/branding", () => {
     vi.doUnmock("../routes/companies.js");
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
-    vi.resetAllMocks();
+    vi.clearAllMocks();
   });
 
   it("rejects non-CEO agent callers", async () => {

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

@@ -39,37 +39,45 @@ const mockFeedbackService = vi.hoisted(() => ({
   saveIssueVote: vi.fn(),
 }));
 
-function registerModuleMocks() {
-  vi.doMock("../routes/authz.js", async () => vi.importActual("../routes/authz.js"));
+vi.mock("../services/access.js", () => ({
+  accessService: () => mockAccessService,
+}));
 
-  vi.doMock("../services/access.js", () => ({
-    accessService: () => mockAccessService,
-  }));
+vi.mock("../services/activity-log.js", () => ({
+  logActivity: mockLogActivity,
+}));
 
-  vi.doMock("../services/activity-log.js", () => ({
-    logActivity: mockLogActivity,
-  }));
+vi.mock("../services/agents.js", () => ({
+  agentService: () => mockAgentService,
+}));
 
-  vi.doMock("../services/agents.js", () => ({
-    agentService: () => mockAgentService,
-  }));
+vi.mock("../services/budgets.js", () => ({
+  budgetService: () => mockBudgetService,
+}));
 
-  vi.doMock("../services/budgets.js", () => ({
-    budgetService: () => mockBudgetService,
-  }));
+vi.mock("../services/companies.js", () => ({
+  companyService: () => mockCompanyService,
+}));
 
-  vi.doMock("../services/companies.js", () => ({
-    companyService: () => mockCompanyService,
-  }));
+vi.mock("../services/company-portability.js", () => ({
+  companyPortabilityService: () => mockCompanyPortabilityService,
+}));
 
-  vi.doMock("../services/company-portability.js", () => ({
-    companyPortabilityService: () => mockCompanyPortabilityService,
-  }));
+vi.mock("../services/feedback.js", () => ({
+  feedbackService: () => mockFeedbackService,
+}));
 
-  vi.doMock("../services/feedback.js", () => ({
-    feedbackService: () => mockFeedbackService,
-  }));
+vi.mock("../services/index.js", () => ({
+  accessService: () => mockAccessService,
+  agentService: () => mockAgentService,
+  budgetService: () => mockBudgetService,
+  companyPortabilityService: () => mockCompanyPortabilityService,
+  companyService: () => mockCompanyService,
+  feedbackService: () => mockFeedbackService,
+  logActivity: mockLogActivity,
+}));
 
+function registerCompanyRouteMocks() {
   vi.doMock("../services/index.js", () => ({
     accessService: () => mockAccessService,
     agentService: () => mockAgentService,
@@ -81,10 +89,16 @@ function registerModuleMocks() {
   }));
 }
 
+let appImportCounter = 0;
+
 async function createApp(actor: Record<string, unknown>) {
+  registerCompanyRouteMocks();
+  appImportCounter += 1;
+  const routeModulePath = `../routes/companies.js?company-portability-routes-${appImportCounter}`;
+  const middlewareModulePath = `../middleware/index.js?company-portability-routes-${appImportCounter}`;
   const [{ companyRoutes }, { errorHandler }] = await Promise.all([
-    vi.importActual<typeof import("../routes/companies.js")>("../routes/companies.js"),
-    vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
+    import(routeModulePath) as Promise<typeof import("../routes/companies.js")>,
+    import(middlewareModulePath) as Promise<typeof import("../middleware/index.js")>,
   ]);
   const app = express();
   app.use(express.json());
@@ -98,6 +112,8 @@ async function createApp(actor: Record<string, unknown>) {
 }
 
 const companyId = "11111111-1111-4111-8111-111111111111";
+const ceoAgentId = "ceo-agent";
+const engineerAgentId = "engineer-agent";
 
 const exportRequest = {
   include: { company: true, agents: true, projects: true },
@@ -123,33 +139,36 @@ function createExportResult() {
   };
 }
 
-describe("company portability routes", () => {
+describe.sequential("company portability routes", () => {
   beforeEach(() => {
-    vi.resetModules();
-    vi.doUnmock("../services/access.js");
-    vi.doUnmock("../services/activity-log.js");
-    vi.doUnmock("../services/agents.js");
-    vi.doUnmock("../services/budgets.js");
-    vi.doUnmock("../services/companies.js");
-    vi.doUnmock("../services/company-portability.js");
-    vi.doUnmock("../services/feedback.js");
-    vi.doUnmock("../services/index.js");
-    vi.doUnmock("../routes/companies.js");
-    vi.doUnmock("../routes/authz.js");
-    vi.doUnmock("../middleware/index.js");
-    registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
+    mockAgentService.getById.mockImplementation(async (id: string) => ({
+      id,
+      companyId,
+      role: id === ceoAgentId ? "ceo" : "engineer",
+    }));
+    mockCompanyPortabilityService.exportBundle.mockResolvedValue(createExportResult());
+    mockCompanyPortabilityService.previewExport.mockResolvedValue({
+      rootPath: "paperclip",
+      manifest: { agents: [], skills: [], projects: [], issues: [], envInputs: [], includes: { company: true, agents: true, projects: true, issues: false, skills: false }, company: null, schemaVersion: 1, generatedAt: new Date().toISOString(), source: null },
+      files: {},
+      fileInventory: [],
+      counts: { files: 0, agents: 0, skills: 0, projects: 0, issues: 0 },
+      warnings: [],
+      paperclipExtensionPath: ".paperclip.yaml",
+    });
+    mockCompanyPortabilityService.previewImport.mockResolvedValue({ ok: true });
+    mockCompanyPortabilityService.importBundle.mockResolvedValue({
+      company: { id: companyId, action: "created" },
+      agents: [],
+      warnings: [],
+    });
   });
 
-  it("rejects non-CEO agents from CEO-safe export preview routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId,
-      role: "engineer",
-    });
+  it.sequential("rejects non-CEO agents from CEO-safe export preview routes", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: engineerAgentId,
       companyId,
       source: "agent_key",
       runId: "run-1",
@@ -164,15 +183,10 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.previewExport).not.toHaveBeenCalled();
   });
 
-  it("rejects non-CEO agents from legacy and CEO-safe export bundle routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId,
-      role: "engineer",
-    });
+  it.sequential("rejects non-CEO agents from legacy and CEO-safe export bundle routes", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: engineerAgentId,
       companyId,
       source: "agent_key",
       runId: "run-1",
@@ -187,12 +201,7 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.exportBundle).not.toHaveBeenCalled();
   });
 
-  it("allows CEO agents to use company-scoped export preview routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId,
-      role: "ceo",
-    });
+  it.sequential("allows CEO agents to use company-scoped export preview routes", async () => {
     mockCompanyPortabilityService.previewExport.mockResolvedValue({
       rootPath: "paperclip",
       manifest: { agents: [], skills: [], projects: [], issues: [], envInputs: [], includes: { company: true, agents: true, projects: true, issues: false, skills: false }, company: null, schemaVersion: 1, generatedAt: new Date().toISOString(), source: null },
@@ -204,7 +213,7 @@ describe("company portability routes", () => {
     });
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: ceoAgentId,
       companyId,
       source: "agent_key",
       runId: "run-1",
@@ -218,16 +227,11 @@ describe("company portability routes", () => {
     expect(res.body.rootPath).toBe("paperclip");
   });
 
-  it("allows CEO agents to export through legacy and CEO-safe bundle routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId,
-      role: "ceo",
-    });
+  it.sequential("allows CEO agents to export through legacy and CEO-safe bundle routes", async () => {
     mockCompanyPortabilityService.exportBundle.mockResolvedValue(createExportResult());
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: ceoAgentId,
       companyId,
       source: "agent_key",
       runId: "run-1",
@@ -244,7 +248,7 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.exportBundle).toHaveBeenNthCalledWith(2, companyId, exportRequest);
   });
 
-  it("allows board users to export through legacy and CEO-safe bundle routes", async () => {
+  it.sequential("allows board users to export through legacy and CEO-safe bundle routes", async () => {
     mockCompanyPortabilityService.exportBundle.mockResolvedValue(createExportResult());
     const app = await createApp({
       type: "board",
@@ -263,15 +267,10 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.exportBundle).toHaveBeenCalledTimes(2);
   });
 
-  it("rejects replace collision strategy on CEO-safe import routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId: "11111111-1111-4111-8111-111111111111",
-      role: "ceo",
-    });
+  it.sequential("rejects replace collision strategy on CEO-safe import routes", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: ceoAgentId,
       companyId: "11111111-1111-4111-8111-111111111111",
       source: "agent_key",
       runId: "run-1",
@@ -291,10 +290,10 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.previewImport).not.toHaveBeenCalled();
   });
 
-  it("keeps global import preview routes board-only", async () => {
+  it.sequential("keeps global import preview routes board-only", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: engineerAgentId,
       companyId: "11111111-1111-4111-8111-111111111111",
       source: "agent_key",
       runId: "run-1",
@@ -313,7 +312,7 @@ describe("company portability routes", () => {
     expect(res.body.error).toContain("Board access required");
   });
 
-  it("requires instance admin for new-company import preview", async () => {
+  it.sequential("requires instance admin for new-company import preview", async () => {
     const app = await createApp({
       type: "board",
       userId: "user-1",
@@ -336,15 +335,10 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.previewImport).not.toHaveBeenCalled();
   });
 
-  it("rejects replace collision strategy on CEO-safe import apply routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId: "11111111-1111-4111-8111-111111111111",
-      role: "ceo",
-    });
+  it.sequential("rejects replace collision strategy on CEO-safe import apply routes", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: ceoAgentId,
       companyId: "11111111-1111-4111-8111-111111111111",
       source: "agent_key",
       runId: "run-1",
@@ -364,15 +358,10 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.importBundle).not.toHaveBeenCalled();
   });
 
-  it("rejects non-CEO agents from CEO-safe import preview routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId: "11111111-1111-4111-8111-111111111111",
-      role: "engineer",
-    });
+  it.sequential("rejects non-CEO agents from CEO-safe import preview routes", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: engineerAgentId,
       companyId: "11111111-1111-4111-8111-111111111111",
       source: "agent_key",
       runId: "run-1",
@@ -392,15 +381,10 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.previewImport).not.toHaveBeenCalled();
   });
 
-  it("rejects non-CEO agents from CEO-safe import apply routes", async () => {
-    mockAgentService.getById.mockResolvedValue({
-      id: "agent-1",
-      companyId: "11111111-1111-4111-8111-111111111111",
-      role: "engineer",
-    });
+  it.sequential("rejects non-CEO agents from CEO-safe import apply routes", async () => {
     const app = await createApp({
       type: "agent",
-      agentId: "agent-1",
+      agentId: engineerAgentId,
       companyId: "11111111-1111-4111-8111-111111111111",
       source: "agent_key",
       runId: "run-1",
@@ -420,7 +404,7 @@ describe("company portability routes", () => {
     expect(mockCompanyPortabilityService.importBundle).not.toHaveBeenCalled();
   });
 
-  it("requires instance admin for new-company import apply", async () => {
+  it.sequential("requires instance admin for new-company import apply", async () => {
     const app = await createApp({
       type: "board",
       userId: "user-1",

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

@@ -86,7 +86,7 @@ describe("company skill mutation permissions", () => {
     vi.doUnmock("../routes/authz.js");
     vi.doUnmock("../middleware/index.js");
     registerModuleMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });
     mockCompanySkillService.importFromSource.mockResolvedValue({
       imported: [],

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

@@ -105,14 +105,147 @@ describe("environment config helpers", () => {
     });
   });
 
-  it("rejects unsupported environment drivers", () => {
-    expect(() =>
-      normalizeEnvironmentConfig({
-        driver: "sandbox" as any,
-        config: {
-          provider: "fake",
+  it("normalizes sandbox config into its canonical stored shape", () => {
+    const config = normalizeEnvironmentConfig({
+      driver: "sandbox",
+      config: {
+        provider: "fake",
+        image: "  ubuntu:24.04  ",
+      },
+    });
+
+    expect(config).toEqual({
+      provider: "fake",
+      image: "ubuntu:24.04",
+      reuseLease: false,
+    });
+  });
+
+  it("parses a persisted sandbox environment into a typed driver config", () => {
+    const parsed = parseEnvironmentDriverConfig({
+      driver: "sandbox",
+      config: {
+        provider: "fake",
+        image: "ubuntu:24.04",
+        reuseLease: true,
+      },
+    });
+
+    expect(parsed).toEqual({
+      driver: "sandbox",
+      config: {
+        provider: "fake",
+        image: "ubuntu:24.04",
+        reuseLease: true,
+      },
+    });
+  });
+
+  it("normalizes schema-driven sandbox config into the generic plugin-backed stored shape", () => {
+    const config = normalizeEnvironmentConfig({
+      driver: "sandbox",
+      config: {
+        provider: "secure-plugin",
+        template: "  base  ",
+        apiKey: "22222222-2222-2222-2222-222222222222",
+        timeoutMs: "450000",
+      },
+    });
+
+    expect(config).toEqual({
+      provider: "secure-plugin",
+      template: "  base  ",
+      apiKey: "22222222-2222-2222-2222-222222222222",
+      timeoutMs: 450000,
+      reuseLease: false,
+    });
+  });
+
+  it("normalizes plugin-backed sandbox provider config without server provider changes", () => {
+    const config = normalizeEnvironmentConfig({
+      driver: "sandbox",
+      config: {
+        provider: "fake-plugin",
+        image: "  fake:test  ",
+        timeoutMs: "120000",
+        reuseLease: true,
+        customFlag: "kept",
+      },
+    });
+
+    expect(config).toEqual({
+      provider: "fake-plugin",
+      image: "  fake:test  ",
+      timeoutMs: 120000,
+      reuseLease: true,
+      customFlag: "kept",
+    });
+  });
+
+  it("parses a persisted schema-driven sandbox environment into a typed driver config", () => {
+    const parsed = parseEnvironmentDriverConfig({
+      driver: "sandbox",
+      config: {
+        provider: "secure-plugin",
+        template: "base",
+        apiKey: "22222222-2222-2222-2222-222222222222",
+        timeoutMs: 300000,
+        reuseLease: true,
+      },
+    });
+
+    expect(parsed).toEqual({
+      driver: "sandbox",
+      config: {
+        provider: "secure-plugin",
+        template: "base",
+        apiKey: "22222222-2222-2222-2222-222222222222",
+        timeoutMs: 300000,
+        reuseLease: true,
+      },
+    });
+  });
+
+  it("parses a persisted plugin-backed sandbox environment into a typed driver config", () => {
+    const parsed = parseEnvironmentDriverConfig({
+      driver: "sandbox",
+      config: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        timeoutMs: 300000,
+        reuseLease: true,
+      },
+    });
+
+    expect(parsed).toEqual({
+      driver: "sandbox",
+      config: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        timeoutMs: 300000,
+        reuseLease: true,
+      },
+    });
+  });
+
+  it("normalizes plugin environment config into its canonical stored shape", () => {
+    const config = normalizeEnvironmentConfig({
+      driver: "plugin",
+      config: {
+        pluginKey: "acme.environments",
+        driverKey: "fake-plugin",
+        driverConfig: {
+          template: "base",
         },
-      }),
-    ).toThrow(HttpError);
+      },
+    });
+
+    expect(config).toEqual({
+      pluginKey: "acme.environments",
+      driverKey: "fake-plugin",
+      driverConfig: {
+        template: "base",
+      },
+    });
   });
 });

server/src/__tests__/environment-execution-target.test.ts

@@ -0,0 +1,58 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockResolveEnvironmentDriverConfigForRuntime } = vi.hoisted(() => ({
+  mockResolveEnvironmentDriverConfigForRuntime: vi.fn(),
+}));
+
+vi.mock("../services/environment-config.js", () => ({
+  resolveEnvironmentDriverConfigForRuntime: mockResolveEnvironmentDriverConfigForRuntime,
+}));
+
+import {
+  DEFAULT_SANDBOX_REMOTE_CWD,
+  resolveEnvironmentExecutionTarget,
+} from "../services/environment-execution-target.js";
+
+describe("resolveEnvironmentExecutionTarget", () => {
+  beforeEach(() => {
+    mockResolveEnvironmentDriverConfigForRuntime.mockReset();
+  });
+
+  it("uses a bounded default cwd for sandbox targets when lease metadata omits remoteCwd", async () => {
+    mockResolveEnvironmentDriverConfigForRuntime.mockResolvedValue({
+      driver: "sandbox",
+      config: {
+        provider: "fake-plugin",
+        reuseLease: false,
+        timeoutMs: 30_000,
+      },
+    });
+
+    const target = await resolveEnvironmentExecutionTarget({
+      db: {} as never,
+      companyId: "company-1",
+      adapterType: "codex_local",
+      environment: {
+        id: "env-1",
+        driver: "sandbox",
+        config: {
+          provider: "fake-plugin",
+        },
+      },
+      leaseId: "lease-1",
+      leaseMetadata: {},
+      lease: null,
+      environmentRuntime: null,
+    });
+
+    expect(target).toMatchObject({
+      kind: "remote",
+      transport: "sandbox",
+      providerKey: "fake-plugin",
+      remoteCwd: DEFAULT_SANDBOX_REMOTE_CWD,
+      leaseId: "lease-1",
+      environmentId: "env-1",
+      timeoutMs: 30_000,
+    });
+  });
+});

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

@@ -1,16 +1,29 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mockEnsureSshWorkspaceReady = vi.hoisted(() => vi.fn());
+const mockProbePluginEnvironmentDriver = vi.hoisted(() => vi.fn());
+const mockProbePluginSandboxProviderDriver = vi.hoisted(() => vi.fn());
+const mockResolvePluginSandboxProviderDriverByKey = vi.hoisted(() => vi.fn());
 
 vi.mock("@paperclipai/adapter-utils/ssh", () => ({
   ensureSshWorkspaceReady: mockEnsureSshWorkspaceReady,
 }));
 
+vi.mock("../services/plugin-environment-driver.js", () => ({
+  probePluginEnvironmentDriver: mockProbePluginEnvironmentDriver,
+  probePluginSandboxProviderDriver: mockProbePluginSandboxProviderDriver,
+  resolvePluginSandboxProviderDriverByKey: mockResolvePluginSandboxProviderDriverByKey,
+}));
+
 import { probeEnvironment } from "../services/environment-probe.ts";
 
 describe("probeEnvironment", () => {
   beforeEach(() => {
     mockEnsureSshWorkspaceReady.mockReset();
+    mockProbePluginEnvironmentDriver.mockReset();
+    mockProbePluginSandboxProviderDriver.mockReset();
+    mockResolvePluginSandboxProviderDriverByKey.mockReset();
+    mockResolvePluginSandboxProviderDriverByKey.mockResolvedValue(null);
   });
 
   it("reports local environments as immediately available", async () => {
@@ -75,6 +88,123 @@ describe("probeEnvironment", () => {
     expect(mockEnsureSshWorkspaceReady).toHaveBeenCalledTimes(1);
   });
 
+  it("reports fake sandbox environments as ready without external calls", async () => {
+    const result = await probeEnvironment({} as any, {
+      id: "env-sandbox",
+      companyId: "company-1",
+      name: "Fake Sandbox",
+      description: null,
+      driver: "sandbox",
+      status: "active",
+      config: {
+        provider: "fake",
+        image: "ubuntu:24.04",
+        reuseLease: true,
+      },
+      metadata: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      driver: "sandbox",
+      summary: "Fake sandbox provider is ready for image ubuntu:24.04.",
+      details: {
+        provider: "fake",
+        image: "ubuntu:24.04",
+        reuseLease: true,
+      },
+    });
+    expect(mockEnsureSshWorkspaceReady).not.toHaveBeenCalled();
+  });
+
+  it("routes plugin-backed sandbox provider probes through plugin workers", async () => {
+    mockProbePluginSandboxProviderDriver.mockResolvedValue({
+      ok: true,
+      driver: "sandbox",
+      summary: "Fake plugin probe passed.",
+      details: {
+        provider: "fake-plugin",
+        metadata: { ready: true },
+      },
+    });
+    const workerManager = {} as any;
+
+    const result = await probeEnvironment({} as any, {
+      id: "env-sandbox-plugin",
+      companyId: "company-1",
+      name: "Fake Plugin Sandbox",
+      description: null,
+      driver: "sandbox",
+      status: "active",
+      config: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        reuseLease: false,
+      },
+      metadata: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }, { pluginWorkerManager: workerManager });
+
+    expect(result.ok).toBe(true);
+    expect(mockProbePluginSandboxProviderDriver).toHaveBeenCalledWith({
+      db: expect.anything(),
+      workerManager,
+      companyId: "company-1",
+      environmentId: "env-sandbox-plugin",
+      provider: "fake-plugin",
+      config: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        reuseLease: false,
+      },
+    });
+  });
+
+  it("routes plugin environment probes through the plugin worker host", async () => {
+    mockProbePluginEnvironmentDriver.mockResolvedValue({
+      ok: true,
+      driver: "plugin",
+      summary: "Plugin probe passed.",
+      details: {
+        metadata: { ready: true },
+      },
+    });
+    const workerManager = {} as any;
+
+    const result = await probeEnvironment({} as any, {
+      id: "env-plugin",
+      companyId: "company-1",
+      name: "Plugin Sandbox",
+      description: null,
+      driver: "plugin",
+      status: "active",
+      config: {
+        pluginKey: "acme.environments",
+        driverKey: "sandbox",
+        driverConfig: { template: "base" },
+      },
+      metadata: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    }, { pluginWorkerManager: workerManager });
+
+    expect(result.ok).toBe(true);
+    expect(mockProbePluginEnvironmentDriver).toHaveBeenCalledWith({
+      db: expect.anything(),
+      workerManager,
+      companyId: "company-1",
+      environmentId: "env-plugin",
+      config: {
+        pluginKey: "acme.environments",
+        driverKey: "sandbox",
+        driverConfig: { template: "base" },
+      },
+    });
+  });
+
   it("captures SSH probe failures without throwing", async () => {
     mockEnsureSshWorkspaceReady.mockRejectedValue(
       Object.assign(new Error("Permission denied"), {

server/src/__tests__/environment-run-orchestrator.test.ts

@@ -0,0 +1,350 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Hoisted mocks — must be declared before any imports that reference them
+// ---------------------------------------------------------------------------
+
+const mockResolveEnvironmentExecutionTarget = vi.hoisted(() => vi.fn());
+const mockAdapterExecutionTargetToRemoteSpec = vi.hoisted(() => vi.fn());
+const mockBuildWorkspaceRealizationRequest = vi.hoisted(() => vi.fn());
+const mockUpdateLeaseMetadata = vi.hoisted(() => vi.fn());
+const mockUpdateExecutionWorkspace = vi.hoisted(() => vi.fn());
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/environment-execution-target.js", () => ({
+  resolveEnvironmentExecutionTarget: mockResolveEnvironmentExecutionTarget,
+  resolveEnvironmentExecutionTransport: vi.fn().mockResolvedValue(null),
+}));
+
+vi.mock("@paperclipai/adapter-utils/execution-target", () => ({
+  adapterExecutionTargetToRemoteSpec: mockAdapterExecutionTargetToRemoteSpec,
+}));
+
+vi.mock("../services/workspace-realization.js", () => ({
+  buildWorkspaceRealizationRequest: mockBuildWorkspaceRealizationRequest,
+}));
+
+vi.mock("../services/environments.js", () => ({
+  environmentService: vi.fn(() => ({
+    ensureLocalEnvironment: vi.fn(),
+    getById: vi.fn(),
+    acquireLease: vi.fn(),
+    releaseLease: vi.fn(),
+    updateLeaseMetadata: mockUpdateLeaseMetadata,
+  })),
+}));
+
+vi.mock("../services/execution-workspaces.js", () => ({
+  executionWorkspaceService: vi.fn(() => ({
+    update: mockUpdateExecutionWorkspace,
+  })),
+}));
+
+vi.mock("../services/activity-log.js", () => ({
+  logActivity: mockLogActivity,
+}));
+
+// ---------------------------------------------------------------------------
+// Imports after mocks
+// ---------------------------------------------------------------------------
+
+import {
+  environmentRunOrchestrator,
+  EnvironmentRunError,
+} from "../services/environment-run-orchestrator.ts";
+import type { Environment, EnvironmentLease, ExecutionWorkspace } from "@paperclipai/shared";
+import type { RealizedExecutionWorkspace } from "../services/workspace-runtime.ts";
+import type { EnvironmentRuntimeService } from "../services/environment-runtime.ts";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function makeEnvironment(driver: string = "local"): Environment {
+  return {
+    id: "env-1",
+    companyId: "company-1",
+    name: "Test Environment",
+    description: null,
+    driver: driver as Environment["driver"],
+    status: "active",
+    config: {},
+    metadata: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function makeLease(overrides: Partial<EnvironmentLease> = {}): EnvironmentLease {
+  return {
+    id: "lease-1",
+    companyId: "company-1",
+    environmentId: "env-1",
+    executionWorkspaceId: null,
+    issueId: null,
+    heartbeatRunId: "run-1",
+    status: "active",
+    leasePolicy: "ephemeral",
+    provider: "local",
+    providerLeaseId: null,
+    acquiredAt: new Date(),
+    lastUsedAt: new Date(),
+    expiresAt: null,
+    releasedAt: null,
+    failureReason: null,
+    cleanupStatus: null,
+    metadata: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function makeExecutionWorkspace(cwd: string = "/workspace/project"): RealizedExecutionWorkspace {
+  return {
+    baseCwd: "/workspace",
+    source: "project_primary",
+    projectId: "project-1",
+    workspaceId: "ws-1",
+    repoUrl: null,
+    repoRef: null,
+    strategy: "project_primary",
+    cwd,
+    branchName: null,
+    worktreePath: null,
+    warnings: [],
+    created: false,
+  };
+}
+
+function makePersistedExecutionWorkspace(
+  overrides: Partial<ExecutionWorkspace> = {},
+): ExecutionWorkspace {
+  return {
+    id: "ew-1",
+    companyId: "company-1",
+    projectId: "project-1",
+    projectWorkspaceId: null,
+    sourceIssueId: null,
+    mode: "standard",
+    strategyType: "project_primary",
+    name: "workspace",
+    status: "open",
+    cwd: "/workspace/project",
+    repoUrl: null,
+    baseRef: null,
+    branchName: null,
+    providerType: "local",
+    providerRef: null,
+    derivedFromExecutionWorkspaceId: null,
+    lastUsedAt: new Date(),
+    openedAt: new Date(),
+    closedAt: null,
+    cleanupEligibleAt: null,
+    cleanupReason: null,
+    config: null,
+    metadata: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function makeRealizeInput(overrides: {
+  environment?: Environment;
+  lease?: EnvironmentLease;
+  persistedExecutionWorkspace?: ExecutionWorkspace | null;
+} = {}): Parameters<ReturnType<typeof environmentRunOrchestrator>["realizeForRun"]>[0] {
+  return {
+    environment: overrides.environment ?? makeEnvironment("local"),
+    lease: overrides.lease ?? makeLease(),
+    adapterType: "claude_local",
+    companyId: "company-1",
+    issueId: null,
+    heartbeatRunId: "run-1",
+    executionWorkspace: makeExecutionWorkspace(),
+    effectiveExecutionWorkspaceMode: null,
+    persistedExecutionWorkspace: overrides.persistedExecutionWorkspace !== undefined
+      ? overrides.persistedExecutionWorkspace
+      : null,
+  };
+}
+
+function makeMockRuntime(overrides: Partial<EnvironmentRuntimeService> = {}): EnvironmentRuntimeService {
+  return {
+    acquireRunLease: vi.fn(),
+    releaseRunLeases: vi.fn(),
+    realizeWorkspace: vi.fn().mockResolvedValue({
+      cwd: "/workspace/project",
+      metadata: {
+        workspaceRealization: {
+          version: 1,
+          driver: "local",
+          cwd: "/workspace/project",
+        },
+      },
+    }),
+    ...overrides,
+  } as unknown as EnvironmentRuntimeService;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("environmentRunOrchestrator — realizeForRun", () => {
+  const mockDb = {} as any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mockBuildWorkspaceRealizationRequest.mockReturnValue({
+      version: 1,
+      adapterType: "claude_local",
+      companyId: "company-1",
+      environmentId: "env-1",
+      executionWorkspaceId: null,
+      issueId: null,
+      heartbeatRunId: "run-1",
+      requestedMode: null,
+      source: {
+        kind: "project_primary",
+        localPath: "/workspace/project",
+        projectId: null,
+        projectWorkspaceId: null,
+        repoUrl: null,
+        repoRef: null,
+        strategy: "project_primary",
+        branchName: null,
+        worktreePath: null,
+      },
+      runtimeOverlay: {
+        provisionCommand: null,
+      },
+    });
+
+    mockAdapterExecutionTargetToRemoteSpec.mockReturnValue({
+      kind: "local",
+      environmentId: "env-1",
+      leaseId: "lease-1",
+    });
+
+    mockUpdateLeaseMetadata.mockResolvedValue(null);
+    mockUpdateExecutionWorkspace.mockResolvedValue(null);
+    mockLogActivity.mockResolvedValue(undefined);
+  });
+
+  it("happy path: returns lease, executionTarget, and remoteExecution on successful realization", async () => {
+    const executionTarget = { kind: "local", environmentId: "env-1", leaseId: "lease-1" };
+    const remoteExecution = { kind: "local", environmentId: "env-1", leaseId: "lease-1" };
+
+    mockResolveEnvironmentExecutionTarget.mockResolvedValue(executionTarget);
+    mockAdapterExecutionTargetToRemoteSpec.mockReturnValue(remoteExecution);
+
+    const runtime = makeMockRuntime();
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    const result = await orchestrator.realizeForRun(makeRealizeInput());
+
+    expect(result.lease).toBeDefined();
+    expect(result.executionTarget).toEqual(executionTarget);
+    expect(result.remoteExecution).toEqual(remoteExecution);
+    expect(result.workspaceRealization).toEqual(
+      expect.objectContaining({ version: 1, driver: "local" }),
+    );
+
+    expect(runtime.realizeWorkspace).toHaveBeenCalledOnce();
+    expect(mockResolveEnvironmentExecutionTarget).toHaveBeenCalledOnce();
+  });
+
+  it("realization failure: runtime.realizeWorkspace throws → EnvironmentRunError with code workspace_realization_failed", async () => {
+    const runtime = makeMockRuntime({
+      realizeWorkspace: vi.fn().mockRejectedValue(new Error("sandbox unreachable")),
+    });
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    await expect(orchestrator.realizeForRun(makeRealizeInput())).rejects.toSatisfy(
+      (err: unknown) =>
+        err instanceof EnvironmentRunError &&
+        err.code === "workspace_realization_failed" &&
+        err.environmentId === "env-1" &&
+        err.driver === "local",
+    );
+
+    expect(mockResolveEnvironmentExecutionTarget).not.toHaveBeenCalled();
+  });
+
+  it("target resolution failure: resolveEnvironmentExecutionTarget throws → EnvironmentRunError with code transport_resolution_failed", async () => {
+    mockResolveEnvironmentExecutionTarget.mockRejectedValue(new Error("network error"));
+
+    const runtime = makeMockRuntime();
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    await expect(orchestrator.realizeForRun(makeRealizeInput())).rejects.toSatisfy(
+      (err: unknown) =>
+        err instanceof EnvironmentRunError &&
+        err.code === "transport_resolution_failed" &&
+        err.environmentId === "env-1",
+    );
+  });
+
+  it("non-sandbox driver skips workspace realization and goes straight to target resolution", async () => {
+    const environment = makeEnvironment("plugin" as Environment["driver"]);
+    const executionTarget = null;
+
+    mockResolveEnvironmentExecutionTarget.mockResolvedValue(executionTarget);
+
+    const runtime = makeMockRuntime();
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    const result = await orchestrator.realizeForRun(
+      makeRealizeInput({ environment }),
+    );
+
+    expect(runtime.realizeWorkspace).not.toHaveBeenCalled();
+    expect(result.workspaceRealization).toEqual({});
+    expect(result.executionTarget).toBeNull();
+  });
+
+  it("persisted metadata is updated on lease and execution workspace after realization", async () => {
+    const persistedExecutionWorkspace = makePersistedExecutionWorkspace();
+    const updatedLease = makeLease({
+      metadata: { workspaceRealization: { version: 1, driver: "local", cwd: "/workspace/project" } },
+    });
+    const updatedEw = { ...persistedExecutionWorkspace, metadata: { workspaceRealizationRequest: {}, workspaceRealization: {} } };
+
+    mockUpdateLeaseMetadata.mockResolvedValue(updatedLease);
+    mockUpdateExecutionWorkspace.mockResolvedValue(updatedEw);
+    mockResolveEnvironmentExecutionTarget.mockResolvedValue({ kind: "local", environmentId: "env-1", leaseId: "lease-1" });
+
+    const runtime = makeMockRuntime();
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    const result = await orchestrator.realizeForRun(
+      makeRealizeInput({ persistedExecutionWorkspace }),
+    );
+
+    // Lease metadata should have been updated with workspaceRealization
+    expect(mockUpdateLeaseMetadata).toHaveBeenCalledOnce();
+    expect(mockUpdateLeaseMetadata).toHaveBeenCalledWith(
+      "lease-1",
+      expect.objectContaining({ workspaceRealization: expect.any(Object) }),
+    );
+
+    // Execution workspace metadata should have been updated
+    expect(mockUpdateExecutionWorkspace).toHaveBeenCalledOnce();
+    expect(mockUpdateExecutionWorkspace).toHaveBeenCalledWith(
+      "ew-1",
+      expect.objectContaining({
+        metadata: expect.objectContaining({
+          workspaceRealizationRequest: expect.any(Object),
+          workspaceRealization: expect.any(Object),
+        }),
+      }),
+    );
+
+    // The returned lease should reflect the updated value
+    expect(result.lease).toEqual(updatedLease);
+    expect(result.persistedExecutionWorkspace).toEqual(updatedEw);
+  });
+});

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

@@ -0,0 +1,319 @@
+import { randomUUID } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { eq } from "drizzle-orm";
+import {
+  buildSshEnvLabFixtureConfig,
+  getSshEnvLabSupport,
+  startSshEnvLabFixture,
+  stopSshEnvLabFixture,
+  type SshEnvironmentConfig,
+} from "@paperclipai/adapter-utils/ssh";
+import {
+  agents,
+  companies,
+  companySecretVersions,
+  companySecrets,
+  createDb,
+  environmentLeases,
+  environments,
+  heartbeatRuns,
+} from "@paperclipai/db";
+import type { Environment } from "@paperclipai/shared";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { environmentRuntimeService } from "../services/environment-runtime.js";
+import { secretService } from "../services/secrets.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+const sshFixtureSupport = await getSshEnvLabSupport();
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping environment runtime driver contract tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+interface RuntimeContractCase {
+  name: string;
+  driver: string;
+  config: Record<string, unknown>;
+  setup?: () => Promise<() => Promise<void>>;
+  expectLease: (lease: {
+    providerLeaseId: string | null;
+    metadata: Record<string, unknown> | null;
+  }, environment: Environment) => void;
+}
+
+describeEmbeddedPostgres("environment runtime driver contract", () => {
+  let stopDb: (() => Promise<void>) | null = null;
+  let db!: ReturnType<typeof createDb>;
+  const fixtureRoots: string[] = [];
+  const servers: Server[] = [];
+
+  beforeAll(async () => {
+    const started = await startEmbeddedPostgresTestDatabase("environment-runtime-contract");
+    stopDb = started.stop;
+    db = createDb(started.connectionString);
+  });
+
+  afterEach(async () => {
+    for (const server of servers.splice(0)) {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+    while (fixtureRoots.length > 0) {
+      const root = fixtureRoots.pop();
+      if (!root) continue;
+      await stopSshEnvLabFixture(path.join(root, "state.json")).catch(() => undefined);
+      await rm(root, { recursive: true, force: true }).catch(() => undefined);
+    }
+    await db.delete(environmentLeases);
+    await db.delete(heartbeatRuns);
+    await db.delete(agents);
+    await db.delete(environments);
+    await db.delete(companySecretVersions);
+    await db.delete(companySecrets);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await stopDb?.();
+  });
+
+  async function seedEnvironment(input: {
+    driver: string;
+    config: Record<string, unknown>;
+  }) {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const environmentId = randomUUID();
+    const runId = randomUUID();
+    const now = new Date();
+    let config = input.config;
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Acme",
+      status: "active",
+      createdAt: now,
+      updatedAt: now,
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "Contract Agent",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+      createdAt: now,
+      updatedAt: now,
+    });
+    if (typeof config.privateKey === "string" && config.privateKey.length > 0) {
+      const secret = await secretService(db).create(companyId, {
+        name: `environment-contract-private-key-${randomUUID()}`,
+        provider: "local_encrypted",
+        value: config.privateKey,
+      });
+      config = {
+        ...config,
+        privateKey: null,
+        privateKeySecretRef: {
+          type: "secret_ref",
+          secretId: secret.id,
+          version: "latest",
+        },
+      };
+    }
+    await db.insert(environments).values({
+      id: environmentId,
+      companyId,
+      name: `${input.driver} contract`,
+      driver: input.driver,
+      status: "active",
+      config,
+      createdAt: now,
+      updatedAt: now,
+    });
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId,
+      invocationSource: "manual",
+      status: "running",
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    return {
+      companyId,
+      issueId: null,
+      runId,
+      environment: {
+        id: environmentId,
+        companyId,
+        name: `${input.driver} contract`,
+        description: null,
+        driver: input.driver,
+        status: "active",
+        config,
+        metadata: null,
+        createdAt: now,
+        updatedAt: now,
+      } as Environment,
+    };
+  }
+
+  async function startHealthServer() {
+    const server = createServer((req, res) => {
+      if (req.url === "/api/health") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+      }
+      res.writeHead(404).end();
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    servers.push(server);
+    const address = server.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected health server to listen on a TCP port.");
+    }
+    return `http://127.0.0.1:${address.port}`;
+  }
+
+  async function runContract(testCase: RuntimeContractCase) {
+    const cleanup = await testCase.setup?.();
+    try {
+      const runtime = environmentRuntimeService(db);
+      const { companyId, environment, issueId, runId } = await seedEnvironment({
+        driver: testCase.driver,
+        config: testCase.config,
+      });
+
+      const acquired = await runtime.acquireRunLease({
+        companyId,
+        environment,
+        issueId,
+        heartbeatRunId: runId,
+        persistedExecutionWorkspace: null,
+      });
+
+      expect(acquired.environment.id).toBe(environment.id);
+      expect(acquired.lease.companyId).toBe(companyId);
+      expect(acquired.lease.environmentId).toBe(environment.id);
+      expect(acquired.lease.issueId).toBeNull();
+      expect(acquired.lease.heartbeatRunId).toBe(runId);
+      expect(acquired.lease.status).toBe("active");
+      expect(acquired.leaseContext).toEqual({
+        executionWorkspaceId: null,
+        executionWorkspaceMode: null,
+      });
+      expect(acquired.lease.metadata).toMatchObject({
+        driver: testCase.driver,
+        executionWorkspaceMode: null,
+      });
+      testCase.expectLease(acquired.lease, environment);
+
+      const released = await runtime.releaseRunLeases(runId);
+
+      expect(released).toHaveLength(1);
+      expect(released[0]?.environment.id).toBe(environment.id);
+      expect(released[0]?.lease.id).toBe(acquired.lease.id);
+      expect(released[0]?.lease.status).toBe("released");
+
+      const activeRows = await db
+        .select()
+        .from(environmentLeases)
+        .where(eq(environmentLeases.status, "active"));
+      expect(activeRows).toHaveLength(0);
+      await expect(runtime.releaseRunLeases(runId)).resolves.toEqual([]);
+    } finally {
+      await cleanup?.();
+    }
+  }
+
+  const contractCases: RuntimeContractCase[] = [
+    {
+      name: "local",
+      driver: "local",
+      config: {},
+      expectLease: (lease) => {
+        expect(lease.providerLeaseId).toBeNull();
+      },
+    },
+    {
+      name: "fake sandbox",
+      driver: "sandbox",
+      config: {
+        provider: "fake",
+        image: "ubuntu:24.04",
+        reuseLease: false,
+      },
+      expectLease: (lease) => {
+        expect(lease.providerLeaseId).toMatch(/^sandbox:\/\/fake\/[0-9a-f-]+\/[0-9a-f-]+$/);
+        expect(lease.metadata).toMatchObject({
+          provider: "fake",
+          image: "ubuntu:24.04",
+          reuseLease: false,
+        });
+      },
+    },
+  ];
+
+  for (const testCase of contractCases) {
+    it(`${testCase.name} satisfies the acquire/release host contract`, async () => {
+      await runContract(testCase);
+    });
+  }
+
+  it("SSH satisfies the acquire/release host contract", async () => {
+    if (!sshFixtureSupport.supported) {
+      console.warn(`Skipping SSH driver contract test: ${sshFixtureSupport.reason ?? "unsupported environment"}`);
+      return;
+    }
+
+    const fixtureRoot = await mkdtemp(path.join(os.tmpdir(), "paperclip-env-runtime-contract-ssh-"));
+    fixtureRoots.push(fixtureRoot);
+    const fixture = await startSshEnvLabFixture({ statePath: path.join(fixtureRoot, "state.json") });
+    const sshConfig = await buildSshEnvLabFixtureConfig(fixture);
+    const runtimeApiUrl = await startHealthServer();
+    const previousCandidates = process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON;
+    process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON = JSON.stringify([runtimeApiUrl]);
+
+    await runContract({
+      name: "ssh",
+      driver: "ssh",
+      config: sshConfig as SshEnvironmentConfig as unknown as Record<string, unknown>,
+      expectLease: (lease) => {
+        expect(lease.providerLeaseId).toContain(`ssh://${sshConfig.username}@${sshConfig.host}:${sshConfig.port}`);
+        expect(lease.metadata).toMatchObject({
+          host: sshConfig.host,
+          port: sshConfig.port,
+          username: sshConfig.username,
+          remoteWorkspacePath: sshConfig.remoteWorkspacePath,
+          remoteCwd: sshConfig.remoteWorkspacePath,
+          paperclipApiUrl: runtimeApiUrl,
+        });
+      },
+      setup: async () => async () => {
+        if (previousCandidates === undefined) {
+          delete process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON;
+        } else {
+          process.env.PAPERCLIP_RUNTIME_API_CANDIDATES_JSON = previousCandidates;
+        }
+      },
+    });
+  });
+});

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

@@ -18,7 +18,6 @@ const mockProjectService = vi.hoisted(() => ({
 
 const mockIssueService = vi.hoisted(() => ({
   create: vi.fn(),
-  createChild: vi.fn(),
   getById: vi.fn(),
   update: vi.fn(),
   getByIdentifier: vi.fn(),
@@ -29,10 +28,22 @@ const mockEnvironmentService = vi.hoisted(() => ({
   getById: vi.fn(),
 }));
 
-const mockReferenceSummary = vi.hoisted(() => ({
-  inbound: [],
-  outbound: [],
-  documentSources: [],
+const mockIssueReferenceService = vi.hoisted(() => ({
+  deleteDocumentSource: vi.fn(async () => undefined),
+  diffIssueReferenceSummary: vi.fn(() => ({
+    addedReferencedIssues: [],
+    removedReferencedIssues: [],
+    currentReferencedIssues: [],
+  })),
+  emptySummary: vi.fn(() => ({ outbound: [], inbound: [] })),
+  listIssueReferenceSummary: vi.fn(async () => ({ outbound: [], inbound: [] })),
+  syncComment: vi.fn(async () => undefined),
+  syncDocument: vi.fn(async () => undefined),
+  syncIssue: vi.fn(async () => undefined),
+}));
+
+const mockSecretService = vi.hoisted(() => ({
+  normalizeEnvBindingsForPersistence: vi.fn(async (_companyId: string, env: Record<string, unknown>) => env),
 }));
 
 const mockLogActivity = vi.hoisted(() => vi.fn());
@@ -41,10 +52,7 @@ vi.mock("../services/index.js", () => ({
   projectService: () => mockProjectService,
   issueService: () => mockIssueService,
   environmentService: () => mockEnvironmentService,
-  secretService: () => ({
-    normalizeEnvBindingsForPersistence: vi.fn(async (_companyId: string, env: unknown) => env),
-    normalizeAdapterConfigForPersistence: vi.fn(async (_companyId: string, config: unknown) => config),
-  }),
+  issueReferenceService: () => mockIssueReferenceService,
   logActivity: mockLogActivity,
   workspaceOperationService: () => ({}),
   accessService: () => ({
@@ -67,35 +75,19 @@ vi.mock("../services/index.js", () => ({
     listApprovalsForIssue: vi.fn(),
     unlink: vi.fn(),
   }),
-  feedbackService: () => ({
-    listIssueVotesForUser: vi.fn(),
-    listFeedbackTraces: vi.fn(),
-    getFeedbackTraceById: vi.fn(),
-    getFeedbackTraceBundle: vi.fn(),
-    saveIssueVote: vi.fn(),
-  }),
-  instanceSettingsService: () => ({
-    get: vi.fn(async () => ({})),
-    listCompanyIds: vi.fn(async () => []),
-  }),
-  issueReferenceService: () => ({
-    emptySummary: vi.fn(() => mockReferenceSummary),
-    syncIssue: vi.fn(),
-    syncComment: vi.fn(),
-    syncDocument: vi.fn(),
-    deleteDocumentSource: vi.fn(),
-    listIssueReferenceSummary: vi.fn(async () => mockReferenceSummary),
-    diffIssueReferenceSummary: vi.fn(() => ({
-      addedReferencedIssues: [],
-      removedReferencedIssues: [],
-      currentReferencedIssues: [],
-    })),
-  }),
   documentService: () => ({}),
   routineService: () => ({}),
   workProductService: () => ({}),
 }));
 
+vi.mock("../services/environments.js", () => ({
+  environmentService: () => mockEnvironmentService,
+}));
+
+vi.mock("../services/secrets.js", () => ({
+  secretService: () => mockSecretService,
+}));
+
 vi.mock("../services/issue-assignment-wakeup.js", () => ({
   queueIssueAssignmentWakeup: vi.fn(),
 }));
@@ -133,7 +125,7 @@ function createIssueApp() {
   return issueServer;
 }
 
-const sshEnvironmentId = "11111111-1111-4111-8111-111111111111";
+const sandboxEnvironmentId = "11111111-1111-4111-8111-111111111111";
 
 async function closeServer(server: Server | null) {
   if (!server) return;
@@ -162,26 +154,33 @@ describe.sequential("execution environment route guards", () => {
     mockProjectService.resolveByReference.mockReset();
     mockProjectService.listWorkspaces.mockReset();
     mockIssueService.create.mockReset();
-    mockIssueService.createChild.mockReset();
     mockIssueService.getById.mockReset();
     mockIssueService.update.mockReset();
     mockIssueService.getByIdentifier.mockReset();
     mockIssueService.assertCheckoutOwner.mockReset();
     mockEnvironmentService.getById.mockReset();
+    mockIssueReferenceService.deleteDocumentSource.mockClear();
+    mockIssueReferenceService.diffIssueReferenceSummary.mockClear();
+    mockIssueReferenceService.emptySummary.mockClear();
+    mockIssueReferenceService.listIssueReferenceSummary.mockClear();
+    mockIssueReferenceService.syncComment.mockClear();
+    mockIssueReferenceService.syncDocument.mockClear();
+    mockIssueReferenceService.syncIssue.mockClear();
+    mockSecretService.normalizeEnvBindingsForPersistence.mockClear();
     mockLogActivity.mockReset();
   });
 
-  it("accepts SSH environments on project create", async () => {
+  it("accepts sandbox environments on project create", async () => {
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
+      id: sandboxEnvironmentId,
       companyId: "company-1",
-      driver: "ssh",
-      config: {},
+      driver: "sandbox",
+      config: { provider: "fake-plugin" },
     });
     mockProjectService.create.mockResolvedValue({
       id: "project-1",
       companyId: "company-1",
-      name: "SSH Project",
+      name: "Sandboxed Project",
       status: "backlog",
     });
     const app = createProjectApp();
@@ -189,10 +188,10 @@ describe.sequential("execution environment route guards", () => {
     const res = await request(app)
       .post("/api/companies/company-1/projects")
       .send({
-        name: "SSH Project",
+        name: "Sandboxed Project",
         executionWorkspacePolicy: {
           enabled: true,
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 
@@ -200,24 +199,24 @@ describe.sequential("execution environment route guards", () => {
     expect(mockProjectService.create).toHaveBeenCalled();
   });
 
-  it("accepts SSH environments on project update", async () => {
+  it("accepts sandbox environments on project update", async () => {
     mockProjectService.getById.mockResolvedValue({
       id: "project-1",
       companyId: "company-1",
-      name: "SSH Project",
+      name: "Sandboxed Project",
       status: "backlog",
       archivedAt: null,
     });
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
+      id: sandboxEnvironmentId,
       companyId: "company-1",
-      driver: "ssh",
-      config: {},
+      driver: "sandbox",
+      config: { provider: "fake-plugin" },
     });
     mockProjectService.update.mockResolvedValue({
       id: "project-1",
       companyId: "company-1",
-      name: "SSH Project",
+      name: "Sandboxed Project",
       status: "backlog",
     });
     const app = createProjectApp();
@@ -227,7 +226,7 @@ describe.sequential("execution environment route guards", () => {
       .send({
         executionWorkspacePolicy: {
           enabled: true,
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 
@@ -235,120 +234,17 @@ describe.sequential("execution environment route guards", () => {
     expect(mockProjectService.update).toHaveBeenCalled();
   });
 
-  it("rejects cross-company environments on project create", async () => {
+  it("accepts sandbox environments on issue create", async () => {
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
-      companyId: "company-2",
-      driver: "ssh",
-      config: {},
-    });
-    const app = createProjectApp();
-
-    const res = await request(app)
-      .post("/api/companies/company-1/projects")
-      .send({
-        name: "Cross Company Project",
-        executionWorkspacePolicy: {
-          enabled: true,
-          environmentId: sshEnvironmentId,
-        },
-      });
-
-    expect(res.status).toBe(422);
-    expect(res.body.error).toBe("Environment not found.");
-    expect(mockProjectService.create).not.toHaveBeenCalled();
-  });
-
-  it("rejects unsupported driver environments on project update", async () => {
-    mockProjectService.getById.mockResolvedValue({
-      id: "project-1",
+      id: sandboxEnvironmentId,
       companyId: "company-1",
-      name: "SSH Project",
-      status: "backlog",
-      archivedAt: null,
-    });
-    mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
-      companyId: "company-1",
-      driver: "unsupported_driver",
-      config: {},
-    });
-    const app = createProjectApp();
-
-    const res = await request(app)
-      .patch("/api/projects/project-1")
-      .send({
-        executionWorkspacePolicy: {
-          enabled: true,
-          environmentId: sshEnvironmentId,
-        },
-      });
-
-    expect(res.status).toBe(422);
-    expect(res.body.error).toContain('Environment driver "unsupported_driver" is not allowed here');
-    expect(mockProjectService.update).not.toHaveBeenCalled();
-  });
-
-  it("rejects archived environments on project create", async () => {
-    mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
-      companyId: "company-1",
-      driver: "ssh",
-      status: "archived",
-      config: {},
-    });
-    const app = createProjectApp();
-
-    const res = await request(app)
-      .post("/api/companies/company-1/projects")
-      .send({
-        name: "Archived Project",
-        executionWorkspacePolicy: {
-          enabled: true,
-          environmentId: sshEnvironmentId,
-        },
-      });
-
-    expect(res.status).toBe(422);
-    expect(res.body.error).toBe("Environment is archived.");
-    expect(mockProjectService.create).not.toHaveBeenCalled();
-  });
-
-  it("rejects archived environments on issue create", async () => {
-    mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
-      companyId: "company-1",
-      driver: "ssh",
-      status: "archived",
-      config: {},
-    });
-    const app = createIssueApp();
-
-    const res = await request(app)
-      .post("/api/companies/company-1/issues")
-      .send({
-        title: "Archived Issue",
-        executionWorkspaceSettings: {
-          environmentId: sshEnvironmentId,
-        },
-      });
-
-    expect(res.status).toBe(422);
-    expect(res.body.error).toBe("Environment is archived.");
-    expect(mockIssueService.create).not.toHaveBeenCalled();
-  });
-
-  it("accepts SSH environments on issue create", async () => {
-    mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
-      companyId: "company-1",
-      driver: "ssh",
-      config: {},
+      driver: "sandbox",
+      config: { provider: "fake-plugin" },
     });
     mockIssueService.create.mockResolvedValue({
       id: "issue-1",
       companyId: "company-1",
-      title: "SSH Issue",
+      title: "Sandboxed Issue",
       status: "todo",
       identifier: "PAPA-999",
     });
@@ -357,9 +253,9 @@ describe.sequential("execution environment route guards", () => {
     const res = await request(app)
       .post("/api/companies/company-1/issues")
       .send({
-        title: "SSH Issue",
+        title: "Sandboxed Issue",
         executionWorkspaceSettings: {
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 
@@ -369,7 +265,7 @@ describe.sequential("execution environment route guards", () => {
 
   it("rejects unsupported driver environments on issue create", async () => {
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
+      id: sandboxEnvironmentId,
       companyId: "company-1",
       driver: "unsupported_driver",
       config: {},
@@ -381,7 +277,7 @@ describe.sequential("execution environment route guards", () => {
       .send({
         title: "Unsupported Driver Issue",
         executionWorkspaceSettings: {
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 
@@ -390,71 +286,59 @@ describe.sequential("execution environment route guards", () => {
     expect(mockIssueService.create).not.toHaveBeenCalled();
   });
 
-  it("rejects unsupported driver environments on child issue create", async () => {
-    mockIssueService.getById.mockResolvedValue({
-      id: "parent-1",
-      companyId: "company-1",
-      status: "todo",
-      assigneeAgentId: null,
-      assigneeUserId: null,
-      createdByUserId: null,
-      identifier: "PAPA-998",
-    });
+  it("rejects built-in fake sandbox environments on issue create", async () => {
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
+      id: sandboxEnvironmentId,
       companyId: "company-1",
-      driver: "unsupported_driver",
-      config: {},
+      driver: "sandbox",
+      config: { provider: "fake" },
     });
     const app = createIssueApp();
 
     const res = await request(app)
-      .post("/api/issues/parent-1/children")
+      .post("/api/companies/company-1/issues")
       .send({
-        title: "Unsupported Child",
+        title: "Fake Sandbox Issue",
         executionWorkspaceSettings: {
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 
     expect(res.status).toBe(422);
-    expect(res.body.error).toContain('Environment driver "unsupported_driver" is not allowed here');
-    expect(mockIssueService.createChild).not.toHaveBeenCalled();
+    expect(res.body.error).toContain('Environment sandbox provider "fake" is not allowed here');
+    expect(mockIssueService.create).not.toHaveBeenCalled();
   });
 
-  it("rejects cross-company environments on child issue create", async () => {
-    mockIssueService.getById.mockResolvedValue({
-      id: "parent-1",
-      companyId: "company-1",
-      status: "todo",
-      assigneeAgentId: null,
-      assigneeUserId: null,
-      createdByUserId: null,
-      identifier: "PAPA-998",
-    });
+  it("accepts plugin-backed sandbox environments on issue create", async () => {
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
-      companyId: "company-2",
-      driver: "ssh",
-      config: {},
+      id: sandboxEnvironmentId,
+      companyId: "company-1",
+      driver: "sandbox",
+      config: { provider: "fake-plugin" },
+    });
+    mockIssueService.create.mockResolvedValue({
+      id: "issue-1",
+      companyId: "company-1",
+      title: "Plugin Sandbox Issue",
+      status: "todo",
+      identifier: "PAPA-999",
     });
     const app = createIssueApp();
 
     const res = await request(app)
-      .post("/api/issues/parent-1/children")
+      .post("/api/companies/company-1/issues")
       .send({
-        title: "Cross Company Child",
+        title: "Plugin Sandbox Issue",
         executionWorkspaceSettings: {
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 
-    expect(res.status).toBe(422);
-    expect(res.body.error).toBe("Environment not found.");
-    expect(mockIssueService.createChild).not.toHaveBeenCalled();
+    expect(res.status).not.toBe(422);
+    expect(mockIssueService.create).toHaveBeenCalled();
   });
 
-  it("accepts SSH environments on issue update", async () => {
+  it("accepts sandbox environments on issue update", async () => {
     mockIssueService.getById.mockResolvedValue({
       id: "issue-1",
       companyId: "company-1",
@@ -465,10 +349,10 @@ describe.sequential("execution environment route guards", () => {
       identifier: "PAPA-999",
     });
     mockEnvironmentService.getById.mockResolvedValue({
-      id: sshEnvironmentId,
+      id: sandboxEnvironmentId,
       companyId: "company-1",
-      driver: "ssh",
-      config: {},
+      driver: "sandbox",
+      config: { provider: "fake-plugin" },
     });
     mockIssueService.update.mockResolvedValue({
       id: "issue-1",
@@ -482,7 +366,7 @@ describe.sequential("execution environment route guards", () => {
       .patch("/api/issues/issue-1")
       .send({
         executionWorkspaceSettings: {
-          environmentId: sshEnvironmentId,
+          environmentId: sandboxEnvironmentId,
         },
       });
 

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

@@ -0,0 +1,237 @@
+import { describe, expect, it } from "vitest";
+import {
+  createEnvironmentTestHarness,
+  createFakeEnvironmentDriver,
+  filterEnvironmentEvents,
+  assertEnvironmentEventOrder,
+  assertLeaseLifecycle,
+  assertWorkspaceRealizationLifecycle,
+  assertExecutionLifecycle,
+  assertEnvironmentError,
+} from "@paperclipai/plugin-sdk/testing";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+
+const FAKE_MANIFEST: PaperclipPluginManifestV1 = {
+  id: "test-env-plugin",
+  apiVersion: 1,
+  version: "0.1.0",
+  displayName: "Test Environment Plugin",
+  description: "Test fixture",
+  author: "test",
+  categories: ["connector"],
+  capabilities: ["environment.drivers.register"],
+  entrypoints: { worker: "./worker.js" },
+  environmentDrivers: [{ driverKey: "fake", displayName: "Fake Driver" }],
+};
+
+const BASE_PARAMS = {
+  driverKey: "fake",
+  companyId: "co-1",
+  environmentId: "env-1",
+  config: {},
+};
+
+describe("environment test harness", () => {
+  it("records lifecycle events through a full acquire → realize → execute → release cycle", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    expect(lease.providerLeaseId).toBe("fake-lease-1");
+
+    await harness.realizeWorkspace({
+      ...BASE_PARAMS,
+      lease,
+      workspace: { localPath: "/tmp/test" },
+    });
+
+    const execResult = await harness.execute({
+      ...BASE_PARAMS,
+      lease,
+      command: "echo",
+      args: ["hello"],
+    });
+    expect(execResult.exitCode).toBe(0);
+    expect(execResult.stdout).toContain("echo hello");
+
+    await harness.releaseLease({
+      ...BASE_PARAMS,
+      providerLeaseId: lease.providerLeaseId,
+    });
+
+    expect(harness.environmentEvents).toHaveLength(4);
+    assertEnvironmentEventOrder(harness.environmentEvents, [
+      "acquireLease",
+      "realizeWorkspace",
+      "execute",
+      "releaseLease",
+    ]);
+  });
+
+  it("records validateConfig and probe events", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const validation = await harness.validateConfig({
+      driverKey: "fake",
+      config: { host: "test" },
+    });
+    expect(validation.ok).toBe(true);
+
+    const probe = await harness.probe(BASE_PARAMS);
+    expect(probe.ok).toBe(true);
+
+    expect(filterEnvironmentEvents(harness.environmentEvents, "validateConfig")).toHaveLength(1);
+    expect(filterEnvironmentEvents(harness.environmentEvents, "probe")).toHaveLength(1);
+  });
+
+  it("supports probe failure injection", async () => {
+    const driver = createFakeEnvironmentDriver({ probeFailure: true });
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const probe = await harness.probe(BASE_PARAMS);
+    expect(probe.ok).toBe(false);
+  });
+
+  it("supports acquire failure injection and records errors", async () => {
+    const driver = createFakeEnvironmentDriver({ acquireFailure: "No capacity" });
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    await expect(harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" })).rejects.toThrow("No capacity");
+    const errorEvent = assertEnvironmentError(harness.environmentEvents, "acquireLease");
+    expect(errorEvent.error).toBe("No capacity");
+  });
+
+  it("supports execute failure injection", async () => {
+    const driver = createFakeEnvironmentDriver({ executeFailure: true });
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    const result = await harness.execute({
+      ...BASE_PARAMS,
+      lease,
+      command: "failing-cmd",
+    });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("Simulated execution failure");
+  });
+
+  it("supports lease resume", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    const resumed = await harness.resumeLease({
+      ...BASE_PARAMS,
+      providerLeaseId: lease.providerLeaseId!,
+    });
+    expect(resumed.metadata).toHaveProperty("resumed", true);
+  });
+
+  it("resume throws for unknown lease", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    await expect(
+      harness.resumeLease({ ...BASE_PARAMS, providerLeaseId: "nonexistent" }),
+    ).rejects.toThrow("not found");
+  });
+
+  it("supports destroyLease", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    await harness.destroyLease({
+      ...BASE_PARAMS,
+      providerLeaseId: lease.providerLeaseId,
+    });
+
+    assertLeaseLifecycle(harness.environmentEvents, "env-1");
+  });
+
+  it("assertLeaseLifecycle throws when acquire is missing", () => {
+    expect(() => assertLeaseLifecycle([], "env-1")).toThrow("No acquireLease event");
+  });
+
+  it("assertWorkspaceRealizationLifecycle validates workspace between acquire and release", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    await harness.realizeWorkspace({
+      ...BASE_PARAMS,
+      lease,
+      workspace: { localPath: "/tmp/ws" },
+    });
+    await harness.releaseLease({ ...BASE_PARAMS, providerLeaseId: lease.providerLeaseId });
+
+    const realize = assertWorkspaceRealizationLifecycle(harness.environmentEvents, "env-1");
+    expect(realize.type).toBe("realizeWorkspace");
+  });
+
+  it("assertExecutionLifecycle validates execute within lease bounds", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: driver,
+    });
+
+    const lease = await harness.acquireLease({ ...BASE_PARAMS, runId: "run-1" });
+    await harness.execute({ ...BASE_PARAMS, lease, command: "ls" });
+    await harness.execute({ ...BASE_PARAMS, lease, command: "pwd" });
+    await harness.releaseLease({ ...BASE_PARAMS, providerLeaseId: lease.providerLeaseId });
+
+    const execs = assertExecutionLifecycle(harness.environmentEvents, "env-1");
+    expect(execs).toHaveLength(2);
+  });
+
+  it("throws when driver does not implement a required hook", async () => {
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      environmentDriver: { driverKey: "bare" },
+    });
+
+    await expect(harness.probe(BASE_PARAMS)).rejects.toThrow("does not implement onProbe");
+    assertEnvironmentError(harness.environmentEvents, "probe");
+  });
+
+  it("base harness methods remain functional", async () => {
+    const driver = createFakeEnvironmentDriver();
+    const harness = createEnvironmentTestHarness({
+      manifest: FAKE_MANIFEST,
+      capabilities: [...FAKE_MANIFEST.capabilities, "events.subscribe", "plugin.state.read", "plugin.state.write"],
+      environmentDriver: driver,
+    });
+
+    harness.ctx.logger.info("test");
+    expect(harness.logs).toHaveLength(1);
+  });
+});

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

@@ -1,6 +1,8 @@
 import express from "express";
 import request from "supertest";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { errorHandler } from "../middleware/index.js";
+import { executionWorkspaceRoutes } from "../routes/execution-workspaces.js";
 
 const mockExecutionWorkspaceService = vi.hoisted(() => ({
   list: vi.fn(),
@@ -15,19 +17,15 @@ const mockWorkspaceOperationService = vi.hoisted(() => ({
   createRecorder: vi.fn(),
 }));
 
-function registerServiceMocks() {
-  vi.doMock("../services/index.js", () => ({
-    executionWorkspaceService: () => mockExecutionWorkspaceService,
-    logActivity: vi.fn(async () => undefined),
-    workspaceOperationService: () => mockWorkspaceOperationService,
-  }));
-}
+const mockLogActivity = vi.hoisted(() => vi.fn(async () => undefined));
 
-async function createApp() {
-  const [{ executionWorkspaceRoutes }, { errorHandler }] = await Promise.all([
-    vi.importActual<typeof import("../routes/execution-workspaces.js")>("../routes/execution-workspaces.js"),
-    vi.importActual<typeof import("../middleware/index.js")>("../middleware/index.js"),
-  ]);
+vi.mock("../services/index.js", () => ({
+  executionWorkspaceService: () => mockExecutionWorkspaceService,
+  logActivity: mockLogActivity,
+  workspaceOperationService: () => mockWorkspaceOperationService,
+}));
+
+function createApp() {
   const app = express();
   app.use(express.json());
   app.use((req, _res, next) => {
@@ -45,15 +43,9 @@ async function createApp() {
   return app;
 }
 
-describe("execution workspace routes", () => {
+describe.sequential("execution workspace routes", () => {
   beforeEach(() => {
-    vi.resetModules();
-    vi.doUnmock("../services/index.js");
-    vi.doUnmock("../routes/execution-workspaces.js");
-    vi.doUnmock("../routes/authz.js");
-    vi.doUnmock("../middleware/index.js");
-    registerServiceMocks();
-    vi.resetAllMocks();
+    vi.clearAllMocks();
     mockExecutionWorkspaceService.list.mockResolvedValue([]);
     mockExecutionWorkspaceService.listSummaries.mockResolvedValue([
       {
@@ -66,7 +58,7 @@ describe("execution workspace routes", () => {
   });
 
   it("uses summary mode for lightweight workspace lookups", async () => {
-    const res = await request(await createApp())
+    const res = await request(createApp())
       .get("/api/companies/company-1/execution-workspaces?summary=true&reuseEligible=true");
 
     expect(res.status).toBe(200);

server/src/__tests__/express5-auth-wildcard.test.ts

@@ -1,6 +1,6 @@
 import express from "express";
 import request from "supertest";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 
 /**
  * Regression test for https://github.com/paperclipai/paperclip/issues/2898
@@ -29,33 +29,28 @@ describe("Express 5 /api/auth wildcard route", () => {
     };
   }
 
-  it("matches a shallow auth sub-path (sign-in/email)", async () => {
-    const { app } = buildApp();
-    const res = await request(app).post("/api/auth/sign-in/email");
-    expect(res.status).toBe(200);
-  });
-
-  it("matches a deep auth sub-path (callback/credentials/sign-in)", async () => {
-    const { app } = buildApp();
-    const res = await request(app).get(
-      "/api/auth/callback/credentials/sign-in"
-    );
-    expect(res.status).toBe(200);
-  });
-
-  it("does not match unrelated paths outside /api/auth", async () => {
-    // Confirm the route is not over-broad — requests to other API paths
-    // must fall through to 404 and not reach the better-auth handler.
+  it("matches auth sub-paths without matching unrelated API paths", async () => {
     const { app, getCallCount } = buildApp();
-    const res = await request(app).get("/api/other/endpoint");
-    expect(res.status).toBe(404);
-    expect(getCallCount()).toBe(0);
-  });
 
-  it("invokes the handler for every matched sub-path", async () => {
-    const { app, getCallCount } = buildApp();
-    await request(app).post("/api/auth/sign-out");
-    await request(app).get("/api/auth/session");
+    await expect(request(app).post("/api/auth/sign-in/email")).resolves.toMatchObject({
+      status: 200,
+    });
+    await expect(request(app).get("/api/auth/callback/credentials/sign-in")).resolves.toMatchObject({
+      status: 200,
+    });
     expect(getCallCount()).toBe(2);
+
+    await expect(request(app).get("/api/other/endpoint")).resolves.toMatchObject({
+      status: 404,
+    });
+    expect(getCallCount()).toBe(2);
+
+    await expect(request(app).post("/api/auth/sign-out")).resolves.toMatchObject({
+      status: 200,
+    });
+    await expect(request(app).get("/api/auth/session")).resolves.toMatchObject({
+      status: 200,
+    });
+    expect(getCallCount()).toBe(4);
   });
 });

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

@@ -1,6 +1,5 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
-import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { eq } from "drizzle-orm";
@@ -8,14 +7,12 @@ import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest
 import { writePaperclipSkillSyncPreference } from "@paperclipai/adapter-utils/server-utils";
 import {
   agents,
-  applyPendingMigrations,
   companies,
   companySkills,
   costEvents,
   createDb,
   documents,
   documentRevisions,
-  ensurePostgresDatabase,
   feedbackExports,
   feedbackVotes,
   heartbeatRuns,
@@ -25,72 +22,7 @@ import {
   issues,
 } from "@paperclipai/db";
 import { feedbackService } from "../services/feedback.ts";
-
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
-}
-
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-feedback-service-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
+import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.ts";
 
 async function closeDbClient(db: ReturnType<typeof createDb> | undefined) {
   await db?.$client?.end?.({ timeout: 0 });
@@ -99,17 +31,15 @@ async function closeDbClient(db: ReturnType<typeof createDb> | undefined) {
 describe("feedbackService.saveIssueVote", () => {
   let db!: ReturnType<typeof createDb>;
   let svc!: ReturnType<typeof feedbackService>;
-  let instance: EmbeddedPostgresInstance | null = null;
-  let dataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
   let tempDirs: string[] = [];
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
+    const started = await startEmbeddedPostgresTestDatabase("paperclip-feedback-service-");
     db = createDb(started.connectionString);
     svc = feedbackService(db);
-    instance = started.instance;
-    dataDir = started.dataDir;
-  }, 20_000);
+    tempDb = started;
+  }, 120_000);
 
   afterEach(async () => {
     await db.delete(feedbackExports);
@@ -134,10 +64,7 @@ describe("feedbackService.saveIssueVote", () => {
 
   afterAll(async () => {
     await closeDbClient(db);
-    await instance?.stop();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
+    await tempDb?.cleanup();
   });
 
   async function seedIssueWithAgentComment() {

server/src/__tests__/heartbeat-active-run-output-watchdog.test.ts

@@ -0,0 +1,549 @@
+import { randomUUID } from "node:crypto";
+import { and, eq, sql } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  agents,
+  companies,
+  createDb,
+  heartbeatRunWatchdogDecisions,
+  heartbeatRuns,
+  issueRelations,
+  issues,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import {
+  ACTIVE_RUN_OUTPUT_CONTINUE_REARM_MS,
+  ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS,
+  ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS,
+  heartbeatService,
+} from "../services/heartbeat.ts";
+import { recoveryService } from "../services/recovery/service.ts";
+import { getRunLogStore } from "../services/run-log-store.ts";
+
+const mockAdapterExecute = vi.hoisted(() =>
+  vi.fn(async () => ({
+    exitCode: 0,
+    signal: null,
+    timedOut: false,
+    errorMessage: null,
+    summary: "Acknowledged stale-run evaluation.",
+    provider: "test",
+    model: "test-model",
+  })),
+);
+
+vi.mock("../telemetry.ts", () => ({
+  getTelemetryClient: () => ({ track: vi.fn() }),
+}));
+
+vi.mock("@paperclipai/shared/telemetry", async () => {
+  const actual = await vi.importActual<typeof import("@paperclipai/shared/telemetry")>(
+    "@paperclipai/shared/telemetry",
+  );
+  return {
+    ...actual,
+    trackAgentFirstHeartbeat: vi.fn(),
+  };
+});
+
+vi.mock("../adapters/index.ts", async () => {
+  const actual = await vi.importActual<typeof import("../adapters/index.ts")>("../adapters/index.ts");
+  return {
+    ...actual,
+    getServerAdapter: vi.fn(() => ({
+      supportsLocalAgentJwt: false,
+      execute: mockAdapterExecute,
+    })),
+  };
+});
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres active-run output watchdog tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("active-run output watchdog", () => {
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+  let db: ReturnType<typeof createDb>;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-active-run-output-watchdog-");
+    db = createDb(tempDb.connectionString);
+  }, 30_000);
+
+  afterEach(async () => {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      const activeRuns = await db
+        .select({ id: heartbeatRuns.id })
+        .from(heartbeatRuns)
+        .where(sql`${heartbeatRuns.status} in ('queued', 'running')`);
+      if (activeRuns.length === 0) break;
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    await db.execute(sql.raw(`TRUNCATE TABLE "companies" CASCADE`));
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seedRunningRun(opts: { now: Date; ageMs: number; withOutput?: boolean; logChunk?: string }) {
+    const companyId = randomUUID();
+    const managerId = randomUUID();
+    const coderId = randomUUID();
+    const issueId = randomUUID();
+    const runId = randomUUID();
+    const issuePrefix = `W${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+    const startedAt = new Date(opts.now.getTime() - opts.ageMs);
+    const lastOutputAt = opts.withOutput ? new Date(opts.now.getTime() - 5 * 60 * 1000) : null;
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Watchdog Co",
+      issuePrefix,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(agents).values([
+      {
+        id: managerId,
+        companyId,
+        name: "CTO",
+        role: "cto",
+        status: "idle",
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+      {
+        id: coderId,
+        companyId,
+        name: "Coder",
+        role: "engineer",
+        status: "running",
+        reportsTo: managerId,
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+    ]);
+    await db.insert(issues).values({
+      id: issueId,
+      companyId,
+      title: "Long running implementation",
+      status: "in_progress",
+      priority: "medium",
+      assigneeAgentId: coderId,
+      issueNumber: 1,
+      identifier: `${issuePrefix}-1`,
+      updatedAt: startedAt,
+      createdAt: startedAt,
+    });
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId: coderId,
+      status: "running",
+      invocationSource: "assignment",
+      triggerDetail: "system",
+      startedAt,
+      processStartedAt: startedAt,
+      lastOutputAt,
+      lastOutputSeq: opts.withOutput ? 3 : 0,
+      lastOutputStream: opts.withOutput ? "stdout" : null,
+      contextSnapshot: { issueId },
+      stdoutExcerpt: "OPENAI_API_KEY=sk-test-secret-value should not leak",
+      logBytes: 0,
+    });
+    if (opts.logChunk) {
+      const store = getRunLogStore();
+      const handle = await store.begin({ companyId, agentId: coderId, runId });
+      const logBytes = await store.append(handle, {
+        stream: "stdout",
+        chunk: opts.logChunk,
+        ts: startedAt.toISOString(),
+      });
+      await db
+        .update(heartbeatRuns)
+        .set({
+          logStore: handle.store,
+          logRef: handle.logRef,
+          logBytes,
+        })
+        .where(eq(heartbeatRuns.id, runId));
+    }
+    await db.update(issues).set({ executionRunId: runId }).where(eq(issues.id, issueId));
+    return { companyId, managerId, coderId, issueId, runId, issuePrefix };
+  }
+
+  it("creates one medium-priority evaluation issue for a suspicious silent run", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const { companyId, managerId, runId } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS + 60_000,
+    });
+    const heartbeat = heartbeatService(db);
+
+    const first = await heartbeat.scanSilentActiveRuns({ now, companyId });
+    const second = await heartbeat.scanSilentActiveRuns({ now, companyId });
+
+    expect(first.created).toBe(1);
+    expect(second.created).toBe(0);
+    expect(second.existing).toBe(1);
+
+    const evaluations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "stale_active_run_evaluation")));
+    expect(evaluations).toHaveLength(1);
+    expect(["todo", "in_progress"]).toContain(evaluations[0]?.status);
+    expect(evaluations[0]).toMatchObject({
+      priority: "medium",
+      assigneeAgentId: managerId,
+      originId: runId,
+      originFingerprint: `stale_active_run:${companyId}:${runId}`,
+    });
+    expect(evaluations[0]?.description).toContain("Decision Checklist");
+    expect(evaluations[0]?.description).not.toContain("sk-test-secret-value");
+  });
+
+  it("redacts sensitive values from actual run-log evidence", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const leakedJwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+    const leakedGithubToken = "ghp_1234567890abcdefghijklmnopqrstuvwxyz";
+    const { companyId } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS + 60_000,
+      logChunk: [
+        "Authorization: Bearer live-bearer-token-value",
+        `POST payload {"apiKey":"json-secret-value","token":"${leakedJwt}"}`,
+        `GITHUB_TOKEN=${leakedGithubToken}`,
+      ].join("\n"),
+    });
+    const heartbeat = heartbeatService(db);
+
+    await heartbeat.scanSilentActiveRuns({ now, companyId });
+
+    const [evaluation] = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "stale_active_run_evaluation")));
+    expect(evaluation?.description).toContain("***REDACTED***");
+    expect(evaluation?.description).not.toContain("live-bearer-token-value");
+    expect(evaluation?.description).not.toContain("json-secret-value");
+    expect(evaluation?.description).not.toContain(leakedJwt);
+    expect(evaluation?.description).not.toContain(leakedGithubToken);
+  });
+
+  it("raises critical stale-run evaluations and blocks the source issue", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const { companyId, issueId } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS + 60_000,
+    });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.scanSilentActiveRuns({ now, companyId });
+
+    expect(result.created).toBe(1);
+    const [evaluation] = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "stale_active_run_evaluation")));
+    expect(evaluation?.priority).toBe("high");
+
+    const [blocker] = await db
+      .select()
+      .from(issueRelations)
+      .where(and(eq(issueRelations.companyId, companyId), eq(issueRelations.relatedIssueId, issueId)));
+    expect(blocker?.issueId).toBe(evaluation?.id);
+
+    const [source] = await db.select().from(issues).where(eq(issues.id, issueId));
+    expect(source?.status).toBe("blocked");
+  });
+
+  it("skips snoozed runs and healthy noisy runs", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const stale = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS + 60_000,
+    });
+    const noisy = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_CRITICAL_THRESHOLD_MS + 60_000,
+      withOutput: true,
+    });
+    await db.insert(heartbeatRunWatchdogDecisions).values({
+      companyId: stale.companyId,
+      runId: stale.runId,
+      decision: "snooze",
+      snoozedUntil: new Date(now.getTime() + 60 * 60 * 1000),
+      reason: "Intentional quiet run",
+    });
+    const heartbeat = heartbeatService(db);
+
+    const staleResult = await heartbeat.scanSilentActiveRuns({ now, companyId: stale.companyId });
+    const noisyResult = await heartbeat.scanSilentActiveRuns({ now, companyId: noisy.companyId });
+
+    expect(staleResult).toMatchObject({ created: 0, snoozed: 1 });
+    expect(noisyResult).toMatchObject({ scanned: 0, created: 0 });
+  });
+
+  it("records watchdog decisions through recovery owner authorization", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const { companyId, managerId, runId } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS + 60_000,
+    });
+    const heartbeat = heartbeatService(db);
+    const recovery = recoveryService(db, { enqueueWakeup: vi.fn() });
+
+    const scan = await heartbeat.scanSilentActiveRuns({ now, companyId });
+    const evaluationIssueId = scan.evaluationIssueIds[0];
+    expect(evaluationIssueId).toBeTruthy();
+
+    await expect(
+      recovery.recordWatchdogDecision({
+        runId,
+        actor: { type: "agent", agentId: randomUUID() },
+        decision: "continue",
+        evaluationIssueId,
+        reason: "not my recovery issue",
+      }),
+    ).rejects.toMatchObject({ status: 403 });
+
+    const snoozedUntil = new Date(now.getTime() + 60 * 60 * 1000);
+    const decision = await recovery.recordWatchdogDecision({
+      runId,
+      actor: { type: "agent", agentId: managerId },
+      decision: "snooze",
+      evaluationIssueId,
+      reason: "Long compile with no output",
+      snoozedUntil,
+    });
+
+    expect(decision).toMatchObject({
+      runId,
+      evaluationIssueId,
+      decision: "snooze",
+      createdByAgentId: managerId,
+    });
+    await expect(recovery.buildRunOutputSilence({
+      id: runId,
+      companyId,
+      status: "running",
+      lastOutputAt: null,
+      lastOutputSeq: 0,
+      lastOutputStream: null,
+      processStartedAt: new Date(now.getTime() - ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS - 60_000),
+      startedAt: new Date(now.getTime() - ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS - 60_000),
+      createdAt: new Date(now.getTime() - ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS - 60_000),
+    }, now)).resolves.toMatchObject({
+      level: "snoozed",
+      snoozedUntil,
+      evaluationIssueId,
+    });
+  });
+
+  it("re-arms continue decisions after the default quiet window", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const { companyId, managerId, runId } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS + 60_000,
+    });
+    const heartbeat = heartbeatService(db);
+    const recovery = recoveryService(db, { enqueueWakeup: vi.fn() });
+
+    const scan = await heartbeat.scanSilentActiveRuns({ now, companyId });
+    const evaluationIssueId = scan.evaluationIssueIds[0];
+    expect(evaluationIssueId).toBeTruthy();
+
+    const decision = await recovery.recordWatchdogDecision({
+      runId,
+      actor: { type: "agent", agentId: managerId },
+      decision: "continue",
+      evaluationIssueId,
+      reason: "Current evidence is acceptable; keep watching.",
+      now,
+    });
+    const rearmAt = new Date(now.getTime() + ACTIVE_RUN_OUTPUT_CONTINUE_REARM_MS);
+    expect(decision).toMatchObject({
+      runId,
+      evaluationIssueId,
+      decision: "continue",
+      createdByAgentId: managerId,
+    });
+    expect(decision.snoozedUntil?.toISOString()).toBe(rearmAt.toISOString());
+
+    await db.update(issues).set({ status: "done" }).where(eq(issues.id, evaluationIssueId));
+
+    const beforeRearm = await heartbeat.scanSilentActiveRuns({
+      now: new Date(rearmAt.getTime() - 60_000),
+      companyId,
+    });
+    expect(beforeRearm).toMatchObject({ created: 0, snoozed: 1 });
+
+    const afterRearm = await heartbeat.scanSilentActiveRuns({
+      now: new Date(rearmAt.getTime() + 60_000),
+      companyId,
+    });
+    expect(afterRearm.created).toBe(1);
+    expect(afterRearm.evaluationIssueIds[0]).not.toBe(evaluationIssueId);
+
+    const evaluations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "stale_active_run_evaluation")));
+    expect(evaluations.filter((issue) => !["done", "cancelled"].includes(issue.status))).toHaveLength(1);
+  });
+
+  it("rejects agent watchdog decisions using issues not bound to the target run", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const { companyId, managerId, coderId, runId, issuePrefix } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS + 60_000,
+    });
+    const heartbeat = heartbeatService(db);
+    const recovery = recoveryService(db, { enqueueWakeup: vi.fn() });
+
+    const scan = await heartbeat.scanSilentActiveRuns({ now, companyId });
+    const evaluationIssueId = scan.evaluationIssueIds[0];
+    expect(evaluationIssueId).toBeTruthy();
+
+    const unrelatedIssueId = randomUUID();
+    await db.insert(issues).values({
+      id: unrelatedIssueId,
+      companyId,
+      title: "Assigned but unrelated",
+      status: "todo",
+      priority: "medium",
+      assigneeAgentId: managerId,
+      issueNumber: 20,
+      identifier: `${issuePrefix}-20`,
+    });
+
+    const otherRunId = randomUUID();
+    const otherEvaluationIssueId = randomUUID();
+    await db.insert(heartbeatRuns).values({
+      id: otherRunId,
+      companyId,
+      agentId: coderId,
+      status: "running",
+      invocationSource: "assignment",
+      triggerDetail: "system",
+      startedAt: new Date(now.getTime() - ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS - 120_000),
+      processStartedAt: new Date(now.getTime() - ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS - 120_000),
+      lastOutputAt: null,
+      lastOutputSeq: 0,
+      lastOutputStream: null,
+      contextSnapshot: {},
+      logBytes: 0,
+    });
+    await db.insert(issues).values({
+      id: otherEvaluationIssueId,
+      companyId,
+      title: "Other run evaluation",
+      status: "todo",
+      priority: "medium",
+      assigneeAgentId: managerId,
+      issueNumber: 21,
+      identifier: `${issuePrefix}-21`,
+      originKind: "stale_active_run_evaluation",
+      originId: otherRunId,
+      originFingerprint: `stale_active_run:${companyId}:${otherRunId}`,
+    });
+
+    const attempts = [
+      { decision: "continue" as const, evaluationIssueId: unrelatedIssueId },
+      { decision: "dismissed_false_positive" as const, evaluationIssueId: unrelatedIssueId },
+      {
+        decision: "snooze" as const,
+        evaluationIssueId: unrelatedIssueId,
+        snoozedUntil: new Date(now.getTime() + 60 * 60 * 1000),
+      },
+      { decision: "continue" as const, evaluationIssueId: otherEvaluationIssueId },
+    ];
+
+    for (const attempt of attempts) {
+      await expect(
+        recovery.recordWatchdogDecision({
+          runId,
+          actor: { type: "agent", agentId: managerId },
+          reason: "malicious or stale binding",
+          ...attempt,
+        }),
+      ).rejects.toMatchObject({ status: 403 });
+    }
+
+    await db.update(issues).set({ status: "done" }).where(eq(issues.id, evaluationIssueId));
+    await expect(
+      recovery.recordWatchdogDecision({
+        runId,
+        actor: { type: "agent", agentId: managerId },
+        decision: "continue",
+        evaluationIssueId,
+        reason: "closed evaluation should not authorize",
+      }),
+    ).rejects.toMatchObject({ status: 403 });
+  });
+
+  it("validates createdByRunId before storing watchdog decisions", async () => {
+    const now = new Date("2026-04-22T20:00:00.000Z");
+    const { companyId, managerId, runId } = await seedRunningRun({
+      now,
+      ageMs: ACTIVE_RUN_OUTPUT_SUSPICION_THRESHOLD_MS + 60_000,
+    });
+    const heartbeat = heartbeatService(db);
+    const recovery = recoveryService(db, { enqueueWakeup: vi.fn() });
+
+    const scan = await heartbeat.scanSilentActiveRuns({ now, companyId });
+    const evaluationIssueId = scan.evaluationIssueIds[0];
+    expect(evaluationIssueId).toBeTruthy();
+
+    await expect(
+      recovery.recordWatchdogDecision({
+        runId,
+        actor: { type: "agent", agentId: managerId },
+        decision: "continue",
+        evaluationIssueId,
+        reason: "client supplied another agent run",
+        createdByRunId: runId,
+      }),
+    ).rejects.toMatchObject({ status: 403 });
+
+    const managerRunId = randomUUID();
+    await db.insert(heartbeatRuns).values({
+      id: managerRunId,
+      companyId,
+      agentId: managerId,
+      status: "running",
+      invocationSource: "assignment",
+      triggerDetail: "system",
+      startedAt: now,
+      processStartedAt: now,
+      lastOutputAt: now,
+      lastOutputSeq: 1,
+      lastOutputStream: "stdout",
+      contextSnapshot: {},
+      logBytes: 0,
+    });
+
+    const decision = await recovery.recordWatchdogDecision({
+      runId,
+      actor: { type: "agent", agentId: managerId, runId: managerRunId },
+      decision: "continue",
+      evaluationIssueId,
+      reason: "valid current actor run",
+      createdByRunId: randomUUID(),
+    });
+    expect(decision.createdByRunId).toBe(managerRunId);
+  });
+});

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

@@ -1,8 +1,4 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { createServer } from "node:http";
 import { and, asc, eq } from "drizzle-orm";
 import { WebSocketServer } from "ws";
@@ -10,81 +6,14 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import {
   agents,
   agentWakeupRequests,
-  applyPendingMigrations,
   companies,
   createDb,
-  ensurePostgresDatabase,
   heartbeatRuns,
   issueComments,
   issues,
 } from "@paperclipai/db";
 import { heartbeatService } from "../services/heartbeat.ts";
-
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
-}
-
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-heartbeat-comment-wake-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, instance, dataDir };
-}
+import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.ts";
 
 async function waitFor(condition: () => boolean | Promise<boolean>, timeoutMs = 10_000, intervalMs = 50) {
   const startedAt = Date.now();
@@ -218,22 +147,17 @@ async function createControlledGatewayServer() {
 
 describe("heartbeat comment wake batching", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
-  let dataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
+    const started = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-comment-wake-");
     db = createDb(started.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
-  }, 45_000);
+    tempDb = started;
+  }, 120_000);
 
   afterAll(async () => {
     await closeDbClient(db);
-    await instance?.stop();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
+    await tempDb?.cleanup();
   });
 
   it("defers approval-approved wakes for a running issue so the assignee resumes after the run", async () => {
@@ -862,6 +786,206 @@ describe("heartbeat comment wake batching", () => {
     }
   }, 120_000);
 
+  it("does not reopen a finished issue when the deferred comment wake came from another agent", async () => {
+    const gateway = await createControlledGatewayServer();
+    const companyId = randomUUID();
+    const assigneeAgentId = randomUUID();
+    const mentionedAgentId = randomUUID();
+    const issueId = randomUUID();
+    const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+    const heartbeat = heartbeatService(db);
+
+    try {
+      await db.insert(companies).values({
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix,
+        requireBoardApprovalForNewAgents: false,
+      });
+
+      await db.insert(agents).values([
+        {
+          id: assigneeAgentId,
+          companyId,
+          name: "Primary Agent",
+          role: "engineer",
+          status: "idle",
+          adapterType: "openclaw_gateway",
+          adapterConfig: {
+            url: gateway.url,
+            headers: {
+              "x-openclaw-token": "gateway-token",
+            },
+            payloadTemplate: {
+              message: "wake now",
+            },
+            waitTimeoutMs: 2_000,
+          },
+          runtimeConfig: {},
+          permissions: {},
+        },
+        {
+          id: mentionedAgentId,
+          companyId,
+          name: "Mentioned Agent",
+          role: "engineer",
+          status: "idle",
+          adapterType: "openclaw_gateway",
+          adapterConfig: {
+            url: gateway.url,
+            headers: {
+              "x-openclaw-token": "gateway-token",
+            },
+            payloadTemplate: {
+              message: "wake now",
+            },
+            waitTimeoutMs: 2_000,
+          },
+          runtimeConfig: {},
+          permissions: {},
+        },
+      ]);
+
+      await db.insert(issues).values({
+        id: issueId,
+        companyId,
+        title: "Do not reopen from agent mention",
+        status: "todo",
+        priority: "medium",
+        assigneeAgentId,
+        issueNumber: 1,
+        identifier: `${issuePrefix}-1`,
+      });
+
+      const firstRun = await heartbeat.wakeup(assigneeAgentId, {
+        source: "assignment",
+        triggerDetail: "system",
+        reason: "issue_assigned",
+        payload: { issueId },
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          wakeReason: "issue_assigned",
+        },
+        requestedByActorType: "system",
+        requestedByActorId: null,
+      });
+
+      expect(firstRun).not.toBeNull();
+      await waitFor(async () => {
+        const run = await db
+          .select({ status: heartbeatRuns.status })
+          .from(heartbeatRuns)
+          .where(eq(heartbeatRuns.id, firstRun!.id))
+          .then((rows) => rows[0] ?? null);
+        return run?.status === "running";
+      });
+
+      const comment = await db
+        .insert(issueComments)
+        .values({
+          companyId,
+          issueId,
+          authorAgentId: assigneeAgentId,
+          createdByRunId: firstRun?.id ?? null,
+          body: "@Mentioned Agent please review after I finish",
+        })
+        .returning()
+        .then((rows) => rows[0]);
+
+      const deferredRun = await heartbeat.wakeup(mentionedAgentId, {
+        source: "automation",
+        triggerDetail: "system",
+        reason: "issue_comment_mentioned",
+        payload: { issueId, commentId: comment.id },
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          commentId: comment.id,
+          wakeCommentId: comment.id,
+          wakeReason: "issue_comment_mentioned",
+          source: "comment.mention",
+        },
+        requestedByActorType: "agent",
+        requestedByActorId: assigneeAgentId,
+      });
+
+      expect(deferredRun).toBeNull();
+
+      await waitFor(async () => {
+        const deferred = await db
+          .select()
+          .from(agentWakeupRequests)
+          .where(
+            and(
+              eq(agentWakeupRequests.companyId, companyId),
+              eq(agentWakeupRequests.agentId, mentionedAgentId),
+              eq(agentWakeupRequests.status, "deferred_issue_execution"),
+            ),
+          )
+          .then((rows) => rows[0] ?? null);
+        return Boolean(deferred);
+      });
+
+      await db
+        .update(issues)
+        .set({
+          status: "done",
+          completedAt: new Date(),
+          executionRunId: null,
+          executionAgentNameKey: null,
+          executionLockedAt: null,
+          updatedAt: new Date(),
+        })
+        .where(eq(issues.id, issueId));
+
+      gateway.releaseFirstWait();
+
+      await waitFor(() => gateway.getAgentPayloads().length === 2, 90_000);
+      await waitFor(async () => {
+        const runs = await db
+          .select()
+          .from(heartbeatRuns)
+          .where(eq(heartbeatRuns.companyId, companyId));
+        return runs.length === 2 && runs.every((run) => run.status === "succeeded");
+      }, 90_000);
+
+      const issueAfterPromotion = await db
+        .select({
+          status: issues.status,
+          completedAt: issues.completedAt,
+        })
+        .from(issues)
+        .where(eq(issues.id, issueId))
+        .then((rows) => rows[0] ?? null);
+
+      expect(issueAfterPromotion).toMatchObject({
+        status: "done",
+      });
+      expect(issueAfterPromotion?.completedAt).not.toBeNull();
+
+      const secondPayload = gateway.getAgentPayloads()[1] ?? {};
+      expect(secondPayload.paperclip).toMatchObject({
+        wake: {
+          reason: "issue_comment_mentioned",
+          commentIds: [comment.id],
+          latestCommentId: comment.id,
+          issue: {
+            id: issueId,
+            identifier: `${issuePrefix}-1`,
+            title: "Do not reopen from agent mention",
+            status: "done",
+            priority: "medium",
+          },
+        },
+      });
+      expect(String(secondPayload.message ?? "")).toContain("please review after I finish");
+    } finally {
+      gateway.releaseFirstWait();
+      await gateway.close();
+    }
+  }, 120_000);
+
   it("queues exactly one follow-up run when an issue-bound run exits without a comment", async () => {
     const gateway = await createControlledGatewayServer();
     const companyId = randomUUID();
@@ -1172,6 +1296,20 @@ describe("heartbeat comment wake batching", () => {
         wakeReason: "issue_comment_mentioned",
       });
 
+      const issueAfterMention = await db
+        .select({
+          assigneeAgentId: issues.assigneeAgentId,
+          executionRunId: issues.executionRunId,
+          executionAgentNameKey: issues.executionAgentNameKey,
+        })
+        .from(issues)
+        .where(eq(issues.id, issueId))
+        .then((rows) => rows[0] ?? null);
+
+      expect(issueAfterMention?.assigneeAgentId).toBe(primaryAgentId);
+      expect(issueAfterMention?.executionRunId).not.toBe(mentionedRuns[0]?.id);
+      expect(issueAfterMention?.executionAgentNameKey).not.toBe("mentioned agent");
+
       const primaryRuns = await db
         .select()
         .from(heartbeatRuns)
@@ -1198,6 +1336,155 @@ describe("heartbeat comment wake batching", () => {
       await gateway.close();
     }
   }, 120_000);
+
+  it("does not mark a direct mentioned-agent run as the issue execution owner", async () => {
+    const gateway = await createControlledGatewayServer();
+    const companyId = randomUUID();
+    const primaryAgentId = randomUUID();
+    const mentionedAgentId = randomUUID();
+    const issueId = randomUUID();
+    const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+    const heartbeat = heartbeatService(db);
+
+    try {
+      await db.insert(companies).values({
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix,
+        requireBoardApprovalForNewAgents: false,
+      });
+
+      await db.insert(agents).values([
+        {
+          id: primaryAgentId,
+          companyId,
+          name: "Primary Agent",
+          role: "engineer",
+          status: "idle",
+          adapterType: "openclaw_gateway",
+          adapterConfig: {
+            url: gateway.url,
+            headers: {
+              "x-openclaw-token": "gateway-token",
+            },
+            payloadTemplate: {
+              message: "wake now",
+            },
+            waitTimeoutMs: 2_000,
+          },
+          runtimeConfig: {},
+          permissions: {},
+        },
+        {
+          id: mentionedAgentId,
+          companyId,
+          name: "Mentioned Agent",
+          role: "engineer",
+          status: "idle",
+          adapterType: "openclaw_gateway",
+          adapterConfig: {
+            url: gateway.url,
+            headers: {
+              "x-openclaw-token": "gateway-token",
+            },
+            payloadTemplate: {
+              message: "wake now",
+            },
+            waitTimeoutMs: 2_000,
+          },
+          runtimeConfig: {},
+          permissions: {},
+        },
+      ]);
+
+      await db.insert(issues).values({
+        id: issueId,
+        companyId,
+        title: "Mention should not steal execution ownership",
+        status: "todo",
+        priority: "medium",
+        assigneeAgentId: primaryAgentId,
+        issueNumber: 1,
+        identifier: `${issuePrefix}-1`,
+      });
+
+      const mentionComment = await db
+        .insert(issueComments)
+        .values({
+          companyId,
+          issueId,
+          authorUserId: "user-1",
+          body: "@Mentioned Agent please inspect this.",
+        })
+        .returning()
+        .then((rows) => rows[0]);
+
+      const mentionRun = await heartbeat.wakeup(mentionedAgentId, {
+        source: "automation",
+        triggerDetail: "system",
+        reason: "issue_comment_mentioned",
+        payload: { issueId, commentId: mentionComment.id },
+        contextSnapshot: {
+          issueId,
+          taskId: issueId,
+          commentId: mentionComment.id,
+          wakeCommentId: mentionComment.id,
+          wakeReason: "issue_comment_mentioned",
+          source: "comment.mention",
+        },
+        requestedByActorType: "user",
+        requestedByActorId: "user-1",
+      });
+
+      expect(mentionRun).not.toBeNull();
+      await waitFor(() => gateway.getAgentPayloads().length === 1);
+
+      const issueDuringMention = await db
+        .select({
+          assigneeAgentId: issues.assigneeAgentId,
+          executionRunId: issues.executionRunId,
+          executionAgentNameKey: issues.executionAgentNameKey,
+        })
+        .from(issues)
+        .where(eq(issues.id, issueId))
+        .then((rows) => rows[0] ?? null);
+
+      expect(issueDuringMention).toMatchObject({
+        assigneeAgentId: primaryAgentId,
+        executionRunId: null,
+        executionAgentNameKey: null,
+      });
+
+      gateway.releaseFirstWait();
+      await waitFor(async () => {
+        const run = await db
+          .select({ status: heartbeatRuns.status })
+          .from(heartbeatRuns)
+          .where(eq(heartbeatRuns.id, mentionRun!.id))
+          .then((rows) => rows[0] ?? null);
+        return run?.status === "succeeded";
+      }, 90_000);
+
+      const issueAfterMention = await db
+        .select({
+          assigneeAgentId: issues.assigneeAgentId,
+          executionRunId: issues.executionRunId,
+          executionAgentNameKey: issues.executionAgentNameKey,
+        })
+        .from(issues)
+        .where(eq(issues.id, issueId))
+        .then((rows) => rows[0] ?? null);
+
+      expect(issueAfterMention).toMatchObject({
+        assigneeAgentId: primaryAgentId,
+        executionRunId: null,
+        executionAgentNameKey: null,
+      });
+    } finally {
+      gateway.releaseFirstWait();
+      await gateway.close();
+    }
+  }, 120_000);
   it("treats the automatic run summary as fallback-only when the run already posted a comment", async () => {
     const gateway = await createControlledGatewayServer();
     const companyId = randomUUID();

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

@@ -123,6 +123,7 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () =
     await db.delete(issueTreeHolds);
     await db.delete(issues);
     await db.delete(heartbeatRunEvents);
+    await db.delete(activityLog);
     await db.delete(heartbeatRuns);
     await db.delete(agentWakeupRequests);
     await db.delete(agentRuntimeState);
@@ -346,6 +347,198 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () =
     expect(blockedWakeRequestCount).toBeGreaterThanOrEqual(2);
   });
 
+  it("cancels stale queued runs when issue blockers are still unresolved", async () => {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const blockerId = randomUUID();
+    const blockedIssueId = randomUUID();
+    const readyIssueId = randomUUID();
+    const blockedWakeupRequestId = randomUUID();
+    const readyWakeupRequestId = randomUUID();
+    const blockedRunId = randomUUID();
+    const readyRunId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "QAChecker",
+      role: "qa",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {
+        heartbeat: {
+          wakeOnDemand: true,
+          maxConcurrentRuns: 2,
+        },
+      },
+      permissions: {},
+    });
+    await db.insert(issues).values([
+      {
+        id: blockerId,
+        companyId,
+        title: "Security review",
+        status: "blocked",
+        priority: "high",
+      },
+      {
+        id: blockedIssueId,
+        companyId,
+        title: "QA validation",
+        status: "blocked",
+        priority: "medium",
+        assigneeAgentId: agentId,
+      },
+      {
+        id: readyIssueId,
+        companyId,
+        title: "Ready QA task",
+        status: "todo",
+        priority: "low",
+        assigneeAgentId: agentId,
+      },
+    ]);
+    await db.insert(issueRelations).values({
+      companyId,
+      issueId: blockerId,
+      relatedIssueId: blockedIssueId,
+      type: "blocks",
+    });
+    await db.insert(agentWakeupRequests).values([
+      {
+        id: blockedWakeupRequestId,
+        companyId,
+        agentId,
+        source: "automation",
+        triggerDetail: "system",
+        reason: "transient_failure_retry",
+        payload: { issueId: blockedIssueId },
+        status: "queued",
+      },
+      {
+        id: readyWakeupRequestId,
+        companyId,
+        agentId,
+        source: "assignment",
+        triggerDetail: "system",
+        reason: "issue_assigned",
+        payload: { issueId: readyIssueId },
+        status: "queued",
+      },
+    ]);
+    await db.insert(heartbeatRuns).values([
+      {
+        id: blockedRunId,
+        companyId,
+        agentId,
+        invocationSource: "automation",
+        triggerDetail: "system",
+        status: "queued",
+        wakeupRequestId: blockedWakeupRequestId,
+        contextSnapshot: {
+          issueId: blockedIssueId,
+          wakeReason: "transient_failure_retry",
+        },
+      },
+      {
+        id: readyRunId,
+        companyId,
+        agentId,
+        invocationSource: "assignment",
+        triggerDetail: "system",
+        status: "queued",
+        wakeupRequestId: readyWakeupRequestId,
+        contextSnapshot: {
+          issueId: readyIssueId,
+          wakeReason: "issue_assigned",
+        },
+      },
+    ]);
+    await db
+      .update(agentWakeupRequests)
+      .set({ runId: blockedRunId })
+      .where(eq(agentWakeupRequests.id, blockedWakeupRequestId));
+    await db
+      .update(agentWakeupRequests)
+      .set({ runId: readyRunId })
+      .where(eq(agentWakeupRequests.id, readyWakeupRequestId));
+    await db
+      .update(issues)
+      .set({
+        executionRunId: blockedRunId,
+        executionAgentNameKey: "qa-checker",
+        executionLockedAt: new Date(),
+      })
+      .where(eq(issues.id, blockedIssueId));
+
+    await heartbeat.resumeQueuedRuns();
+
+    await waitForCondition(async () => {
+      const run = await db
+        .select({ status: heartbeatRuns.status })
+        .from(heartbeatRuns)
+        .where(eq(heartbeatRuns.id, readyRunId))
+        .then((rows) => rows[0] ?? null);
+      return run?.status === "succeeded";
+    });
+
+    const [blockedRun, blockedWakeup, blockedIssue, readyRun] = await Promise.all([
+      db
+        .select({
+          status: heartbeatRuns.status,
+          errorCode: heartbeatRuns.errorCode,
+          finishedAt: heartbeatRuns.finishedAt,
+          resultJson: heartbeatRuns.resultJson,
+        })
+        .from(heartbeatRuns)
+        .where(eq(heartbeatRuns.id, blockedRunId))
+        .then((rows) => rows[0] ?? null),
+      db
+        .select({
+          status: agentWakeupRequests.status,
+          error: agentWakeupRequests.error,
+        })
+        .from(agentWakeupRequests)
+        .where(eq(agentWakeupRequests.id, blockedWakeupRequestId))
+        .then((rows) => rows[0] ?? null),
+      db
+        .select({
+          executionRunId: issues.executionRunId,
+          executionAgentNameKey: issues.executionAgentNameKey,
+          executionLockedAt: issues.executionLockedAt,
+        })
+        .from(issues)
+        .where(eq(issues.id, blockedIssueId))
+        .then((rows) => rows[0] ?? null),
+      db
+        .select({ status: heartbeatRuns.status })
+        .from(heartbeatRuns)
+        .where(eq(heartbeatRuns.id, readyRunId))
+        .then((rows) => rows[0] ?? null),
+    ]);
+
+    expect(blockedRun?.status).toBe("cancelled");
+    expect(blockedRun?.errorCode).toBe("issue_dependencies_blocked");
+    expect(blockedRun?.finishedAt).toBeTruthy();
+    expect(blockedRun?.resultJson).toMatchObject({ stopReason: "issue_dependencies_blocked" });
+    expect(blockedWakeup?.status).toBe("skipped");
+    expect(blockedWakeup?.error).toContain("dependencies are still blocked");
+    expect(blockedIssue).toMatchObject({
+      executionRunId: null,
+      executionAgentNameKey: null,
+      executionLockedAt: null,
+    });
+    expect(readyRun?.status).toBe("succeeded");
+    expect(mockAdapterExecute).toHaveBeenCalledTimes(1);
+  });
+
   it("suppresses normal wakeups while allowing comment interaction wakes under a pause hold", async () => {
     const companyId = randomUUID();
     const agentId = randomUUID();
@@ -424,12 +617,39 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () =
       .then((rows) => rows[0] ?? null);
     expect(skippedWake).toMatchObject({ status: "skipped", reason: "issue_tree_hold_active" });
 
+    const childCommentId = randomUUID();
+    await db.insert(issueComments).values({
+      id: childCommentId,
+      companyId,
+      issueId: childIssueId,
+      authorUserId: "board-user",
+      body: "Please respond while this hold is active.",
+    });
+
+    const forgedChildCommentWake = await heartbeat.wakeup(agentId, {
+      source: "on_demand",
+      triggerDetail: "manual",
+      reason: "issue_commented",
+      payload: { issueId: childIssueId, commentId: childCommentId },
+      requestedByActorType: "agent",
+      requestedByActorId: agentId,
+    });
+    expect(forgedChildCommentWake).toBeNull();
+
     const childCommentWake = await heartbeat.wakeup(agentId, {
       source: "automation",
       triggerDetail: "system",
       reason: "issue_commented",
-      payload: { issueId: childIssueId, commentId: randomUUID() },
-      contextSnapshot: { issueId: childIssueId, wakeReason: "issue_commented" },
+      payload: { issueId: childIssueId, commentId: childCommentId },
+      requestedByActorType: "user",
+      requestedByActorId: "board-user",
+      contextSnapshot: {
+        issueId: childIssueId,
+        commentId: childCommentId,
+        wakeCommentId: childCommentId,
+        wakeReason: "issue_commented",
+        source: "issue.comment",
+      },
     });
 
     expect(childCommentWake).not.toBeNull();
@@ -493,12 +713,29 @@ describeEmbeddedPostgres("heartbeat dependency-aware queued run selection", () =
       releasePolicy: { strategy: "manual", note: "full_pause" },
     });
 
+    const rootCommentId = randomUUID();
+    await db.insert(issueComments).values({
+      id: rootCommentId,
+      companyId,
+      issueId: rootIssueId,
+      authorUserId: "board-user",
+      body: "Please respond while this hold is active.",
+    });
+
     const rootCommentWake = await heartbeat.wakeup(agentId, {
       source: "automation",
       triggerDetail: "system",
       reason: "issue_commented",
-      payload: { issueId: rootIssueId, commentId: randomUUID() },
-      contextSnapshot: { issueId: rootIssueId, wakeReason: "issue_commented" },
+      payload: { issueId: rootIssueId, commentId: rootCommentId },
+      requestedByActorType: "user",
+      requestedByActorId: "board-user",
+      contextSnapshot: {
+        issueId: rootIssueId,
+        commentId: rootCommentId,
+        wakeCommentId: rootCommentId,
+        wakeReason: "issue_commented",
+        source: "issue.comment",
+      },
     });
 
     expect(rootCommentWake).not.toBeNull();

server/src/__tests__/heartbeat-issue-liveness-escalation.test.ts

@@ -4,13 +4,16 @@ import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest
 import {
   activityLog,
   agents,
-  agentWakeupRequests,
   companies,
   createDb,
+  executionWorkspaces,
   heartbeatRuns,
   issueComments,
   issueRelations,
+  issueTreeHolds,
   issues,
+  projects,
+  projectWorkspaces,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -55,6 +58,7 @@ vi.mock("../adapters/index.ts", async () => {
 });
 
 import { heartbeatService } from "../services/heartbeat.ts";
+import { instanceSettingsService } from "../services/instance-settings.ts";
 import { runningProcesses } from "../adapters/index.ts";
 
 const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
@@ -94,13 +98,23 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
     }
     await new Promise((resolve) => setTimeout(resolve, 50));
     await db.execute(sql.raw(`TRUNCATE TABLE "companies" CASCADE`));
+    await instanceSettingsService(db).updateExperimental({
+      enableIssueGraphLivenessAutoRecovery: false,
+      enableIsolatedWorkspaces: false,
+    });
   });
 
   afterAll(async () => {
     await tempDb?.cleanup();
   });
 
-  async function seedBlockedChain() {
+  async function enableAutoRecovery() {
+    await instanceSettingsService(db).updateExperimental({
+      enableIssueGraphLivenessAutoRecovery: true,
+    });
+  }
+
+  async function seedBlockedChain(opts: { stale?: boolean } = {}) {
     const companyId = randomUUID();
     const managerId = randomUUID();
     const coderId = randomUUID();
@@ -124,7 +138,7 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
         status: "idle",
         adapterType: "codex_local",
         adapterConfig: {},
-        runtimeConfig: {},
+        runtimeConfig: { heartbeat: { wakeOnDemand: false } },
         permissions: {},
       },
       {
@@ -136,11 +150,14 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
         reportsTo: managerId,
         adapterType: "codex_local",
         adapterConfig: {},
-        runtimeConfig: {},
+        runtimeConfig: { heartbeat: { wakeOnDemand: false } },
         permissions: {},
       },
     ]);
 
+    const issueTimestamp = opts.stale === false
+      ? new Date()
+      : new Date(Date.now() - 25 * 60 * 60 * 1000);
     await db.insert(issues).values([
       {
         id: blockedIssueId,
@@ -151,6 +168,8 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
         assigneeAgentId: coderId,
         issueNumber: 1,
         identifier: `${issuePrefix}-1`,
+        createdAt: issueTimestamp,
+        updatedAt: issueTimestamp,
       },
       {
         id: blockerIssueId,
@@ -160,6 +179,8 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
         priority: "medium",
         issueNumber: 2,
         identifier: `${issuePrefix}-2`,
+        createdAt: issueTimestamp,
+        updatedAt: issueTimestamp,
       },
     ]);
 
@@ -173,7 +194,91 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
     return { companyId, managerId, blockedIssueId, blockerIssueId };
   }
 
-  it("creates one manager escalation, preserves blockers, and wakes the assignee", async () => {
+  it("keeps liveness findings advisory when auto recovery is disabled", async () => {
+    const { companyId } = await seedBlockedChain();
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileIssueGraphLiveness();
+
+    expect(result.findings).toBe(1);
+    expect(result.autoRecoveryEnabled).toBe(false);
+    expect(result.escalationsCreated).toBe(0);
+    expect(result.skippedAutoRecoveryDisabled).toBe(1);
+
+    const escalations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "harness_liveness_escalation")));
+    expect(escalations).toHaveLength(0);
+  });
+
+  it("does not create recovery issues until the dependency path is stale for 24 hours", async () => {
+    await enableAutoRecovery();
+    const { companyId } = await seedBlockedChain({ stale: false });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileIssueGraphLiveness();
+
+    expect(result.findings).toBe(1);
+    expect(result.escalationsCreated).toBe(0);
+    expect(result.skippedAutoRecoveryTooYoung).toBe(1);
+
+    const escalations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "harness_liveness_escalation")));
+    expect(escalations).toHaveLength(0);
+  });
+
+  it("suppresses liveness escalation when the source issue is under an active pause hold", async () => {
+    await enableAutoRecovery();
+    const { companyId, blockedIssueId } = await seedBlockedChain();
+
+    await db.insert(issueTreeHolds).values({
+      companyId,
+      rootIssueId: blockedIssueId,
+      mode: "pause",
+      status: "active",
+      reason: "pause liveness recovery subtree",
+      releasePolicy: { strategy: "manual" },
+    });
+
+    const result = await heartbeatService(db).reconcileIssueGraphLiveness();
+
+    expect(result.findings).toBe(1);
+    expect(result.escalationsCreated).toBe(0);
+    expect(result.existingEscalations).toBe(0);
+    expect(result.skipped).toBe(1);
+
+    const escalations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "harness_liveness_escalation")));
+    expect(escalations).toHaveLength(0);
+  });
+
+  it("treats an active executionRunId on the leaf blocker as a live execution path", async () => {
+    await enableAutoRecovery();
+    const { companyId, managerId, blockedIssueId, blockerIssueId } = await seedBlockedChain();
+    const runId = randomUUID();
+    await db.insert(heartbeatRuns).values({
+      id: runId,
+      companyId,
+      agentId: managerId,
+      status: "running",
+      contextSnapshot: { issueId: blockedIssueId },
+    });
+    await db.update(issues).set({ executionRunId: runId }).where(eq(issues.id, blockerIssueId));
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileIssueGraphLiveness();
+
+    expect(result.findings).toBe(0);
+    expect(result.escalationsCreated).toBe(0);
+  });
+
+  it("creates one manager escalation, preserves blockers, and records owner selection", async () => {
+    await enableAutoRecovery();
     const { companyId, managerId, blockedIssueId, blockerIssueId } = await seedBlockedChain();
     const heartbeat = heartbeatService(db);
 
@@ -182,7 +287,6 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
 
     expect(first.escalationsCreated).toBe(1);
     expect(second.escalationsCreated).toBe(0);
-    expect(second.existingEscalations).toBe(1);
 
     const escalations = await db
       .select()
@@ -195,9 +299,15 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
       );
     expect(escalations).toHaveLength(1);
     expect(escalations[0]).toMatchObject({
-      parentId: blockedIssueId,
+      parentId: blockerIssueId,
       assigneeAgentId: managerId,
       status: expect.stringMatching(/^(todo|in_progress|done)$/),
+      originFingerprint: [
+        "harness_liveness_leaf",
+        companyId,
+        "blocked_by_unassigned_issue",
+        blockerIssueId,
+      ].join(":"),
     });
 
     const blockers = await db
@@ -213,15 +323,217 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
     expect(comments[0]?.body).toContain("harness-level liveness incident");
     expect(comments[0]?.body).toContain(escalations[0]?.identifier ?? escalations[0]!.id);
 
-    const wakes = await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.agentId, managerId));
-    expect(wakes.some((wake) => wake.reason === "issue_assigned")).toBe(true);
-
     const events = await db.select().from(activityLog).where(eq(activityLog.companyId, companyId));
-    expect(events.some((event) => event.action === "issue.harness_liveness_escalation_created")).toBe(true);
+    const createdEvent = events.find((event) => event.action === "issue.harness_liveness_escalation_created");
+    expect(createdEvent).toBeTruthy();
+    expect(createdEvent?.details).toMatchObject({
+      recoveryIssueId: blockerIssueId,
+      ownerSelection: {
+        selectedAgentId: managerId,
+        selectedReason: "root_agent",
+        selectedSourceIssueId: blockerIssueId,
+      },
+      workspaceSelection: {
+        reuseRecoveryExecutionWorkspace: false,
+        inheritedExecutionWorkspaceFromIssueId: null,
+        projectWorkspaceSourceIssueId: blockerIssueId,
+      },
+    });
     expect(events.some((event) => event.action === "issue.blockers.updated")).toBe(true);
   });
 
+  it("parents recovery under the leaf blocker without inheriting dependent or blocker execution state for manager-owned recovery", async () => {
+    await enableAutoRecovery();
+    await instanceSettingsService(db).updateExperimental({ enableIsolatedWorkspaces: true });
+
+    const companyId = randomUUID();
+    const managerId = randomUUID();
+    const blockedIssueId = randomUUID();
+    const blockerIssueId = randomUUID();
+    const dependentProjectId = randomUUID();
+    const blockerProjectId = randomUUID();
+    const dependentProjectWorkspaceId = randomUUID();
+    const blockerProjectWorkspaceId = randomUUID();
+    const dependentExecutionWorkspaceId = randomUUID();
+    const blockerExecutionWorkspaceId = randomUUID();
+    const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+    const issueTimestamp = new Date(Date.now() - 25 * 60 * 60 * 1000);
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(agents).values({
+      id: managerId,
+      companyId,
+      name: "Root Operator",
+      role: "operator",
+      status: "idle",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: { heartbeat: { wakeOnDemand: false } },
+      permissions: {},
+    });
+    await db.insert(projects).values([
+      {
+        id: dependentProjectId,
+        companyId,
+        name: "Dependent workspace project",
+        status: "in_progress",
+      },
+      {
+        id: blockerProjectId,
+        companyId,
+        name: "Blocker workspace project",
+        status: "in_progress",
+      },
+    ]);
+    await db.insert(projectWorkspaces).values([
+      {
+        id: dependentProjectWorkspaceId,
+        companyId,
+        projectId: dependentProjectId,
+        name: "Dependent primary",
+      },
+      {
+        id: blockerProjectWorkspaceId,
+        companyId,
+        projectId: blockerProjectId,
+        name: "Blocker primary",
+      },
+    ]);
+    await db.insert(executionWorkspaces).values([
+      {
+        id: dependentExecutionWorkspaceId,
+        companyId,
+        projectId: dependentProjectId,
+        projectWorkspaceId: dependentProjectWorkspaceId,
+        mode: "operator_branch",
+        strategyType: "git_worktree",
+        name: "Dependent branch",
+        status: "active",
+        providerType: "git_worktree",
+      },
+      {
+        id: blockerExecutionWorkspaceId,
+        companyId,
+        projectId: blockerProjectId,
+        projectWorkspaceId: blockerProjectWorkspaceId,
+        mode: "operator_branch",
+        strategyType: "git_worktree",
+        name: "Blocker branch",
+        status: "active",
+        providerType: "git_worktree",
+      },
+    ]);
+    await db.insert(issues).values([
+      {
+        id: blockedIssueId,
+        companyId,
+        projectId: dependentProjectId,
+        projectWorkspaceId: dependentProjectWorkspaceId,
+        executionWorkspaceId: dependentExecutionWorkspaceId,
+        executionWorkspacePreference: "reuse_existing",
+        executionWorkspaceSettings: { mode: "operator_branch" },
+        title: "Blocked dependent",
+        status: "blocked",
+        priority: "medium",
+        issueNumber: 1,
+        identifier: `${issuePrefix}-1`,
+        createdAt: issueTimestamp,
+        updatedAt: issueTimestamp,
+      },
+      {
+        id: blockerIssueId,
+        companyId,
+        projectId: blockerProjectId,
+        projectWorkspaceId: blockerProjectWorkspaceId,
+        executionWorkspaceId: blockerExecutionWorkspaceId,
+        executionWorkspacePreference: "reuse_existing",
+        executionWorkspaceSettings: { mode: "operator_branch" },
+        title: "Unassigned leaf blocker",
+        status: "todo",
+        priority: "medium",
+        issueNumber: 2,
+        identifier: `${issuePrefix}-2`,
+        createdAt: issueTimestamp,
+        updatedAt: issueTimestamp,
+      },
+    ]);
+    await db.insert(issueRelations).values({
+      companyId,
+      issueId: blockerIssueId,
+      relatedIssueId: blockedIssueId,
+      type: "blocks",
+    });
+
+    const result = await heartbeatService(db).reconcileIssueGraphLiveness();
+
+    expect(result.escalationsCreated).toBe(1);
+    const escalations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "harness_liveness_escalation")));
+    expect(escalations).toHaveLength(1);
+    expect(escalations[0]).toMatchObject({
+      parentId: blockerIssueId,
+      projectId: blockerProjectId,
+      projectWorkspaceId: blockerProjectWorkspaceId,
+      executionWorkspaceId: null,
+      executionWorkspacePreference: null,
+      assigneeAgentId: managerId,
+    });
+  });
+
+  it("reuses one open recovery issue for multiple dependents with the same leaf blocker", async () => {
+    await enableAutoRecovery();
+    const { companyId, blockedIssueId, blockerIssueId } = await seedBlockedChain();
+    const secondBlockedIssueId = randomUUID();
+    const issuePrefix = `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+    const issueTimestamp = new Date(Date.now() - 25 * 60 * 60 * 1000);
+    await db.insert(issues).values({
+      id: secondBlockedIssueId,
+      companyId,
+      title: "Second blocked parent",
+      status: "blocked",
+      priority: "medium",
+      issueNumber: 3,
+      identifier: `${issuePrefix}-3`,
+      createdAt: issueTimestamp,
+      updatedAt: issueTimestamp,
+    });
+    await db.insert(issueRelations).values({
+      companyId,
+      issueId: blockerIssueId,
+      relatedIssueId: secondBlockedIssueId,
+      type: "blocks",
+    });
+    const heartbeat = heartbeatService(db);
+
+    const result = await heartbeat.reconcileIssueGraphLiveness();
+
+    expect(result.findings).toBe(2);
+    expect(result.escalationsCreated).toBe(1);
+    expect(result.existingEscalations).toBe(1);
+    const escalations = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "harness_liveness_escalation")));
+    expect(escalations).toHaveLength(1);
+
+    const blockers = await db
+      .select({ blockedIssueId: issueRelations.relatedIssueId })
+      .from(issueRelations)
+      .where(and(eq(issueRelations.companyId, companyId), eq(issueRelations.issueId, escalations[0]!.id)));
+    expect(blockers.map((row) => row.blockedIssueId).sort()).toEqual(
+      [blockedIssueId, secondBlockedIssueId].sort(),
+    );
+  });
+
   it("creates a fresh escalation when the previous matching escalation is terminal", async () => {
+    await enableAutoRecovery();
     const { companyId, managerId, blockedIssueId, blockerIssueId } = await seedBlockedChain();
     const heartbeat = heartbeatService(db);
     const incidentKey = [
@@ -265,7 +577,7 @@ describeEmbeddedPostgres("heartbeat issue graph liveness escalation", () => {
     expect(openEscalations).toHaveLength(2);
     const freshEscalation = openEscalations.find((issue) => issue.status !== "done");
     expect(freshEscalation).toMatchObject({
-      parentId: blockedIssueId,
+      parentId: blockerIssueId,
       assigneeAgentId: managerId,
       status: expect.stringMatching(/^(todo|in_progress|done)$/),
     });