fix(remote-sandbox): harden host workspace resumes (#5922)

## Thinking Path

> - Paperclip orchestrates AI agents through a control plane while
adapters execute work in local, remote, or sandboxed runtimes.
> - Remote sandbox execution depends on a strict host-versus-remote
workspace boundary: the host prepares/restores files, while the adapter
command runs inside the sandbox cwd.
> - Jannes' PR #5823 identified host-side failure modes that were not
covered by replacement PR #5822.
> - Persisting a remote pod cwd in session params could poison the next
host heartbeat resume and make Paperclip inspect or upload system temp
roots.
> - Plugin sandbox providers also need a narrow way to receive
model-provider API keys without exposing the full server environment to
every plugin worker.
> - This pull request ports the host-side fixes from #5823 in the
current codebase style, with focused regression coverage.
> - The benefit is safer remote sandbox resumes and plugin worker
environment handling without broadening core plugin privileges.

## What Changed

- Persist host workspace cwd, not remote sandbox cwd, in `claude_local`
session params while retaining remote execution identity metadata.
- Reject saved session cwds that point at system roots before heartbeat
falls back to agent home workspace.
- Skip sockets, FIFOs, devices, and other non-file entries during
workspace restore snapshot capture/comparison.
- Pass a small model-provider API-key allowlist only to plugins
declaring `environment.drivers.register`.
- Added focused regression tests for remote Claude session params,
unsafe session cwd detection, plugin worker env filtering, and non-file
snapshot entries.

Credits: ports host-side fixes from Jannes' #5823.

## Verification

- `pnpm vitest run
packages/adapter-utils/src/workspace-restore-merge.test.ts
server/src/services/session-workspace-cwd.test.ts
server/src/__tests__/claude-local-execute.test.ts
server/src/__tests__/plugin-database.test.ts` (25 passed, 7 skipped by
existing embedded-Postgres host guard)
- `pnpm --filter @paperclipai/adapter-utils typecheck`
- `pnpm --filter @paperclipai/adapter-claude-local typecheck`
- `pnpm --filter @paperclipai/server typecheck`

## Risks

- Low risk: changes are scoped to remote sandbox/session metadata,
workspace snapshot filtering, and plugin worker env setup.
- Sandbox-provider plugins now receive only the explicit model-provider
key allowlist; any provider needing another key name will need a
deliberate allowlist update.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5-based coding agent, tool-enabled local code
execution and repository editing.

## 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
- [x] 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

---------

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

server/src/services/heartbeat.ts

@@ -163,6 +163,7 @@ import { extractSkillMentionIds } from "@paperclipai/shared";
 import { environmentService } from "./environments.js";
 import { environmentRuntimeService } from "./environment-runtime.js";
 import { environmentRunOrchestrator } from "./environment-run-orchestrator.js";
+import { isUnsafeSessionWorkspaceCwd } from "./session-workspace-cwd.js";
 import type { PluginWorkerManager } from "./plugin-worker-manager.js";
 
 const MAX_LIVE_LOG_CHUNK_BYTES = 8 * 1024;
@@ -3568,7 +3569,8 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
     }
 
     const sessionCwd = readNonEmptyString(previousSessionParams?.cwd);
-    if (sessionCwd) {
+    const sessionCwdLooksUnsafe = isUnsafeSessionWorkspaceCwd(sessionCwd);
+    if (sessionCwd && !sessionCwdLooksUnsafe) {
       const sessionCwdExists = await fs
         .stat(sessionCwd)
         .then((stats) => stats.isDirectory())
@@ -3590,7 +3592,11 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
     const cwd = resolveDefaultAgentWorkspaceDir(agent.id);
     await fs.mkdir(cwd, { recursive: true });
     const warnings: string[] = [];
-    if (sessionCwd) {
+    if (sessionCwd && sessionCwdLooksUnsafe) {
+      warnings.push(
+        `Saved session workspace "${sessionCwd}" points at a system temp root and was rejected as untrusted. Using fallback workspace "${cwd}" for this run.`,
+      );
+    } else if (sessionCwd) {
       warnings.push(
         `Saved session workspace "${sessionCwd}" is not available. Using fallback workspace "${cwd}" for this run.`,
       );

server/src/services/plugin-loader.ts

@@ -79,6 +79,37 @@ export const DEFAULT_LOCAL_PLUGIN_DIR = path.join(
 
 const DEV_TSX_LOADER_PATH = path.resolve(__dirname, "../../../cli/node_modules/tsx/dist/loader.mjs");
 
+const ADAPTER_ENV_PASSTHROUGH = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "GOOGLE_API_KEY",
+  "GEMINI_API_KEY",
+  "OPENROUTER_API_KEY",
+];
+
+export function buildPluginWorkerEnv(input: {
+  manifest: Pick<PaperclipPluginManifestV1, "capabilities">;
+  instanceInfo: { deploymentMode?: string | null; deploymentExposure?: string | null };
+  processEnv?: NodeJS.ProcessEnv;
+}): Record<string, string> {
+  const processEnv = input.processEnv ?? process.env;
+  const env: Record<string, string> = {
+    PAPERCLIP_DEPLOYMENT_MODE: input.instanceInfo.deploymentMode ?? "",
+    PAPERCLIP_DEPLOYMENT_EXPOSURE: input.instanceInfo.deploymentExposure ?? "",
+  };
+  const canRegisterEnvironmentDrivers = Array.isArray(input.manifest.capabilities)
+    && input.manifest.capabilities.includes("environment.drivers.register");
+  if (!canRegisterEnvironmentDrivers) return env;
+
+  for (const key of ADAPTER_ENV_PASSTHROUGH) {
+    const value = processEnv[key];
+    if (value && value.trim().length > 0) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
 // ---------------------------------------------------------------------------
 // Discovery result types
 // ---------------------------------------------------------------------------
@@ -1820,10 +1851,7 @@ export function pluginLoader(
         databaseNamespace,
         hostHandlers,
         autoRestart: true,
-        env: {
-          PAPERCLIP_DEPLOYMENT_MODE: instanceInfo.deploymentMode ?? "",
-          PAPERCLIP_DEPLOYMENT_EXPOSURE: instanceInfo.deploymentExposure ?? "",
-        },
+        env: buildPluginWorkerEnv({ manifest, instanceInfo }),
       };
 
       // Repo-local plugin installs can resolve workspace TS sources at runtime

server/src/services/session-workspace-cwd.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { isUnsafeSessionWorkspaceCwd } from "./session-workspace-cwd.js";
+
+describe("isUnsafeSessionWorkspaceCwd", () => {
+  it("rejects system roots that can poison remote sandbox session resumes", () => {
+    expect(isUnsafeSessionWorkspaceCwd("/")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/private/tmp")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/var/tmp")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/var/run")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/proc")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/sys")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/dev")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/run")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/.")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/..")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/var/./run")).toBe(true);
+  });
+
+  it("allows concrete workspace descendants", () => {
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/paperclip-workspace")).toBe(false);
+    expect(isUnsafeSessionWorkspaceCwd("/Users/dotta/paperclip")).toBe(false);
+    expect(isUnsafeSessionWorkspaceCwd(null)).toBe(false);
+  });
+});

server/src/services/session-workspace-cwd.ts

@@ -0,0 +1,24 @@
+import path from "node:path";
+
+const SESSION_CWD_SYSTEM_ROOTS = new Set([
+  "/",
+  "/tmp",
+  "/var",
+  "/var/tmp",
+  "/var/run",
+  "/usr",
+  "/etc",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/run",
+  "/private",
+  "/private/tmp",
+]);
+
+export function isUnsafeSessionWorkspaceCwd(cwd: string | null | undefined): boolean {
+  const value = typeof cwd === "string" && cwd.trim().length > 0 ? cwd.trim() : null;
+  if (!value) return false;
+  const normalized = path.normalize(value.replace(/\/+$/, "") || "/");
+  return SESSION_CWD_SYSTEM_ROOTS.has(normalized);
+}