Merge upstream/master into dev (76 commits)

Resolved 5 conflicts:
- .github/workflows/docker.yml, release.yml: kept fork stubs (CI handled by build-prod/build-dev)
- server/src/routes/secrets.ts: kept fork's /usages route alongside upstream's /usage, /access-events
- server/src/services/secrets.ts: kept fork's usages() function and in-use deletion guard,
  layered before upstream's soft-delete + provider cleanup in remove()
- ui/src/api/secrets.ts: kept fork's usages() method alongside upstream's vault methods

Typechecks pass on @paperclipai/shared, @paperclipai/server, @paperclipai/ui.

.github/workflows/pr.yml

@@ -45,6 +45,15 @@ jobs:
       - name: Validate Dockerfile deps stage
         run: node ./scripts/check-docker-deps-stage.mjs
 
+      - name: Validate release package manifest
+        run: node ./scripts/release-package-map.mjs check
+
+      - name: Verify release package bootstrap for changed manifests
+        run: |
+          mapfile -t changed_paths < <(git diff --name-only "${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}")
+          PAPERCLIP_RELEASE_BOOTSTRAP_BASE_SHA="${{ github.event.pull_request.base.sha }}" \
+            node ./scripts/check-release-package-bootstrap.mjs "${changed_paths[@]}"
+
       - name: Validate dependency resolution when manifests change
         run: |
           changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}")"
@@ -76,11 +85,11 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Typecheck
-        run: pnpm -r typecheck
+      - name: Typecheck workspaces whose build scripts skip TypeScript
+        run: pnpm run typecheck:build-gaps
 
-      - name: Run tests
-        run: pnpm test:run
+      - name: Run general test suites
+        run: pnpm test:run:general
 
       - name: Verify release registry test coverage
         run: pnpm run test:release-registry
@@ -88,7 +97,76 @@ jobs:
       - name: Build
         run: pnpm build
 
-      - name: Release canary dry run
+  verify_serialized_server:
+    name: Verify serialized server suites (${{ matrix.shard_label }})
+    needs: [policy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - shard_index: 0
+            shard_count: 4
+            shard_label: 1/4
+          - shard_index: 1
+            shard_count: 4
+            shard_label: 2/4
+          - shard_index: 2
+            shard_count: 4
+            shard_label: 3/4
+          - shard_index: 3
+            shard_count: 4
+            shard_label: 4/4
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run serialized server test shard
+        run: pnpm test:run:serialized -- --shard-index ${{ matrix.shard_index }} --shard-count ${{ matrix.shard_count }}
+
+  canary_dry_run:
+    name: Canary Dry Run
+    needs: [policy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # `release.sh` always executes its Step 2/7 workspace build, even when
+      # `--skip-verify` bypasses the initial verification gate.
+      - name: Release canary dry run via release.sh internal build
         run: |
           git checkout -B master HEAD
           git checkout -- pnpm-lock.yaml
@@ -117,9 +195,6 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Build
-        run: pnpm build
-
       - name: Install Playwright
         run: npx playwright install --with-deps chromium
 

Dockerfile

@@ -25,6 +25,7 @@ COPY packages/mcp-server/package.json packages/mcp-server/
 COPY packages/adapters/acpx-local/package.json packages/adapters/acpx-local/
 COPY packages/adapters/claude-local/package.json packages/adapters/claude-local/
 COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
+COPY packages/adapters/cursor-cloud/package.json packages/adapters/cursor-cloud/
 COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
 COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/
 COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/

cli/package.json

@@ -40,6 +40,7 @@
     "@paperclipai/adapter-acpx-local": "workspace:*",
     "@paperclipai/adapter-claude-local": "workspace:*",
     "@paperclipai/adapter-codex-local": "workspace:*",
+    "@paperclipai/adapter-cursor-cloud": "workspace:*",
     "@paperclipai/adapter-cursor-local": "workspace:*",
     "@paperclipai/adapter-gemini-local": "workspace:*",
     "@paperclipai/adapter-opencode-local": "workspace:*",
@@ -49,7 +50,7 @@
     "@paperclipai/db": "workspace:*",
     "@paperclipai/server": "workspace:*",
     "@paperclipai/shared": "workspace:*",
-    "drizzle-orm": "0.38.4",
+    "drizzle-orm": "0.45.2",
     "dotenv": "^17.0.1",
     "commander": "^13.1.0",
     "embedded-postgres": "^18.1.0-beta.16",

cli/src/__tests__/company.test.ts

@@ -244,6 +244,7 @@ describe("renderCompanyImportPreview", () => {
             billingCode: null,
             executionWorkspaceSettings: null,
             assigneeAdapterOverrides: null,
+            comments: [],
             metadata: null,
           },
         ],
@@ -460,6 +461,7 @@ describe("import selection catalog", () => {
             billingCode: null,
             executionWorkspaceSettings: null,
             assigneeAdapterOverrides: null,
+            comments: [],
             metadata: null,
           },
         ],

cli/src/__tests__/home-paths.test.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -16,13 +17,14 @@ describe("home path resolution", () => {
   });
 
   it("defaults to ~/.paperclip and default instance", () => {
-    delete process.env.PAPERCLIP_HOME;
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-home-paths-"));
+    process.env.PAPERCLIP_HOME = home;
     delete process.env.PAPERCLIP_INSTANCE_ID;
 
     const paths = describeLocalInstancePaths();
-    expect(paths.homeDir).toBe(path.resolve(os.homedir(), ".paperclip"));
+    expect(paths.homeDir).toBe(home);
     expect(paths.instanceId).toBe("default");
-    expect(paths.configPath).toBe(path.resolve(os.homedir(), ".paperclip", "instances", "default", "config.json"));
+    expect(paths.configPath).toBe(path.resolve(home, "instances", "default", "config.json"));
   });
 
   it("supports PAPERCLIP_HOME and explicit instance ids", () => {
@@ -34,7 +36,7 @@ describe("home path resolution", () => {
   });
 
   it("rejects invalid instance ids", () => {
-    expect(() => resolvePaperclipInstanceId("bad/id")).toThrow(/Invalid instance id/);
+    expect(() => resolvePaperclipInstanceId("bad/id")).toThrow(/Invalid PAPERCLIP_INSTANCE_ID/);
   });
 
   it("expands ~ prefixes", () => {

cli/src/__tests__/onboard.test.ts

@@ -6,6 +6,7 @@ import { onboard } from "../commands/onboard.js";
 import type { PaperclipConfig } from "../config/schema.js";
 
 const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
 
 function createExistingConfigFixture() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-"));
@@ -85,10 +86,18 @@ describe("onboard", () => {
     delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
     delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
     delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+    delete process.env.PAPERCLIP_HOME;
+    delete process.env.PAPERCLIP_CONFIG;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+    delete process.env.PAPERCLIP_BIND;
+    delete process.env.PAPERCLIP_BIND_HOST;
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+    delete process.env.HOST;
   });
 
   afterEach(() => {
     process.env = { ...ORIGINAL_ENV };
+    process.chdir(ORIGINAL_CWD);
   });
 
   it("preserves an existing config when rerun without flags", async () => {
@@ -125,6 +134,27 @@ describe("onboard", () => {
     expect(raw.server.host).toBe("127.0.0.1");
   });
 
+  it("creates instance-root config and data paths for a fresh PAPERCLIP_HOME", async () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-home-"));
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-cwd-"));
+    process.chdir(cwd);
+    process.env.PAPERCLIP_HOME = home;
+
+    await onboard({ yes: true, invokedByRun: true });
+
+    const instanceRoot = path.join(home, "instances", "default");
+    const configPath = path.join(instanceRoot, "config.json");
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+
+    expect(raw.database.embeddedPostgresDataDir).toBe(path.join(instanceRoot, "db"));
+    expect(raw.database.backup.dir).toBe(path.join(instanceRoot, "data", "backups"));
+    expect(raw.logging.logDir).toBe(path.join(instanceRoot, "logs"));
+    expect(raw.storage.localDisk.baseDir).toBe(path.join(instanceRoot, "data", "storage"));
+    expect(raw.secrets.localEncrypted.keyFilePath).toBe(path.join(instanceRoot, "secrets", "master.key"));
+    expect(fs.existsSync(path.join(instanceRoot, ".env"))).toBe(true);
+    expect(fs.existsSync(path.join(instanceRoot, "secrets", "master.key"))).toBe(true);
+  });
+
   it("supports authenticated/private quickstart bind presets", async () => {
     const configPath = createFreshConfigPath();
     process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";

cli/src/__tests__/secrets.test.ts

@@ -0,0 +1,257 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { Agent, CompanySecret } from "@paperclipai/shared";
+import type { PaperclipConfig } from "../config/schema.js";
+import { secretsCheck } from "../checks/secrets-check.js";
+import {
+  buildInlineMigrationSecretName,
+  buildMigratedAgentEnv,
+  collectInlineSecretMigrationCandidates,
+  parseSecretsInclude,
+  toPlainEnvValue,
+} from "../commands/client/secrets.js";
+
+function agent(partial: Partial<Agent>): Agent {
+  return {
+    id: "agent-12345678",
+    companyId: "company-1",
+    name: "Coder",
+    urlKey: "coder",
+    role: "engineer",
+    title: null,
+    icon: null,
+    status: "idle",
+    reportsTo: null,
+    capabilities: null,
+    adapterType: "codex_local",
+    adapterConfig: {},
+    runtimeConfig: {},
+    budgetMonthlyCents: 0,
+    spentMonthlyCents: 0,
+    pauseReason: null,
+    pausedAt: null,
+    permissions: {
+      canCreateAgents: false,
+    },
+    lastHeartbeatAt: null,
+    metadata: null,
+    createdAt: new Date("2026-04-26T00:00:00.000Z"),
+    updatedAt: new Date("2026-04-26T00:00:00.000Z"),
+    ...partial,
+  };
+}
+
+function secret(partial: Partial<CompanySecret>): CompanySecret {
+  return {
+    id: "secret-1",
+    companyId: "company-1",
+    key: "agent_agent-12_anthropic_api_key",
+    name: "agent_agent-12_anthropic_api_key",
+    provider: "local_encrypted",
+    status: "active",
+    managedMode: "paperclip_managed",
+    externalRef: null,
+    providerConfigId: null,
+    providerMetadata: null,
+    latestVersion: 1,
+    description: null,
+    lastResolvedAt: null,
+    lastRotatedAt: null,
+    deletedAt: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    createdAt: new Date("2026-04-26T00:00:00.000Z"),
+    updatedAt: new Date("2026-04-26T00:00:00.000Z"),
+    ...partial,
+  };
+}
+
+function configWithSecretsProvider(provider: PaperclipConfig["secrets"]["provider"]): PaperclipConfig {
+  return {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-05-02T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: "/tmp/paperclip/db",
+      embeddedPostgresPort: 55432,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: "/tmp/paperclip/backups",
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: "/tmp/paperclip/logs",
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled: true,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: "/tmp/paperclip/storage",
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider,
+      strictMode: true,
+      localEncrypted: {
+        keyFilePath: "/tmp/paperclip/secrets/master.key",
+      },
+    },
+  };
+}
+
+describe("secrets CLI helpers", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.PAPERCLIP_SECRETS_AWS_REGION;
+    delete process.env.AWS_REGION;
+    delete process.env.AWS_DEFAULT_REGION;
+    delete process.env.PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID;
+    delete process.env.PAPERCLIP_SECRETS_AWS_KMS_KEY_ID;
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("parses declaration include filters", () => {
+    expect(parseSecretsInclude("agents,projects,tasks")).toEqual({
+      company: false,
+      agents: true,
+      projects: true,
+      issues: true,
+      skills: false,
+    });
+  });
+
+  it("detects inline sensitive env values that need migration", () => {
+    const rows = collectInlineSecretMigrationCandidates(
+      [
+        agent({
+          id: "agent-12345678",
+          adapterConfig: {
+            env: {
+              ANTHROPIC_API_KEY: "sk-ant-test",
+              GH_TOKEN: {
+                type: "plain",
+                value: "ghp-test",
+              },
+              PATH: {
+                type: "plain",
+                value: "/usr/bin",
+              },
+              OPENAI_API_KEY: {
+                type: "secret_ref",
+                secretId: "secret-existing",
+              },
+            },
+          },
+        }),
+      ],
+      [
+        secret({
+          id: "secret-gh-token",
+          name: buildInlineMigrationSecretName("agent-12345678", "GH_TOKEN"),
+        }),
+      ],
+    );
+
+    expect(rows).toEqual([
+      {
+        agentId: "agent-12345678",
+        agentName: "Coder",
+        envKey: "ANTHROPIC_API_KEY",
+        secretName: "agent_agent-12_anthropic_api_key",
+        existingSecretId: null,
+      },
+      {
+        agentId: "agent-12345678",
+        agentName: "Coder",
+        envKey: "GH_TOKEN",
+        secretName: "agent_agent-12_gh_token",
+        existingSecretId: "secret-gh-token",
+      },
+    ]);
+  });
+
+  it("builds migrated env bindings without preserving secret values", () => {
+    const next = buildMigratedAgentEnv(
+      {
+        ANTHROPIC_API_KEY: "sk-ant-test",
+        NODE_ENV: {
+          type: "plain",
+          value: "development",
+        },
+      },
+      new Map([["ANTHROPIC_API_KEY", "secret-1"]]),
+    );
+
+    expect(next).toEqual({
+      ANTHROPIC_API_KEY: {
+        type: "secret_ref",
+        secretId: "secret-1",
+        version: "latest",
+      },
+      NODE_ENV: {
+        type: "plain",
+        value: "development",
+      },
+    });
+    expect(JSON.stringify(next)).not.toContain("sk-ant-test");
+  });
+
+  it("reads only explicit plain env values", () => {
+    expect(toPlainEnvValue("plain-value")).toBe("plain-value");
+    expect(toPlainEnvValue({ type: "plain", value: "wrapped" })).toBe("wrapped");
+    expect(toPlainEnvValue({ type: "secret_ref", secretId: "secret-1" })).toBeNull();
+  });
+
+  it("reports the AWS bootstrap config required by doctor", () => {
+    const result = secretsCheck(configWithSecretsProvider("aws_secrets_manager"));
+
+    expect(result.status).toBe("fail");
+    expect(result.message).toContain("PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID");
+    expect(result.repairHint).toContain("AWS SDK default credential chain");
+    expect(result.repairHint).toContain("Do not store AWS root credentials");
+  });
+
+  it("passes AWS doctor checks when non-secret provider config is present", () => {
+    process.env.PAPERCLIP_SECRETS_AWS_REGION = "us-east-1";
+    process.env.PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID = "prod-us-1";
+    process.env.PAPERCLIP_SECRETS_AWS_KMS_KEY_ID =
+      "arn:aws:kms:us-east-1:123456789012:key/test";
+    process.env.AWS_PROFILE = "paperclip-prod";
+
+    const result = secretsCheck(configWithSecretsProvider("aws_secrets_manager"));
+
+    expect(result.status).toBe("pass");
+    expect(result.message).toContain("prod-us-1");
+    expect(result.message).toContain("AWS_PROFILE/shared config");
+  });
+});

cli/src/adapters/registry.ts

@@ -3,6 +3,7 @@ import { printAcpxStreamEvent } from "@paperclipai/adapter-acpx-local/cli";
 import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
 import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
 import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
+import { printCursorCloudEvent } from "@paperclipai/adapter-cursor-cloud/cli";
 import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";
 import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
 import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
@@ -40,6 +41,11 @@ const cursorLocalCLIAdapter: CLIAdapterModule = {
   formatStdoutEvent: printCursorStreamEvent,
 };
 
+const cursorCloudCLIAdapter: CLIAdapterModule = {
+  type: "cursor_cloud",
+  formatStdoutEvent: printCursorCloudEvent,
+};
+
 const geminiLocalCLIAdapter: CLIAdapterModule = {
   type: "gemini_local",
   formatStdoutEvent: printGeminiStreamEvent,
@@ -58,6 +64,7 @@ const adaptersByType = new Map<string, CLIAdapterModule>(
     openCodeLocalCLIAdapter,
     piLocalCLIAdapter,
     cursorLocalCLIAdapter,
+    cursorCloudCLIAdapter,
     geminiLocalCLIAdapter,
     openclawGatewayCLIAdapter,
     processCLIAdapter,

cli/src/checks/secrets-check.ts

@@ -5,6 +5,9 @@ import type { PaperclipConfig } from "../config/schema.js";
 import type { CheckResult } from "./index.js";
 import { resolveRuntimeLikePath } from "./path-resolver.js";
 
+const AWS_CREDENTIAL_SOURCE_HINT =
+  "Provide AWS runtime credentials through the AWS SDK default credential chain: IAM role/workload identity, AWS_PROFILE/SSO/shared credentials, web identity, container/instance metadata, or short-lived shell credentials";
+
 function decodeMasterKey(raw: string): Buffer | null {
   const trimmed = raw.trim();
   if (!trimmed) return null;
@@ -47,13 +50,16 @@ function withStrictModeNote(
 
 export function secretsCheck(config: PaperclipConfig, configPath?: string): CheckResult {
   const provider = config.secrets.provider;
+  if (provider === "aws_secrets_manager") {
+    return withStrictModeNote(awsSecretsManagerCheck(), config);
+  }
   if (provider !== "local_encrypted") {
     return {
       name: "Secrets adapter",
       status: "fail",
-      message: `${provider} is configured, but this build only supports local_encrypted`,
+      message: `${provider} is configured, but this build only supports local_encrypted and aws_secrets_manager`,
       canRepair: false,
-      repairHint: "Run `paperclipai configure --section secrets` and set provider to local_encrypted",
+      repairHint: "Run `paperclipai configure --section secrets` and choose local_encrypted or aws_secrets_manager",
     };
   }
 
@@ -135,12 +141,100 @@ export function secretsCheck(config: PaperclipConfig, configPath?: string): Chec
     };
   }
 
+  const keyMode = fs.statSync(keyFilePath).mode & 0o777;
+  const permissionWarning =
+    (keyMode & 0o077) !== 0
+      ? `; key file permissions are ${keyMode.toString(8)} (run chmod 600 ${keyFilePath})`
+      : "";
+
   return withStrictModeNote(
     {
       name: "Secrets adapter",
-      status: "pass",
-      message: `Local encrypted provider configured with key file ${keyFilePath}`,
+      status: permissionWarning ? "warn" : "pass",
+      message: `Local encrypted provider configured with key file ${keyFilePath}${permissionWarning}`,
+      repairHint: permissionWarning
+        ? "Restrict the local encrypted secrets key file to owner read/write permissions"
+        : undefined,
     },
     config,
   );
 }
+
+function awsSecretsManagerCheck(): CheckResult {
+  const missingConfig = missingAwsSecretsManagerConfig();
+  if (missingConfig.length > 0) {
+    return {
+      name: "Secrets adapter",
+      status: "fail",
+      message: `AWS Secrets Manager provider is missing non-secret config: ${missingConfig.join(", ")}`,
+      canRepair: false,
+      repairHint:
+        `Set ${missingConfig.join(", ")} in the Paperclip server runtime. ${AWS_CREDENTIAL_SOURCE_HINT}. Do not store AWS root credentials or long-lived IAM user keys in Paperclip secrets.`,
+    };
+  }
+
+  const staticEnvCredentials =
+    process.env.AWS_ACCESS_KEY_ID?.trim() && process.env.AWS_SECRET_ACCESS_KEY?.trim();
+  const credentialSource = detectedAwsCredentialSources().join(", ");
+  const message =
+    `AWS Secrets Manager provider configured for deployment ${process.env.PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID}; ` +
+    `runtime credentials source: ${credentialSource || "AWS SDK default credential chain"}`;
+
+  if (staticEnvCredentials) {
+    return {
+      name: "Secrets adapter",
+      status: "warn",
+      message,
+      canRepair: false,
+      repairHint:
+        "AWS static environment credentials are visible. Use only short-lived shell credentials locally; prefer IAM role/workload identity for hosted deployments and never store AWS access keys in Paperclip company secrets.",
+    };
+  }
+
+  return {
+    name: "Secrets adapter",
+    status: "pass",
+    message,
+  };
+}
+
+function missingAwsSecretsManagerConfig(): string[] {
+  const missing: string[] = [];
+  if (
+    !(
+      process.env.PAPERCLIP_SECRETS_AWS_REGION?.trim() ||
+      process.env.AWS_REGION?.trim() ||
+      process.env.AWS_DEFAULT_REGION?.trim()
+    )
+  ) {
+    missing.push("PAPERCLIP_SECRETS_AWS_REGION or AWS_REGION/AWS_DEFAULT_REGION");
+  }
+  if (!process.env.PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID?.trim()) {
+    missing.push("PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID");
+  }
+  if (!process.env.PAPERCLIP_SECRETS_AWS_KMS_KEY_ID?.trim()) {
+    missing.push("PAPERCLIP_SECRETS_AWS_KMS_KEY_ID");
+  }
+  return missing;
+}
+
+function detectedAwsCredentialSources(): string[] {
+  const sources: string[] = [];
+  if (process.env.AWS_PROFILE?.trim()) sources.push("AWS_PROFILE/shared config");
+  if (process.env.AWS_ACCESS_KEY_ID?.trim() && process.env.AWS_SECRET_ACCESS_KEY?.trim()) {
+    sources.push("temporary AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment credentials");
+  }
+  if (process.env.AWS_WEB_IDENTITY_TOKEN_FILE?.trim() && process.env.AWS_ROLE_ARN?.trim()) {
+    sources.push("AWS web identity token");
+  }
+  if (
+    process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI?.trim() ||
+    process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI?.trim()
+  ) {
+    sources.push("AWS container credentials endpoint");
+  }
+  if (process.env.AWS_SHARED_CREDENTIALS_FILE?.trim() || process.env.AWS_CONFIG_FILE?.trim()) {
+    sources.push("custom AWS shared credentials/config file");
+  }
+  return sources;
+}

cli/src/commands/client/secrets.ts

@@ -0,0 +1,501 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import type {
+  Agent,
+  AgentEnvConfig,
+  CompanyPortabilityEnvInput,
+  CompanyPortabilityExportPreviewResult,
+  CompanyPortabilityInclude,
+  CompanySecret,
+  EnvBinding,
+  SecretProvider,
+  SecretProviderDescriptor,
+} from "@paperclipai/shared";
+import {
+  addCommonClientOptions,
+  formatInlineRecord,
+  handleCommandError,
+  printOutput,
+  resolveCommandContext,
+  type BaseClientOptions,
+} from "./common.js";
+
+interface SecretListOptions extends BaseClientOptions {
+  companyId?: string;
+}
+
+interface SecretDeclarationsOptions extends BaseClientOptions {
+  companyId?: string;
+  include?: string;
+  kind?: "all" | "secret" | "plain";
+}
+
+interface SecretCreateOptions extends BaseClientOptions {
+  companyId?: string;
+  name?: string;
+  key?: string;
+  provider?: SecretProvider;
+  value?: string;
+  valueEnv?: string;
+  description?: string;
+}
+
+interface SecretLinkOptions extends BaseClientOptions {
+  companyId?: string;
+  name?: string;
+  key?: string;
+  provider?: SecretProvider;
+  externalRef?: string;
+  providerVersionRef?: string;
+  description?: string;
+}
+
+interface SecretDoctorOptions extends BaseClientOptions {
+  companyId?: string;
+}
+
+interface SecretMigrateInlineEnvOptions extends BaseClientOptions {
+  companyId?: string;
+  apply?: boolean;
+}
+
+interface SecretProviderHealth {
+  provider: SecretProvider;
+  status: "ok" | "warn" | "error";
+  message: string;
+  warnings?: string[];
+  backupGuidance?: string[];
+  details?: Record<string, unknown>;
+}
+
+interface SecretProviderHealthResponse {
+  providers: SecretProviderHealth[];
+}
+
+export interface InlineSecretMigrationCandidate {
+  agentId: string;
+  agentName: string;
+  envKey: string;
+  secretName: string;
+  existingSecretId: string | null;
+}
+
+const SENSITIVE_ENV_KEY_RE =
+  /(^token$|[-_]?token$|api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)/i;
+
+const DEFAULT_DECLARATION_INCLUDE: CompanyPortabilityInclude = {
+  company: true,
+  agents: true,
+  projects: true,
+  issues: false,
+  skills: false,
+};
+
+export function parseSecretsInclude(input: string | undefined): CompanyPortabilityInclude {
+  if (!input?.trim()) return { ...DEFAULT_DECLARATION_INCLUDE };
+  const values = input.split(",").map((part) => part.trim().toLowerCase()).filter(Boolean);
+  const include = {
+    company: values.includes("company"),
+    agents: values.includes("agents"),
+    projects: values.includes("projects"),
+    issues: values.includes("issues") || values.includes("tasks"),
+    skills: values.includes("skills"),
+  };
+  if (!Object.values(include).some(Boolean)) {
+    throw new Error("Invalid --include value. Use one or more of: company,agents,projects,issues,tasks,skills");
+  }
+  return include;
+}
+
+export function isSensitiveEnvKey(key: string): boolean {
+  return SENSITIVE_ENV_KEY_RE.test(key);
+}
+
+export function toPlainEnvValue(binding: unknown): string | null {
+  if (typeof binding === "string") return binding;
+  if (typeof binding !== "object" || binding === null || Array.isArray(binding)) return null;
+  const record = binding as Record<string, unknown>;
+  if (record.type === "plain" && typeof record.value === "string") return record.value;
+  return null;
+}
+
+export function buildInlineMigrationSecretName(agentId: string, key: string): string {
+  return `agent_${agentId.slice(0, 8)}_${key.toLowerCase()}`;
+}
+
+export function collectInlineSecretMigrationCandidates(
+  agents: Agent[],
+  existingSecrets: CompanySecret[],
+): InlineSecretMigrationCandidate[] {
+  const secretByName = new Map(existingSecrets.map((secret) => [secret.name, secret]));
+  const candidates: InlineSecretMigrationCandidate[] = [];
+
+  for (const agent of agents) {
+    const env = asRecord(agent.adapterConfig.env);
+    if (!env) continue;
+    for (const [envKey, binding] of Object.entries(env)) {
+      if (!isSensitiveEnvKey(envKey)) continue;
+      const plain = toPlainEnvValue(binding);
+      if (plain === null || plain.trim().length === 0) continue;
+      const secretName = buildInlineMigrationSecretName(agent.id, envKey);
+      candidates.push({
+        agentId: agent.id,
+        agentName: agent.name,
+        envKey,
+        secretName,
+        existingSecretId: secretByName.get(secretName)?.id ?? null,
+      });
+    }
+  }
+
+  return candidates;
+}
+
+export function buildMigratedAgentEnv(
+  env: Record<string, unknown>,
+  secretIdByEnvKey: Map<string, string>,
+): AgentEnvConfig {
+  const next: AgentEnvConfig = { ...(env as Record<string, EnvBinding>) };
+  for (const [envKey, secretId] of secretIdByEnvKey) {
+    next[envKey] = {
+      type: "secret_ref",
+      secretId,
+      version: "latest",
+    };
+  }
+  return next;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function readValueFromOptions(opts: SecretCreateOptions): string {
+  if (opts.value !== undefined && opts.valueEnv !== undefined) {
+    throw new Error("Use only one of --value or --value-env.");
+  }
+  if (opts.valueEnv !== undefined) {
+    const value = process.env[opts.valueEnv];
+    if (!value) throw new Error(`Environment variable ${opts.valueEnv} is empty or unset.`);
+    return value;
+  }
+  if (opts.value !== undefined) return opts.value;
+  throw new Error("Secret value is required. Pass --value or --value-env.");
+}
+
+function renderDeclaration(input: CompanyPortabilityEnvInput): Record<string, unknown> {
+  const scope = input.agentSlug
+    ? `agent:${input.agentSlug}`
+    : input.projectSlug
+      ? `project:${input.projectSlug}`
+      : "company";
+  return {
+    key: input.key,
+    scope,
+    kind: input.kind,
+    requirement: input.requirement,
+    portability: input.portability,
+    hasDefault: input.defaultValue !== null && input.defaultValue.length > 0,
+    description: input.description,
+  };
+}
+
+function renderSecret(secret: CompanySecret): Record<string, unknown> {
+  return {
+    id: secret.id,
+    name: secret.name,
+    key: secret.key,
+    provider: secret.provider,
+    status: secret.status,
+    managedMode: secret.managedMode,
+    latestVersion: secret.latestVersion,
+    externalRef: secret.externalRef ? "yes" : "no",
+  };
+}
+
+function printProviderHealth(rows: SecretProviderHealth[], json: boolean): void {
+  if (json) {
+    printOutput(rows, { json: true });
+    return;
+  }
+  if (rows.length === 0) {
+    printOutput([], { json: false });
+    return;
+  }
+  for (const row of rows) {
+    console.log(
+      formatInlineRecord({
+        id: row.provider,
+        status: row.status,
+        message: row.message,
+      }),
+    );
+    for (const warning of row.warnings ?? []) {
+      console.log(pc.yellow(`warning=${warning}`));
+    }
+    const missingConfig = asStringArray(row.details?.missingConfig);
+    if (missingConfig.length > 0) {
+      console.log(pc.dim(`missingConfig=${missingConfig.join(",")}`));
+    }
+    const credentialSource = typeof row.details?.credentialSource === "string"
+      ? row.details.credentialSource
+      : null;
+    if (credentialSource) {
+      console.log(pc.dim(`credentialSource=${credentialSource}`));
+    }
+    const detectedCredentialSources = asStringArray(row.details?.detectedCredentialSources);
+    if (detectedCredentialSources.length > 0) {
+      console.log(pc.dim(`detectedCredentialSources=${detectedCredentialSources.join(",")}`));
+    }
+    for (const guidance of row.backupGuidance ?? []) {
+      console.log(pc.dim(`backup=${guidance}`));
+    }
+  }
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
+    : [];
+}
+
+async function migrateInlineEnv(opts: SecretMigrateInlineEnvOptions): Promise<void> {
+  const ctx = resolveCommandContext(opts, { requireCompany: true });
+  const companyId = ctx.companyId!;
+  const agents = (await ctx.api.get<Agent[]>(`/api/companies/${companyId}/agents`)) ?? [];
+  const secrets = (await ctx.api.get<CompanySecret[]>(`/api/companies/${companyId}/secrets`)) ?? [];
+  const candidates = collectInlineSecretMigrationCandidates(agents, secrets);
+
+  if (!opts.apply) {
+    printOutput(
+      {
+        apply: false,
+        agentsToUpdate: new Set(candidates.map((candidate) => candidate.agentId)).size,
+        secretsToCreate: candidates.filter((candidate) => !candidate.existingSecretId).length,
+        secretsToRotate: candidates.filter((candidate) => candidate.existingSecretId).length,
+        candidates,
+      },
+      { json: ctx.json },
+    );
+    if (!ctx.json) {
+      console.log(pc.dim("Re-run with --apply to create/rotate secrets and update agent env bindings."));
+    }
+    return;
+  }
+
+  const createdOrRotated = new Map<string, string>();
+  let createdSecrets = 0;
+  let rotatedSecrets = 0;
+
+  for (const candidate of candidates) {
+    const agent = agents.find((row) => row.id === candidate.agentId);
+    const env = asRecord(agent?.adapterConfig.env);
+    const value = env ? toPlainEnvValue(env[candidate.envKey]) : null;
+    if (!value) continue;
+
+    if (candidate.existingSecretId) {
+      await ctx.api.post(`/api/secrets/${candidate.existingSecretId}/rotate`, { value });
+      createdOrRotated.set(`${candidate.agentId}:${candidate.envKey}`, candidate.existingSecretId);
+      rotatedSecrets += 1;
+      continue;
+    }
+
+    const created = await ctx.api.post<CompanySecret>(`/api/companies/${companyId}/secrets`, {
+      name: candidate.secretName,
+      provider: "local_encrypted",
+      value,
+      description: `Migrated from agent ${candidate.agentId} env ${candidate.envKey}`,
+    });
+    if (!created) throw new Error(`Secret create returned no data for ${candidate.secretName}`);
+    createdOrRotated.set(`${candidate.agentId}:${candidate.envKey}`, created.id);
+    createdSecrets += 1;
+  }
+
+  let updatedAgents = 0;
+  for (const agent of agents) {
+    const env = asRecord(agent.adapterConfig.env);
+    if (!env) continue;
+    const secretIdByEnvKey = new Map<string, string>();
+    for (const [key] of Object.entries(env)) {
+      const secretId = createdOrRotated.get(`${agent.id}:${key}`);
+      if (secretId) secretIdByEnvKey.set(key, secretId);
+    }
+    if (secretIdByEnvKey.size === 0) continue;
+    const adapterConfig = {
+      ...agent.adapterConfig,
+      env: buildMigratedAgentEnv(env, secretIdByEnvKey),
+    };
+    await ctx.api.patch(`/api/agents/${agent.id}`, {
+      adapterConfig,
+      replaceAdapterConfig: true,
+    });
+    updatedAgents += 1;
+  }
+
+  printOutput(
+    {
+      apply: true,
+      updatedAgents,
+      createdSecrets,
+      rotatedSecrets,
+    },
+    { json: ctx.json },
+  );
+}
+
+export function registerSecretCommands(program: Command): void {
+  const secrets = program.command("secrets").description("Secret declaration and provider operations");
+
+  addCommonClientOptions(
+    secrets
+      .command("list")
+      .description("List secret metadata for a company")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .action(async (opts: SecretListOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const rows = (await ctx.api.get<CompanySecret[]>(`/api/companies/${ctx.companyId}/secrets`)) ?? [];
+          printOutput(ctx.json ? rows : rows.map(renderSecret), { json: ctx.json });
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    secrets
+      .command("declarations")
+      .description("List portable env declarations emitted by company export")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .option("--include <values>", "Comma-separated include set: company,agents,projects,issues,tasks,skills", "company,agents,projects")
+      .option("--kind <kind>", "Filter declarations: all | secret | plain", "all")
+      .action(async (opts: SecretDeclarationsOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const kind = opts.kind ?? "all";
+          if (!["all", "secret", "plain"].includes(kind)) {
+            throw new Error("Invalid --kind value. Use: all, secret, plain");
+          }
+          const preview = await ctx.api.post<CompanyPortabilityExportPreviewResult>(
+            `/api/companies/${ctx.companyId}/exports/preview`,
+            { include: parseSecretsInclude(opts.include) },
+          );
+          const declarations = (preview?.manifest.envInputs ?? [])
+            .filter((entry) => kind === "all" || entry.kind === kind);
+          printOutput(ctx.json ? declarations : declarations.map(renderDeclaration), { json: ctx.json });
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    secrets
+      .command("create")
+      .description("Create a Paperclip-managed secret")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .requiredOption("--name <name>", "Secret display name")
+      .option("--key <key>", "Portable secret key")
+      .option("--provider <provider>", "Secret provider id")
+      .option("--value <value>", "Secret value")
+      .option("--value-env <name>", "Read secret value from an environment variable")
+      .option("--description <text>", "Description")
+      .action(async (opts: SecretCreateOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const created = await ctx.api.post<CompanySecret>(`/api/companies/${ctx.companyId}/secrets`, {
+            name: opts.name,
+            key: opts.key,
+            provider: opts.provider,
+            value: readValueFromOptions(opts),
+            description: opts.description,
+          });
+          printOutput(ctx.json ? created : renderSecret(created!), { json: ctx.json });
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    secrets
+      .command("link")
+      .description("Link an external provider-owned secret without storing its value in Paperclip")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .requiredOption("--name <name>", "Secret display name")
+      .requiredOption("--provider <provider>", "Secret provider id")
+      .requiredOption("--external-ref <ref>", "Provider secret ARN/name/path/reference")
+      .option("--key <key>", "Portable secret key")
+      .option("--provider-version-ref <ref>", "Provider version id or label")
+      .option("--description <text>", "Description")
+      .action(async (opts: SecretLinkOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const created = await ctx.api.post<CompanySecret>(`/api/companies/${ctx.companyId}/secrets`, {
+            name: opts.name,
+            key: opts.key,
+            provider: opts.provider,
+            managedMode: "external_reference",
+            externalRef: opts.externalRef,
+            providerVersionRef: opts.providerVersionRef,
+            description: opts.description,
+          });
+          printOutput(ctx.json ? created : renderSecret(created!), { json: ctx.json });
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    secrets
+      .command("doctor")
+      .description("Run secret provider health checks through the Paperclip API")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .action(async (opts: SecretDoctorOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const health = await ctx.api.get<SecretProviderHealthResponse>(
+            `/api/companies/${ctx.companyId}/secret-providers/health`,
+          );
+          printProviderHealth(health?.providers ?? [], ctx.json);
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    secrets
+      .command("providers")
+      .description("List configured secret provider descriptors")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .action(async (opts: SecretDoctorOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const rows = (await ctx.api.get<SecretProviderDescriptor[]>(
+            `/api/companies/${ctx.companyId}/secret-providers`,
+          )) ?? [];
+          printOutput(rows, { json: ctx.json });
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    secrets
+      .command("migrate-inline-env")
+      .description("Migrate inline sensitive agent env values into secret references")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .option("--apply", "Persist changes; default is a dry run", false)
+      .action(async (opts: SecretMigrateInlineEnvOptions) => {
+        try {
+          await migrateInlineEnv(opts);
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+}

cli/src/config/home.ts

@@ -1,32 +1,31 @@
-import os from "node:os";
 import path from "node:path";
+import {
+  expandHomePrefix,
+  resolveDefaultBackupDir as resolveSharedDefaultBackupDir,
+  resolveDefaultEmbeddedPostgresDir as resolveSharedDefaultEmbeddedPostgresDir,
+  resolveDefaultLogsDir as resolveSharedDefaultLogsDir,
+  resolveDefaultSecretsKeyFilePath as resolveSharedDefaultSecretsKeyFilePath,
+  resolveDefaultStorageDir as resolveSharedDefaultStorageDir,
+  resolveHomeAwarePath,
+  resolvePaperclipConfigPathForInstance,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+  resolvePaperclipInstanceRoot as resolveSharedPaperclipInstanceRoot,
+} from "@paperclipai/shared/home-paths";
 
-const DEFAULT_INSTANCE_ID = "default";
-const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
-
-export function resolvePaperclipHomeDir(): string {
-  const envHome = process.env.PAPERCLIP_HOME?.trim();
-  if (envHome) return path.resolve(expandHomePrefix(envHome));
-  return path.resolve(os.homedir(), ".paperclip");
-}
-
-export function resolvePaperclipInstanceId(override?: string): string {
-  const raw = override?.trim() || process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
-  if (!INSTANCE_ID_RE.test(raw)) {
-    throw new Error(
-      `Invalid instance id '${raw}'. Allowed characters: letters, numbers, '_' and '-'.`,
-    );
-  }
-  return raw;
-}
+export {
+  expandHomePrefix,
+  resolveHomeAwarePath,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+};
 
 export function resolvePaperclipInstanceRoot(instanceId?: string): string {
-  const id = resolvePaperclipInstanceId(instanceId);
-  return path.resolve(resolvePaperclipHomeDir(), "instances", id);
+  return resolveSharedPaperclipInstanceRoot({ instanceId });
 }
 
 export function resolveDefaultConfigPath(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "config.json");
+  return resolvePaperclipConfigPathForInstance({ instanceId });
 }
 
 export function resolveDefaultContextPath(): string {
@@ -38,29 +37,23 @@ export function resolveDefaultCliAuthPath(): string {
 }
 
 export function resolveDefaultEmbeddedPostgresDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "db");
+  return resolveSharedDefaultEmbeddedPostgresDir({ instanceId });
 }
 
 export function resolveDefaultLogsDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "logs");
+  return resolveSharedDefaultLogsDir({ instanceId });
 }
 
 export function resolveDefaultSecretsKeyFilePath(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "secrets", "master.key");
+  return resolveSharedDefaultSecretsKeyFilePath({ instanceId });
 }
 
 export function resolveDefaultStorageDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "data", "storage");
+  return resolveSharedDefaultStorageDir({ instanceId });
 }
 
 export function resolveDefaultBackupDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "data", "backups");
-}
-
-export function expandHomePrefix(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
-  return value;
+  return resolveSharedDefaultBackupDir({ instanceId });
 }
 
 export function describeLocalInstancePaths(instanceId?: string) {

cli/src/index.ts

@@ -18,6 +18,7 @@ import { registerActivityCommands } from "./commands/client/activity.js";
 import { registerDashboardCommands } from "./commands/client/dashboard.js";
 import { registerRoutineCommands } from "./commands/routines.js";
 import { registerFeedbackCommands } from "./commands/client/feedback.js";
+import { registerSecretCommands } from "./commands/client/secrets.js";
 import { applyDataDirOverride, type DataDirOptionLike } from "./config/data-dir.js";
 import { loadPaperclipEnvFile } from "./config/env.js";
 import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
@@ -147,6 +148,7 @@ registerActivityCommands(program);
 registerDashboardCommands(program);
 registerRoutineCommands(program);
 registerFeedbackCommands(program);
+registerSecretCommands(program);
 registerWorktreeCommands(program);
 registerEnvLabCommands(program);
 registerPluginCommands(program);

cli/src/prompts/secrets.ts

@@ -32,7 +32,7 @@ export async function promptSecrets(current?: SecretsConfig): Promise<SecretsCon
       {
         value: "aws_secrets_manager" as const,
         label: "AWS Secrets Manager",
-        hint: "requires external adapter integration",
+        hint: "requires runtime AWS credentials and provider env config",
       },
       {
         value: "gcp_secret_manager" as const,
@@ -84,7 +84,9 @@ export async function promptSecrets(current?: SecretsConfig): Promise<SecretsCon
 
   if (provider !== "local_encrypted") {
     p.note(
-      `${provider} is not fully wired in this build yet. Keep local_encrypted unless you are actively implementing that adapter.`,
+      provider === "aws_secrets_manager"
+        ? "AWS credentials must come from the Paperclip server runtime (IAM role/workload identity, AWS_PROFILE/SSO/shared credentials, or short-lived shell env), not from Paperclip company secrets."
+        : `${provider} is not fully wired in this build yet. Keep local_encrypted unless you are actively implementing that adapter.`,
       "Heads up",
     );
   }

doc/CLI.md

@@ -143,6 +143,32 @@ pnpm paperclipai agent local-cli codexcoder --company-id <company-id>
 pnpm paperclipai agent local-cli claudecoder --company-id <company-id>
 ```
 
+## Secrets Commands
+
+```sh
+pnpm paperclipai secrets list --company-id <company-id>
+pnpm paperclipai secrets declarations --company-id <company-id> [--include agents,projects] [--kind secret]
+pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
+pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
+pnpm paperclipai secrets doctor --company-id <company-id>
+pnpm paperclipai secrets migrate-inline-env --company-id <company-id> [--apply]
+```
+
+Secret listing and declarations never print secret values. `create` accepts
+`--value-env` so shell history does not capture the value. `link` records
+provider-owned references without copying the secret value into Paperclip.
+For AWS-backed secrets, `secrets doctor` reports missing non-secret provider
+env and the expected AWS SDK runtime credential source; do not store AWS
+bootstrap credentials in Paperclip secrets.
+
+Per-company provider vaults (multiple vault instances per provider, default
+vault selection, coming-soon GCP/Vault) are configured from the board UI under
+`Company Settings → Secrets → Provider vaults` or through
+`/api/companies/{companyId}/secret-provider-configs`. There is no CLI surface
+for vault management today. See the
+[secrets deploy guide](../docs/deploy/secrets.md#provider-vaults) and
+[API reference](../docs/api/secrets.md#provider-vaults) for the contract.
+
 ## Approval Commands
 
 ```sh
@@ -178,7 +204,28 @@ pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhos
 
 ## Local Storage Defaults
 
-Default local instance root is `~/.paperclip/instances/default`:
+Local Paperclip data lives under the selected instance root. `PAPERCLIP_HOME` chooses the home directory and `PAPERCLIP_INSTANCE_ID` chooses the instance.
+
+```text
+~/.paperclip/                                     # PAPERCLIP_HOME
+└── instances/
+    └── default/                                  # instance root (PAPERCLIP_INSTANCE_ID)
+        ├── config.json                           # runtime config
+        ├── .env                                  # instance env file
+        ├── db/                                   # embedded PostgreSQL data
+        ├── data/
+        │   ├── storage/                          # local_disk uploads
+        │   └── backups/                          # automatic DB backups
+        ├── logs/
+        ├── secrets/
+        │   └── master.key                        # local_encrypted master key
+        ├── workspaces/                           # default agent workspaces
+        ├── projects/                             # project execution workspaces
+        ├── companies/                            # per-company adapter homes (e.g. codex-home)
+        └── codex-home/                           # per-instance codex home (when not company-scoped)
+```
+
+Default paths for the canonical install:
 
 - config: `~/.paperclip/instances/default/config.json`
 - embedded db: `~/.paperclip/instances/default/db`

doc/DATABASE.md

@@ -171,6 +171,8 @@ For local/default installs, the active provider is `local_encrypted`:
 - Secret material is encrypted at rest with a local master key.
 - Default key file: `~/.paperclip/instances/default/secrets/master.key` (auto-created if missing).
 - CLI config location: `~/.paperclip/instances/default/config.json` under `secrets.localEncrypted.keyFilePath`.
+- Backup/restore requires both the database metadata and the local master key file; either artifact alone is insufficient.
+- The server best-effort enforces `0600` key file permissions and provider health reports permission warnings.
 
 Optional overrides:
 
@@ -192,5 +194,10 @@ pnpm paperclipai configure --section secrets
 Inline secret migration command:
 
 ```sh
+pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+
+# direct database maintenance fallback
 pnpm secrets:migrate-inline-env --apply
 ```
+
+Hosted AWS provider notes live in [SECRETS-AWS-PROVIDER.md](./SECRETS-AWS-PROVIDER.md).

doc/DEVELOPING.md

@@ -157,6 +157,27 @@ See `doc/DOCKER.md` for API key wiring (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`)
 
 For a separate review-oriented container that keeps `codex`/`claude` login state in Docker volumes and checks out PRs into an isolated scratch workspace, see `doc/UNTRUSTED-PR-REVIEW.md`.
 
+## Local Instance Layout
+
+Every local install keeps runtime state directly under the selected instance root:
+
+```text
+~/.paperclip/instances/default/                  # instance root
+  config.json                                    # runtime config
+  .env                                           # instance env file
+  db/                                            # embedded PostgreSQL data
+  data/
+    storage/                                     # local_disk uploads
+    backups/                                     # automatic DB backups
+  logs/
+  secrets/master.key                             # local_encrypted master key
+  workspaces/<agent-id>/                         # default agent workspaces
+  projects/                                      # project execution workspaces
+  companies/<company-id>/codex-home/             # per-company codex_local home
+```
+
+`PAPERCLIP_HOME` and `PAPERCLIP_INSTANCE_ID` override the home root and instance id respectively. `paperclipai onboard` echoes the resolved values in its banner (`Local home: <home> | instance: <id> | config: <path>`) so you can confirm where state will land before continuing.
+
 ## Database in Dev (Auto-Handled)
 
 For local development, leave `DATABASE_URL` unset.
@@ -164,7 +185,7 @@ The server will automatically use embedded PostgreSQL and persist data at:
 
 - `~/.paperclip/instances/default/db`
 
-Override home and instance:
+Override home or instance:
 
 ```sh
 PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
@@ -280,7 +301,7 @@ paperclipai worktree init --from-data-dir ~/.paperclip
 paperclipai worktree init --force
 ```
 
-Repair an already-created repo-managed worktree and reseed its isolated instance from the main default install:
+Repair an already-created repo-managed worktree and reseed its isolated instance from the main default install. Point `--from-config` at the instance config:
 
 ```sh
 cd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component
@@ -462,6 +483,7 @@ Agent env vars now support secret references. By default, secret values are stor
 - Default local key path: `~/.paperclip/instances/default/secrets/master.key`
 - Override key material directly: `PAPERCLIP_SECRETS_MASTER_KEY`
 - Override key file path: `PAPERCLIP_SECRETS_MASTER_KEY_FILE`
+- Back up the key file and database together; either one alone is not enough to restore local encrypted secrets.
 
 Strict mode (recommended outside local trusted machines):
 
@@ -470,12 +492,20 @@ PAPERCLIP_SECRETS_STRICT_MODE=true
 ```
 
 When strict mode is enabled, sensitive env keys (for example `*_API_KEY`, `*_TOKEN`, `*_SECRET`) must use secret references instead of inline plain values.
+Authenticated deployments default strict mode on unless explicitly overridden.
 
 CLI configuration support:
 
 - `pnpm paperclipai onboard` writes a default `secrets` config section (`local_encrypted`, strict mode off, key file path set) and creates a local key file when needed.
 - `pnpm paperclipai configure --section secrets` lets you update provider/strict mode/key path and creates the local key file when needed.
-- `pnpm paperclipai doctor` validates secrets adapter configuration and can create a missing local key file with `--repair`.
+- `pnpm paperclipai doctor` validates secrets adapter configuration, can create a missing local key file with `--repair`, and reports missing AWS Secrets Manager bootstrap env when that provider is selected.
+- Provider health is available at `GET /api/companies/:companyId/secret-providers/health` and reports local key permission warnings plus backup guidance.
+
+Per-company provider vaults are configured in the board UI under
+`Company Settings → Secrets → Provider vaults`, backed by
+`/api/companies/{companyId}/secret-provider-configs`. The CLI does not own
+vault lifecycle today. See `docs/deploy/secrets.md` (`Provider Vaults` section)
+for the operator model.
 
 Migration helper for existing inline env secrets:
 

doc/PUBLISHING.md

@@ -176,6 +176,58 @@ That means:
 
 See [doc/RELEASE-AUTOMATION-SETUP.md](RELEASE-AUTOMATION-SETUP.md) for the GitHub/npm setup steps.
 
+## Release enrollment for new public packages
+
+Paperclip does not auto-publish every non-private workspace package anymore.
+CI publishing is controlled by [`scripts/release-package-manifest.json`](../scripts/release-package-manifest.json).
+
+When you add a new public package:
+
+1. add it to the manifest and decide whether CI should publish it immediately
+2. if CI should publish it, bootstrap the package on npm before merge
+3. if CI should not publish it yet, keep `"publishFromCi": false`
+4. only enable `"publishFromCi": true` after npm trusted publishing is configured for that package
+
+PR CI now checks changed release-enabled package manifests against npm. That catches a missing first-publish bootstrap before the change reaches `master`.
+
+### One-time bootstrap sequence for a new package
+
+The first publish of a brand-new package still needs one human maintainer with npm write access.
+After that, trusted publishing can take over.
+
+Example for `@paperclipai/adapter-acpx-local` from the repo root:
+
+```bash
+# safe preview
+pnpm run release:bootstrap-package -- @paperclipai/adapter-acpx-local
+
+# one-time first publish from an authenticated maintainer machine
+pnpm run release:bootstrap-package -- @paperclipai/adapter-acpx-local --publish --otp 123456
+```
+
+The helper script:
+
+- checks that the package does not already exist on npm
+- builds the target package unless `--skip-build` is passed
+- runs `npm pack --dry-run` in the package directory
+- only runs the real `npm publish --access public` when `--publish --otp <code>` is provided
+
+For the real `--publish` step, the maintainer machine must already be authenticated to npm.
+If `npm whoami` returns `401`, first run `npm logout --registry=https://registry.npmjs.org/` to clear any stale local auth, then run `npm login` or `npm adduser` locally as an npm org member, and finally rerun the helper.
+That local human auth is fine for the one-time bootstrap publish; we just do not want the same auth model inside CI.
+The helper now requires `--otp <code>` up front for `--publish`, so it fails before the real publish attempt if the one-time password is missing.
+
+After that first publish succeeds:
+
+1. open `https://www.npmjs.com/package/@paperclipai/adapter-acpx-local`
+2. go to `Settings` → `Trusted publishing`
+3. add repository `paperclipai/paperclip`
+4. set workflow filename to `release.yml`
+5. optionally go to `Settings` → `Publishing access` and enable `Require two-factor authentication and disallow tokens`
+6. keep `publishFromCi: true` in [`scripts/release-package-manifest.json`](../scripts/release-package-manifest.json)
+
+Once those steps are done, future canary and stable publishes for that package are automated through GitHub OIDC. The manual step is only the first package creation on npm.
+
 ## Rollback model
 
 Rollback does not unpublish anything.

doc/RELEASE-AUTOMATION-SETUP.md

@@ -67,6 +67,27 @@ Why:
 - the single `release.yml` workflow handles both canary and stable publishing
 - GitHub environments `npm-canary` and `npm-stable` still enforce different approval rules on the GitHub side
 
+### 2.2.1. Newly added public packages need a bootstrap phase
+
+Trusted publishing is configured on the npm package itself, not at the repo scope.
+That means a brand-new public package must not be auto-enrolled into CI publishing until its npm package exists and its trusted publisher has been configured.
+
+Repo policy:
+
+1. add every non-private package to [`scripts/release-package-manifest.json`](../scripts/release-package-manifest.json)
+2. set `"publishFromCi": true` only when CI is expected to publish that package
+3. if the package is not ready for CI publishing yet, keep `"publishFromCi": false`
+4. complete the package bootstrap before merging any PR that changes a release-enabled new package
+
+Bootstrap sequence for a new package:
+
+1. publish the package once from a trusted maintainer machine using normal npm auth
+2. open that package on npm and add the `paperclipai/paperclip` trusted publisher for `.github/workflows/release.yml`
+3. rerun or dry-run the release flow as needed to confirm CI publishing now works
+4. only then enable `"publishFromCi": true`
+
+PR CI enforces this by checking changed release-enabled package manifests against npm. That keeps `master` canary publishing healthy while preserving the no-long-lived-token model for normal CI releases.
+
 ### 2.3. Verify trusted publishing before removing old auth
 
 After the workflows are live:

doc/SECRETS-AWS-PROVIDER.md

@@ -0,0 +1,368 @@
+# AWS Secrets Manager Provider
+
+Operational contract for the hosted `aws_secrets_manager` secret provider used by Paperclip Cloud.
+
+## Scope
+
+- Hosted provider for Paperclip-managed secrets when Paperclip Cloud runs on AWS.
+- Source of truth for secret values is AWS Secrets Manager, not Postgres.
+- Paperclip stores only metadata needed for ownership, bindings, version selection, audit, and runtime resolution.
+- AWS provider bootstrap credentials are deployment/runtime credentials, not Paperclip-managed company secrets.
+- Remote import for existing AWS secrets is metadata-only. Preview/import uses
+  AWS inventory metadata and creates Paperclip external references; it does not
+  copy plaintext into Paperclip.
+- Per-company AWS provider vaults (named instances of `aws_secrets_manager`
+  with their own region, namespace, prefix, KMS key id, and tags) are managed
+  in the board UI under `Company Settings → Secrets → Provider vaults`. See
+  [Provider Vaults](../docs/deploy/secrets.md#provider-vaults) for the operator
+  model and [Provider Vaults API](../docs/api/secrets.md#provider-vaults) for
+  the routes. The bootstrap trust model in this document still applies — vault
+  config carries non-sensitive routing metadata only, never AWS credentials.
+
+## Bootstrap Trust Model
+
+The AWS provider has a chicken-and-egg boundary: Paperclip cannot use
+`company_secrets` to unlock the AWS provider that stores those secrets. The
+initial AWS trust must exist before the Paperclip server starts.
+
+Allowed bootstrap locations:
+
+- Infrastructure IAM or workload identity attached to the Paperclip server
+  runtime.
+- Process environment or orchestrator secret store used to start the Paperclip
+  server.
+- Local AWS SDK sources such as `AWS_PROFILE`, AWS SSO/shared config, web
+  identity, container metadata, or instance metadata.
+- Short-lived shell credentials for local development only.
+
+Do not ask operators to paste AWS root credentials or long-lived IAM user access
+keys into the Paperclip board UI. Do not store those bootstrap keys in
+`company_secrets`.
+
+## Paperclip Cloud Bootstrap
+
+Paperclip Cloud must provision the AWS backing resources before any board user
+can create AWS-backed company secrets:
+
+1. Create or select the deployment KMS key.
+2. Create the Paperclip server runtime role for the deployment.
+3. Attach a minimum IAM policy scoped to the deployment Secrets Manager prefix
+   and the configured KMS key.
+4. Configure the server runtime with the non-secret provider environment
+   variables below.
+5. Run `paperclipai doctor` or the provider health endpoint from the deployed
+   runtime and confirm that the provider reports the expected region, prefix,
+   deployment id, KMS setting, and AWS SDK credential source.
+
+Once this is in place, the board UI can create Paperclip-managed AWS secrets and
+Paperclip will write them under the deployment/company namespace.
+
+## Self-Hosted And Local Bootstrap
+
+Self-hosted AWS deployments should use the AWS SDK default credential provider
+chain. Preferred sources are role-based:
+
+- EC2 instance profile.
+- ECS task role.
+- EKS IRSA or another OIDC web identity role.
+- AWS SSO/shared config via `AWS_PROFILE`.
+
+Local development can use:
+
+```sh
+aws sso login --profile paperclip-dev
+AWS_PROFILE=paperclip-dev \
+PAPERCLIP_SECRETS_PROVIDER=aws_secrets_manager \
+PAPERCLIP_SECRETS_AWS_REGION=us-east-1 \
+PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID=dev-local \
+PAPERCLIP_SECRETS_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/abcd-... \
+pnpm dev
+```
+
+Temporary `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY` environment credentials
+are acceptable only as a local break-glass or short-lived test source. They
+should not be written to Paperclip config, committed to `.env` files, stored in
+`company_secrets`, or used as the default Paperclip Cloud bootstrap path.
+
+## Deployment Config
+
+Required environment variables:
+
+```sh
+PAPERCLIP_SECRETS_PROVIDER=aws_secrets_manager
+PAPERCLIP_SECRETS_AWS_REGION=us-east-1
+PAPERCLIP_SECRETS_AWS_DEPLOYMENT_ID=prod-us-1
+PAPERCLIP_SECRETS_AWS_KMS_KEY_ID=arn:aws:kms:us-east-1:123456789012:key/abcd-...
+```
+
+Optional environment variables:
+
+```sh
+PAPERCLIP_SECRETS_AWS_PREFIX=paperclip
+PAPERCLIP_SECRETS_AWS_ENVIRONMENT=production
+PAPERCLIP_SECRETS_AWS_PROVIDER_OWNER=paperclip
+PAPERCLIP_SECRETS_AWS_ENDPOINT=
+PAPERCLIP_SECRETS_AWS_DELETE_RECOVERY_DAYS=30
+```
+
+Naming convention for Paperclip-managed secrets:
+
+```text
+paperclip/{deploymentId}/{companyId}/{secretKey}
+```
+
+Tag set for Paperclip-managed secrets:
+
+- `paperclip:managed-by=paperclip`
+- `paperclip:provider-owner=<owner tag>`
+- `paperclip:deployment-id=<deployment id>`
+- `paperclip:company-id=<company id>`
+- `paperclip:secret-key=<secret key>`
+- `paperclip:environment=<environment tag>`
+
+## IAM And KMS Assumptions
+
+Launch posture:
+
+- One Paperclip app role per deployment.
+- One deployment-scoped KMS key per deployment at launch.
+- Future per-company KMS keys remain compatible because Paperclip stores provider refs and version metadata separately from values.
+
+Minimum IAM boundary:
+
+- Allow `secretsmanager:CreateSecret`, `PutSecretValue`, `GetSecretValue`, and `DeleteSecret`.
+- Scope resources to the deployment prefix:
+
+```text
+arn:aws:secretsmanager:<region>:<account-id>:secret:paperclip/<deployment-id>/*
+```
+
+- Allow `kms:Encrypt`, `kms:Decrypt`, `kms:GenerateDataKey`, and `kms:DescribeKey` for the configured deployment CMK.
+- Deny wildcard access outside the deployment prefix.
+- Prefer workload identity / role-based auth. Do not store AWS credentials inline in Paperclip config.
+
+Example minimum policy shape:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "PaperclipDeploymentSecrets",
+      "Effect": "Allow",
+      "Action": [
+        "secretsmanager:CreateSecret",
+        "secretsmanager:PutSecretValue",
+        "secretsmanager:GetSecretValue",
+        "secretsmanager:DeleteSecret"
+      ],
+      "Resource": "arn:aws:secretsmanager:<region>:<account-id>:secret:paperclip/<deployment-id>/*"
+    },
+    {
+      "Sid": "PaperclipDeploymentKms",
+      "Effect": "Allow",
+      "Action": [
+        "kms:Encrypt",
+        "kms:Decrypt",
+        "kms:GenerateDataKey",
+        "kms:DescribeKey"
+      ],
+      "Resource": "arn:aws:kms:<region>:<account-id>:key/<key-id>"
+    }
+  ]
+}
+```
+
+Operational expectation:
+
+- Paperclip-managed secrets may be deleted only by Paperclip or an operator with equivalent break-glass access.
+- External references may resolve through Paperclip runtime, but Paperclip should not delete the external secret resource.
+
+## Remote Import Inventory IAM
+
+Remote import preview needs one additional AWS permission:
+
+```json
+{
+  "Sid": "PaperclipRemoteSecretInventory",
+  "Effect": "Allow",
+  "Action": "secretsmanager:ListSecrets",
+  "Resource": "*"
+}
+```
+
+This is intentionally separate from the managed create/rotate/delete policy.
+AWS treats `ListSecrets` as an account/Region inventory action; do not document
+secret ARNs, names, tags, or AWS request filters as an IAM boundary for it. Use
+`Resource: "*"` and decide whether inventory exposure is acceptable for the AWS
+account and Region behind each provider vault.
+
+Remote import preview/import must not call:
+
+- `secretsmanager:GetSecretValue`
+- `secretsmanager:BatchGetSecretValue`
+- `kms:Decrypt`
+
+Those permissions are only needed later when a bound runtime resolves an
+imported external reference. For imported refs, scope read permissions to the
+operator-approved external prefixes that Paperclip is allowed to consume:
+
+```json
+{
+  "Sid": "PaperclipResolveImportedExternalReferences",
+  "Effect": "Allow",
+  "Action": "secretsmanager:GetSecretValue",
+  "Resource": [
+    "arn:aws:secretsmanager:<region>:<account-id>:secret:<approved-external-prefix>/*"
+  ]
+}
+```
+
+If selected external secrets use customer-managed KMS keys, also grant
+`kms:Decrypt` and `kms:DescribeKey` on those keys. Keep managed write/delete
+permissions scoped to `paperclip/<deployment-id>/*`; do not broaden them for
+remote import.
+
+Safe scoping guidance:
+
+- Prefer one Paperclip runtime role per environment/account.
+- Point provider vaults at the intended AWS account and Region instead of a
+  broad central admin role.
+- Enable `ListSecrets` only in accounts where inventory exposure is acceptable.
+- Keep preview/import board-only; agent API keys must not call these routes.
+- Treat AWS tag/name filters as search UX only, not permission enforcement.
+
+Paperclip also blocks importing refs under its own managed namespace as
+external references. Use the Paperclip-managed flow for
+`paperclip/{deploymentId}/{companyId}/{secretKey}` resources.
+
+## Existing AWS Secrets
+
+V1 keeps existing AWS Secrets Manager entries as **linked external references**, not adopted
+Paperclip-managed resources.
+
+Use the Paperclip-managed flow when Paperclip should create and rotate the value. The AWS
+secret name is derived from deployment and company scope:
+
+```text
+paperclip/{deploymentId}/{companyId}/{secretKey}
+```
+
+Use the external-reference flow when the secret already exists at an operator-owned path such
+as:
+
+```text
+/paperclip-bench/anthropic_api_key
+```
+
+In that mode Paperclip stores only the path or ARN, resolves it at runtime, and records
+redacted access events. Operators rotate the actual value in AWS. Update the Paperclip
+reference only when the AWS path, ARN, or pinned provider version changes.
+
+Paperclip does not currently offer an "adopt existing AWS secret" flow that takes over future
+`PutSecretValue` writes for an arbitrary existing secret. Adding that later requires explicit
+confirmation UX, scope validation, expected Paperclip tags, and security/cloud-ops review.
+
+## Data Custody
+
+- Paperclip stores `externalRef`, `providerVersionRef`, provider id, fingerprint hash, status, and binding metadata.
+- Paperclip does not store AWS secret plaintext in `company_secret_versions.material`.
+- Runtime resolution fetches the value from AWS only when a bound consumer needs it.
+
+## Rotation Runbook
+
+Manual Paperclip-managed rotation:
+
+1. Write the new value through the Paperclip secret rotate flow.
+2. Paperclip creates a new AWS secret version with `PutSecretValue`.
+3. Paperclip records the new `providerVersionRef` in `company_secret_versions`.
+4. Re-run or restart affected workloads that consume `latest`, or pin consumers to a specific Paperclip version before rollout when you need staged release safety.
+
+Guidance:
+
+- Prefer pinned Paperclip secret versions for risky rollouts.
+- Treat provider-native automatic rotation as a later enhancement; current V1 flow is explicit create-new-version plus controlled rollout.
+
+## Backup And Restore Runbook
+
+What must survive:
+
+- Paperclip database metadata for secret ownership, bindings, status, and provider version refs.
+- AWS Secrets Manager namespace under the configured deployment prefix.
+- The configured KMS key and its decrypt permissions.
+
+Restore checklist:
+
+1. Restore Paperclip database metadata.
+2. Confirm the same AWS Secrets Manager namespace still exists.
+3. Confirm the Paperclip runtime role can call `GetSecretValue` on the restored prefix.
+4. Confirm the role still has decrypt access to the CMK referenced by `PAPERCLIP_SECRETS_AWS_KMS_KEY_ID`.
+5. Run the live smoke below or a targeted runtime secret resolution test.
+
+## Provider Outage Runbook
+
+Symptoms:
+
+- Secret create/rotate/resolve operations fail with AWS provider errors.
+- Agent runs fail before adapter invocation on required secret resolution.
+- Remote import preview fails to list AWS inventory.
+
+Immediate actions:
+
+1. Confirm AWS regional health and Secrets Manager availability.
+2. Confirm the runtime role still has `GetSecretValue` and KMS decrypt permissions.
+3. Check for accidental prefix, region, deployment id, or KMS key config drift.
+4. Retry a single resolution after AWS service health is green.
+5. If outage persists, pause high-risk runs that require secret access rather than churning retries.
+
+Remote import-specific actions:
+
+- Missing list permission: add `secretsmanager:ListSecrets` with
+  `Resource: "*"` only when inventory import is approved for that vault's
+  AWS account and Region.
+- Throttling: narrow the search, wait briefly, and retry with backoff. Avoid
+  full-account enumeration.
+- Invalid or stale cursor: refresh the preview and discard the old
+  `NextToken`.
+- Large account: load pages intentionally, keep one in-flight preview request
+  per vault/search, and do not run background full-account crawls.
+- Runtime read failure after import: verify `GetSecretValue` and KMS decrypt
+  on the selected external secret. Visibility in `ListSecrets` does not prove
+  read permission.
+
+## Incident Response Runbook
+
+Potential incidents:
+
+- Cross-company access caused by IAM scoping drift.
+- KMS policy drift causing decrypt failures or over-broad access.
+- Suspected secret exposure in logs, transcripts, or downstream agent output.
+
+Response steps:
+
+1. Stop or pause affected Paperclip runs.
+2. Audit recent Paperclip secret access events for impacted secret ids and consumers.
+3. Audit AWS CloudTrail for `ListSecrets`, `GetSecretValue`,
+   `PutSecretValue`, and `DeleteSecret` calls on the relevant vault account,
+   Region, deployment prefix, and approved external prefixes.
+4. Rotate impacted secrets in AWS through Paperclip-managed versioning.
+5. Re-scope IAM and KMS policies before resuming normal traffic.
+6. If a value may have reached an agent transcript or external system, treat it as exposed and rotate immediately.
+
+## Optional Live Smoke
+
+This is safe to skip locally. Run it only against a dedicated AWS test namespace.
+
+Prerequisites:
+
+- AWS credentials or workload identity with the deployment-scoped IAM permissions above.
+- `PAPERCLIP_SECRETS_PROVIDER=aws_secrets_manager`
+- The required `PAPERCLIP_SECRETS_AWS_*` environment variables set.
+
+Suggested smoke:
+
+1. Create a test secret through the Paperclip board or API under a throwaway company.
+2. Confirm the resulting AWS secret name matches `paperclip/{deploymentId}/{companyId}/{secretKey}`.
+3. Rotate the secret once and confirm a new `providerVersionRef` appears in Paperclip metadata.
+4. Resolve the secret through a bound runtime path, not by adding a general-purpose reveal endpoint.
+5. Delete the throwaway secret and confirm AWS schedules deletion with the configured recovery window.

doc/execution-semantics.md

@@ -67,13 +67,15 @@ This is the right state for:
 
 - waiting on another issue
 - waiting on a human decision
-- waiting on an external dependency or system
+- waiting on an external dependency or system when Paperclip does not own a scheduled re-check
 - work that automatic recovery could not safely continue
 
 ### `in_review`
 
 Execution work is paused because the next move belongs to a reviewer or approver, not the current executor.
 
+An external review service can also be a valid review path when the issue keeps an agent assignee and has an active one-shot monitor that will wake that assignee to check the service later.
+
 ### `done`
 
 The work is complete and terminal.
@@ -164,6 +166,7 @@ The valid action-path primitives are:
 - a queued wake or continuation that can be delivered to the responsible agent
 - a typed execution-policy participant, such as `executionState.currentParticipant`
 - a pending issue-thread interaction or linked approval that is waiting for a specific responder
+- a one-shot issue monitor (`executionPolicy.monitor.nextCheckAt`) that will wake the assignee for a future check
 - a human owner via `assigneeUserId`
 - a first-class blocker chain whose unresolved leaf issues are themselves healthy
 - an open explicit recovery issue that names the owner and action needed to restore liveness
@@ -180,6 +183,16 @@ A healthy dispatch state means at least one of these is true:
 
 An assigned `todo` issue is stalled when dispatch was interrupted, no wake remains queued or running, and no recovery path has been opened.
 
+### Agent-assigned `backlog`
+
+This is parked state, not dispatch state.
+
+Assigning an issue normally implies executable intent. When create APIs receive an assignee and no explicit status, Paperclip defaults the issue to `todo` so the assignee has a wake path instead of silently inheriting the unassigned `backlog` default.
+
+An explicit assigned `backlog` issue remains valid when the creator is deliberately parking the work. It must not wake the assignee just because it has an assignee. Paperclip should make that choice visible in activity and UI so operators can distinguish intentional parking from a missed handoff.
+
+An assigned `backlog` issue becomes a liveness problem when another issue is blocked on it and there is no explicit waiting path such as a human owner, active run, queued wake, pending interaction or approval, monitor, or open recovery issue. In that case the blocked parent should surface "blocked by parked work" rather than treating the dependency chain as healthy.
+
 ### Agent-assigned `in_progress`
 
 This is active-work state.
@@ -188,6 +201,7 @@ A healthy active-work state means at least one of these is true:
 
 - there is an active run for the issue
 - there is already a queued continuation wake
+- there is an active one-shot monitor that will wake the assignee for a future check
 - there is an open explicit recovery issue for the lost execution path
 
 An agent-owned `in_progress` issue is stalled when it has no active run, no queued continuation, and no explicit recovery surface. A still-running but silent process is not automatically stalled; it is handled by the active-run watchdog contract.
@@ -202,11 +216,34 @@ A healthy `in_review` issue has at least one valid action path:
 - a pending issue-thread interaction or linked approval waiting for a named responder
 - a human owner via `assigneeUserId`
 - an active run or queued wake that is expected to process the review state
+- an active one-shot monitor for an external service or async review loop that the assignee owns
 - an open explicit recovery issue for an ambiguous review handoff
 
 Agent-assigned `in_review` with no typed participant is only healthy when one of the other paths exists. Assignment to the same agent that produced the handoff is not, by itself, a review path.
 
-An `in_review` issue is stalled when it has no typed participant, no pending interaction or approval, no user owner, no active run, no queued wake, and no explicit recovery issue. Paperclip should surface that state as recovery work rather than silently completing the issue or leaving blocker chains parked indefinitely.
+An `in_review` issue is stalled when it has no typed participant, no pending interaction or approval, no user owner, no active monitor, no active run, no queued wake, and no explicit recovery issue. Paperclip should surface that state as recovery work rather than silently completing the issue or leaving blocker chains parked indefinitely.
+
+### Issue monitors
+
+An issue monitor is a one-shot deferred action path for agent-owned issues in `in_progress` or `in_review`.
+
+Use a monitor when the current assignee owns a future check against an async system or external service. Examples include Greptile review loops, GitHub checks, Vercel deployments, or provider jobs where the agent should come back later and decide what happens next.
+
+Monitor policy lives under `executionPolicy.monitor` and includes:
+
+- `nextCheckAt`: when Paperclip should wake the assignee
+- `notes`: non-secret instructions for what the assignee should check
+- `serviceName`: optional non-secret external-service context
+- `externalRef`: optional external-service reference input; Paperclip treats it as secret-adjacent, redacts it before persistence/visibility, and omits it from activity and wake payloads
+- `timeoutAt`, `maxAttempts`, and `recoveryPolicy`: optional recovery hints for bounded waits
+
+Monitors are not recurring intervals. When a monitor fires, Paperclip clears the scheduled monitor and queues an `issue_monitor_due` wake for the assignee. If the external service is still pending, the assignee must explicitly re-arm the monitor with a new `nextCheckAt`. If the issue moves to `done`, `cancelled`, an invalid status, or a human/unassigned owner, the monitor is cleared.
+
+Because `serviceName` and `notes` remain visible in issue activity and wake context, operators should keep them short and non-secret. Put enough context for the assignee to know what to inspect, but do not include signed URLs, bearer tokens, customer secrets, tenant-private identifiers, or provider links with embedded credentials.
+
+Monitor bounds are enforced. Paperclip rejects attempts to re-arm a monitor whose `timeoutAt` or `maxAttempts` is already exhausted. When a scheduled monitor reaches an exhausted bound at trigger time, Paperclip clears it and follows `recoveryPolicy`: `wake_owner` queues a bounded recovery wake for the assignee, `create_recovery_issue` opens visible recovery work, and `escalate_to_board` records a board-visible escalation comment/activity.
+
+Use `blocked` instead of a monitor when no Paperclip assignee owns a responsible polling path. In that case, name the external owner/action or create first-class recovery/blocker work.
 
 ### `blocked`
 

doc/plans/2026-04-26-plugin-secret-ref-company-scope.md

@@ -0,0 +1,86 @@
+# Plugin Secret Refs: Company Scope Reintroduction Plan
+
+Date: 2026-04-26
+Status: follow-up after fail-closed mitigation
+Related issue: PAP-2394
+
+## Current state
+
+`PAP-2394` now fails closed:
+
+- `POST /api/plugins/:pluginId/config` rejects any config containing plugin secret refs.
+- `ctx.secrets.resolve()` is disabled for plugin workers.
+
+This removes the release-blocking cross-company exposure path, but it also disables plugin secret-ref support until the runtime carries company scope end to end.
+
+## Vulnerability summary
+
+The original design mixed an instance-global config store with company-scoped secret bindings:
+
+- [server/src/routes/plugins.ts](/Users/dotta/paperclip/.paperclip/worktrees/PAP-2339-secrets-make-a-plan/server/src/routes/plugins.ts:1898) saved one global plugin config row, then wrote bindings into `company_secret_bindings` grouped by each referenced secret's owning company.
+- [packages/db/src/schema/plugin_config.ts](/Users/dotta/paperclip/.paperclip/worktrees/PAP-2339-secrets-make-a-plan/packages/db/src/schema/plugin_config.ts:15) stored one config row per plugin, with no company dimension.
+- [packages/db/src/schema/company_secret_bindings.ts](/Users/dotta/paperclip/.paperclip/worktrees/PAP-2339-secrets-make-a-plan/packages/db/src/schema/company_secret_bindings.ts:5) already modeled bindings as company-scoped.
+- [server/src/services/plugin-secrets-handler.ts](/Users/dotta/paperclip/.paperclip/worktrees/PAP-2339-secrets-make-a-plan/server/src/services/plugin-secrets-handler.ts:212) resolved by `pluginId` + secret UUID, with no active company context from the bridge call.
+- [packages/plugins/sdk/src/worker-rpc-host.ts](/Users/dotta/paperclip/.paperclip/worktrees/PAP-2339-secrets-make-a-plan/packages/plugins/sdk/src/worker-rpc-host.ts:384) exposed `ctx.config.get()` and `ctx.secrets.resolve()` without a company parameter.
+
+This violated Least Privilege, Complete Mediation, and Secure Defaults.
+
+## Recommended end state
+
+Re-enable plugin secret refs only after both of these are true:
+
+1. Plugin config reads/writes are company-scoped.
+2. Runtime secret resolution carries explicit company context and enforces it at resolution time.
+
+## Implementation plan
+
+### 1. Make plugin config company-scoped
+
+- Add `company_id` to `plugin_config`, with a unique index on `(plugin_id, company_id)`.
+- Update registry helpers to require `companyId` for `getConfig`, `upsertConfig`, `patchConfig`, and `deleteConfig`.
+- Update plugin config routes to require `companyId` and call `assertCompanyAccess(req, companyId)`.
+- Keep instance-global plugin lifecycle state separate from company-scoped plugin config.
+
+### 2. Propagate company context through the worker runtime
+
+- Extend the SDK so `ctx.config.get()` and `ctx.secrets.resolve()` can receive or derive `companyId`.
+- Introduce worker request context storage for handlers that already run with company scope:
+  - `getData`
+  - `performAction`
+  - scoped API routes
+  - tool executions
+  - environment driver calls
+- Fail closed when plugin code tries to read company-scoped config or secrets outside an active company context.
+
+### 3. Rebind secrets by `(companyId, pluginId, configPath)`
+
+- On config save, validate every referenced secret belongs to the authorized company.
+- Store bindings only for that company.
+- Resolve secrets only by the current company-scoped binding, never by bare plugin ID plus UUID.
+- Treat stale bindings as invalid and remove them on config replacement.
+
+### 4. Prevent cross-company config disclosure
+
+- When returning config to the UI, only materialize the selected company's secret refs.
+- Never expose another company's secret UUIDs through the global plugin config surface.
+
+## Required regression coverage
+
+- Company A board user cannot save plugin config that references a Company B secret.
+- Company A plugin execution cannot resolve a Company B secret even if the same plugin is configured for Company B.
+- Company-scoped config reads only return the selected company's secret bindings.
+- Config replacement removes stale bindings for the same `(companyId, pluginId)` target.
+- Runtime calls without company context fail closed.
+
+## Migration notes
+
+- Existing `plugin_config` rows need a migration strategy before re-enable.
+- Safest default: do not auto-assume a company for historical secret refs.
+- Prefer one of:
+  - explicit admin migration per company, or
+  - import existing rows as non-secret config only and require re-entry of secret refs.
+
+## Release posture
+
+- Keep plugin secret refs disabled until all steps above land.
+- Do not restore the feature behind a soft warning; the insecure path must remain unavailable by default.

doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md

@@ -0,0 +1,135 @@
+# LLM Wiki Paperclip Asset And Work-Product Security Gate
+
+Status: accepted Phase 5 policy
+Date: 2026-05-06
+Owner: Security engineering
+Scope: Paperclip-derived ingestion into the LLM Wiki before any asset or work-product content indexing ships
+
+## Decision
+
+Phase 5 remains **fail-closed** for Paperclip assets and work products.
+
+- Paperclip-derived **text extraction is allowed only** for issue titles/descriptions, issue comments, and issue documents.
+- Paperclip **assets/attachments** and **issue work products** are **metadata-only** in Phase 5.
+- **Linked summaries** and **content extraction** for assets/work products are **not approved** in Phase 5.
+- No implementation may fetch `/api/assets/:id/content`, dereference a work-product `url`, scrape preview pages, or embed binary/blob content into source bundles or source snapshots.
+
+This keeps the secure path easier than the insecure one and avoids broadening the wiki into a second content-distribution channel.
+
+## Allowed Source Kinds
+
+These source kinds may contribute body text to Paperclip-derived source bundles:
+
+| Source kind | Allowed body fields | Reason |
+| --- | --- | --- |
+| Issue | `title`, `description`, identifier/status metadata | First-party Paperclip text under company ACL |
+| Comment | `body` | First-party Paperclip text under company ACL |
+| Document | `body`, `title`, `key`, revision metadata | First-party Paperclip text under company ACL |
+
+## Assets And Work Products
+
+### Assets / attachments
+
+Allowed in Phase 5:
+
+- metadata-only references built from allowlisted structured fields already stored in Paperclip
+- recommended fields: `issueId`, `issueCommentId`, `attachmentId`, `assetId`, `originalFilename`, `contentType`, `byteSize`, `sha256`, `createdAt`, `createdByAgentId`, `createdByUserId`
+
+Disallowed in Phase 5:
+
+- fetching asset bytes from `/api/assets/:id/content`
+- parsing any blob body, including `text/plain`, `text/markdown`, `application/json`, images, SVG, PDFs, archives, or office formats
+- storing `contentPath` in wiki source bundles or source snapshots
+- model summarization of attachment bodies
+
+### Work products
+
+Allowed in Phase 5:
+
+- metadata-only references built from allowlisted structured fields already stored in Paperclip
+- recommended fields: `issueId`, `workProductId`, `type`, `provider`, `title`, `status`, `reviewState`, `healthStatus`, `externalId`, `isPrimary`, `createdAt`, `updatedAt`
+- optional boolean/derived metadata such as `hasUrl: true`
+
+Disallowed in Phase 5:
+
+- fetching or crawling the work-product `url`
+- scraping preview pages, artifacts, pull requests, branches, commits, or custom provider targets through the wiki ingestion path
+- storing raw `url` values in wiki source bundles or source snapshots
+- model-authored linked summaries derived from off-record content
+
+## MIME Allowlists And Size Caps
+
+No MIME allowlist is approved for asset content extraction in Phase 5 because **no asset body extraction is approved at all**.
+
+- Every asset MIME type is treated as opaque for Paperclip-derived indexing.
+- Existing upload limits remain storage concerns, not ingestion approvals.
+- Work-product destinations are also opaque regardless of MIME type or size.
+
+Any future issue that wants blob parsing must define:
+
+- a positive MIME allowlist
+- per-type parser strategy
+- per-source size caps
+- sandbox/isolation requirements
+- prompt-injection handling
+- regression tests for refusal paths
+
+## Redaction Rules
+
+Metadata-only means **structured facts only**, not capability-bearing links.
+
+- Do not persist `contentPath` for assets.
+- Do not persist raw work-product `url` values.
+- Do not persist query strings, fragments, signed URL tokens, or userinfo.
+- Prefer stable identifiers (`assetId`, `workProductId`, `externalId`) over links.
+
+This addresses Sensitive Information Disclosure, Unsafe Consumption of APIs, and Insecure Output Handling risks.
+
+## Provenance Rules
+
+Every metadata-only reference must preserve enough provenance to explain where it came from without reading the underlying content:
+
+- `companyId`
+- `issueId`
+- attachment/work-product id
+- producer identity when available
+- timestamps
+- an explicit `metadata_only` marker in any future reference/snapshot schema
+
+## Review-Required Behavior
+
+Human review is **not** required for plain metadata-only references that stay inside the allowlisted fields above.
+
+Human review **is required**, with a separate security sign-off issue, before enabling any of the following:
+
+- asset body extraction
+- work-product URL fetching
+- linked summaries generated from asset/work-product content
+- storing raw blob links or raw remote URLs in wiki source material
+- non-default-space routing for Paperclip-derived asset/work-product references
+
+## Security Rationale
+
+This gate exists because the current host surfaces have different trust properties:
+
+- issue/comment/document text is first-party Paperclip content already exposed through company-scoped issue/document APIs
+- asset content is a blob download surface (`/api/assets/:id/content`) and can carry prompt-injection or parser-risk payloads
+- work products can point at arbitrary destinations through `url`, which reintroduces SSRF, token leakage, and prompt-injection risk if dereferenced automatically
+
+Relevant threat classes:
+
+- OWASP LLM Top 10: Prompt Injection, Sensitive Information Disclosure, Insecure Output Handling, Excessive Agency
+- OWASP API Top 10: SSRF, Unsafe Consumption of APIs, Broken Object Property Level Authorization
+- Saltzer & Schroeder: Least Privilege, Fail Securely, Complete Mediation, Secure Defaults
+
+## Follow-Up Implementation Scope
+
+A follow-up implementation issue is justified only for **metadata-only references**.
+
+That implementation must:
+
+- keep assets/work products out of source-bundle body text
+- never fetch blob bytes or remote URLs
+- redact capability-bearing link fields
+- mark references as `metadata_only`
+- ship tests proving source bundles/snapshots never contain `contentPath` or raw work-product `url` fields

doc/plugins/PLUGIN_AUTHORING_GUIDE.md

@@ -13,7 +13,9 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i
 - Plugin database migrations are restricted to a host-derived plugin namespace.
 - Plugin-owned JSON API routes must be declared in the manifest and are mounted
   only under `/api/plugins/:pluginId/api/*`.
-- There is no host-provided shared React component kit for plugins yet.
+- The host provides a small shared React component kit through
+  `@paperclipai/plugin-sdk/ui`; use it for common Paperclip controls before
+  building custom versions.
 - `ctx.assets` is not supported in the current runtime.
 
 ## Scaffold a plugin
@@ -83,10 +85,11 @@ Worker:
 - database namespace via `ctx.db`
 - scoped JSON API routes declared with `apiRoutes`
 - entities
-- projects and project workspaces
+- projects, project workspaces, and plugin-managed projects
 - companies
 - issues, comments, namespaced `plugin:<pluginKey>` origins, blocker relations, checkout assertions, assignment wakeups, and orchestration summaries
-- agents and agent sessions
+- agents, plugin-managed agents, and agent sessions
+- plugin-managed routines
 - goals
 - data/actions
 - streams
@@ -143,6 +146,161 @@ handler. The worker receives sanitized headers, route params, query, parsed JSON
 body, actor context, and company id. Do not use plugin routes to claim core
 paths; they always remain under `/api/plugins/:pluginId/api/*`.
 
+## Managed Paperclip resources
+
+Plugins that provide durable Paperclip business objects should declare them in
+the manifest and let the host create or relink the actual records per company.
+Do this for plugin-owned agents, plugin-owned projects, and recurring automation.
+Do not hide long-lived work behind private plugin state when it should be visible
+to the board, scoped to a company, audited, budgeted, and assigned like normal
+Paperclip work.
+
+Use these surfaces:
+
+- Managed agents: declare top-level `agents[]` and require
+  `agents.managed`. Use this when the plugin provides a named worker the board
+  should see in the org, budget, pause, invoke, and inspect. Managed agents are
+  normal Paperclip agents with plugin ownership metadata, not background plugin
+  workers.
+- Managed projects: declare top-level `projects[]` and require
+  `projects.managed`. Use this when the plugin needs a stable company-scoped
+  project for its issues, routines, or workspace-oriented UI. Keep plugin work
+  in a project instead of scattering generated issues across unrelated projects.
+- Managed routines: declare top-level `routines[]` and require
+  `routines.managed`. Use this for scheduled, webhook, or manually triggered
+  jobs that should create visible Paperclip issues. Prefer managed routines over
+  plugin `jobs[]` for recurring business work; plugin jobs are for plugin
+  runtime maintenance that does not need a board-visible task trail.
+
+Managed resources are resolved by stable plugin keys, not hardcoded database
+ids. In a worker action or data handler, call `ctx.agents.managed.reconcile()`,
+`ctx.projects.managed.reconcile()`, and `ctx.routines.managed.reconcile()` for
+the current `companyId`. `reconcile()` creates the missing resource, relinks a
+recoverable binding, or returns the existing resource. `reset()` reapplies the
+manifest defaults when the operator wants to restore the plugin's suggested
+configuration.
+
+Declare dependencies between managed resources with refs. A routine can point
+at a managed agent through `assigneeRef` and at a managed project through
+`projectRef`. Reconcile the referenced agent and project before reconciling the
+routine; if a ref is still missing, the routine resolution reports
+`missing_refs` instead of guessing.
+
+```ts
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: "example.research-plugin",
+  apiVersion: 1,
+  version: "0.1.0",
+  displayName: "Research Plugin",
+  description: "Creates a managed research agent and scheduled research routine.",
+  author: "Example",
+  categories: ["automation"],
+  capabilities: [
+    "agents.managed",
+    "projects.managed",
+    "routines.managed",
+    "instance.settings.register",
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui",
+  },
+  agents: [
+    {
+      agentKey: "researcher",
+      displayName: "Researcher",
+      role: "research",
+      title: "Research Agent",
+      capabilities: "Runs recurring research briefs for this company.",
+      adapterPreference: ["codex_local", "claude_local", "process"],
+      instructions: {
+        content: "Follow the Paperclip heartbeat and produce concise research briefs.",
+      },
+    },
+  ],
+  projects: [
+    {
+      projectKey: "research",
+      displayName: "Research",
+      description: "Recurring research work created by the Research Plugin.",
+      status: "in_progress",
+    },
+  ],
+  routines: [
+    {
+      routineKey: "weekly-brief",
+      title: "Weekly research brief",
+      description: "Create a short research brief for the board.",
+      assigneeRef: { resourceKind: "agent", resourceKey: "researcher" },
+      projectRef: { resourceKind: "project", resourceKey: "research" },
+      priority: "medium",
+      triggers: [
+        {
+          kind: "schedule",
+          label: "Monday morning",
+          cronExpression: "0 9 * * 1",
+          timezone: "America/Chicago",
+          enabled: false,
+        },
+      ],
+    },
+  ],
+  ui: {
+    slots: [
+      {
+        type: "settingsPage",
+        id: "settings",
+        displayName: "Research",
+        exportName: "SettingsPage",
+      },
+    ],
+  },
+};
+
+export default manifest;
+```
+
+In the worker, expose a small setup action or settings-page action that
+reconciles the resources for the selected company:
+
+```ts
+import { definePlugin } from "@paperclipai/plugin-sdk";
+
+export default definePlugin({
+  setup(ctx) {
+    ctx.actions.register("setup-company", async (params) => {
+      const companyId = String(params.companyId ?? "");
+      if (!companyId) throw new Error("companyId is required");
+
+      const project = await ctx.projects.managed.reconcile("research", companyId);
+      const agent = await ctx.agents.managed.reconcile("researcher", companyId);
+      const routine = await ctx.routines.managed.reconcile("weekly-brief", companyId);
+
+      return { project, agent, routine };
+    });
+  },
+});
+```
+
+Authoring rules:
+
+- Keep keys stable once published. Renaming `agentKey`, `projectKey`, or
+  `routineKey` creates a new managed resource from the host's point of view.
+- Use managed agents for plugin-provided labor. Use `ctx.agents.invoke()` or
+  `ctx.agents.sessions` only after you have a real agent id, either selected by
+  the operator or resolved from `ctx.agents.managed`.
+- Use managed routines for recurring or externally triggered work that should
+  produce tasks. Schedule, webhook, and API triggers are visible routine
+  triggers, and each run has the normal Paperclip issue/audit trail.
+- Use managed projects to keep plugin-generated work organized and to give
+  project-scoped plugin UI a stable home. For filesystem access inside a
+  project, still resolve project workspaces through `ctx.projects`.
+- Keep defaults conservative. Managed declarations are suggestions owned by the
+  plugin, but the resulting resources are normal Paperclip records that the
+  operator can inspect, pause, and adjust.
+
 UI:
 
 - `usePluginData`
@@ -168,6 +326,187 @@ Mount surfaces currently wired in the host include:
 - `commentAnnotation`
 - `commentContextMenuItem`
 
+## Shared host components
+
+Use shared components from `@paperclipai/plugin-sdk/ui` when the plugin needs a
+Paperclip-native control. The host owns the implementation, so plugins inherit
+the board's current styling, ordering, recent selections, and dark-mode behavior
+without importing `ui/src` internals.
+
+Currently exposed components include:
+
+- `MarkdownBlock` and `MarkdownEditor` for rendered and editable markdown.
+- `FileTree` for serializable file and directory trees.
+- `IssuesList` for a native company-scoped issue table.
+- `AssigneePicker` for the same agent/user selector used in the new issue pane.
+  Use the controlled `value` format `agent:<id>`, `user:<id>`, or `""`.
+- `ProjectPicker` for the same project selector used in the new issue pane.
+  Use the controlled project id value, or `""` for no project.
+- `ManagedRoutinesList` for plugin-owned routine settings pages.
+
+```tsx
+import { AssigneePicker, ProjectPicker } from "@paperclipai/plugin-sdk/ui";
+
+export function PluginAssignmentControls({ companyId }: { companyId: string }) {
+  const [assignee, setAssignee] = useState("");
+  const [projectId, setProjectId] = useState("");
+
+  return (
+    <>
+      <AssigneePicker
+        companyId={companyId}
+        value={assignee}
+        onChange={(value) => setAssignee(value)}
+      />
+      <ProjectPicker
+        companyId={companyId}
+        value={projectId}
+        onChange={setProjectId}
+      />
+    </>
+  );
+}
+```
+
+## File and path UI
+
+Plugin UI often needs to render a file tree, accept a folder path, or browse a
+project workspace. There are three different surfaces for that, and they map to
+different trust and data-flow boundaries. Pick the surface that matches the
+data the plugin actually has.
+
+### When to use the shared `FileTree`
+
+Use `FileTree` from `@paperclipai/plugin-sdk/ui` whenever the plugin only needs
+to render a serializable file/directory list and react to selection or
+expand/collapse. The host owns the implementation, so plugin UI inherits the
+board's icons, indent, focus ring, and dark-mode styling without importing host
+internals.
+
+```tsx
+import {
+  FileTree,
+  type FileTreeNode,
+} from "@paperclipai/plugin-sdk/ui";
+
+const nodes: FileTreeNode[] = [
+  { name: "AGENTS.md", path: "AGENTS.md", kind: "file", children: [] },
+  {
+    name: "wiki",
+    path: "wiki",
+    kind: "dir",
+    children: [
+      { name: "index.md", path: "wiki/index.md", kind: "file", children: [] },
+    ],
+  },
+];
+
+export function WikiTree() {
+  const [expanded, setExpanded] = useState<Set<string>>(() => new Set(["wiki"]));
+  const [selected, setSelected] = useState<string | null>(null);
+
+  return (
+    <FileTree
+      nodes={nodes}
+      selectedFile={selected}
+      expandedPaths={expanded}
+      onSelectFile={(path) => setSelected(path)}
+      onToggleDir={(path) =>
+        setExpanded((current) => {
+          const next = new Set(current);
+          next.has(path) ? next.delete(path) : next.add(path);
+          return next;
+        })
+      }
+    />
+  );
+}
+```
+
+Good fits:
+
+- LLM Wiki page navigation in `packages/plugins/plugin-llm-wiki` builds a
+  `FileTreeNode[]` from worker query results and renders it through `FileTree`.
+- The example `plugin-file-browser-example` lazily fetches a directory's
+  children through a `loadFileList` action when `onToggleDir` fires, then
+  merges the children into the local tree state — letting the shared component
+  handle rendering and selection.
+
+Boundary rules:
+
+- Keep the prop surface serializable (`nodes`, `expandedPaths`, `checkedPaths`,
+  `fileBadges`, `fileTones`). Do not pass arbitrary render functions across the
+  plugin/host boundary in v1; the supported escape hatches are
+  `fileBadges` (status pill keyed by path) and `fileTones` (row tone keyed by
+  path).
+- Do not import the host's `FileTree.tsx` or any `ui/src/*` module. The SDK
+  declaration is the only supported import path for plugin UI.
+- The shared `FileTree` is for rendering and selection. Plugin-specific editors,
+  ingest flows, query forms, and lint runs stay inside the plugin and do not
+  belong as `FileTree` props.
+
+### When to declare `localFolders`
+
+When the plugin needs operator-configured filesystem roots — typically for
+trusted local plugins like wiki tooling — declare `localFolders[]` on the
+manifest and add the `local.folders` capability. The host renders a settings
+surface for the operator to set the absolute path, validates the path
+server-side (containment, symlinks, required files/directories), and exposes
+`ctx.localFolders.readText()` and `ctx.localFolders.writeTextAtomic()` in the
+worker.
+
+```ts
+export const manifest = {
+  capabilities: ["local.folders"],
+  localFolders: [
+    {
+      folderKey: "content-root",
+      displayName: "Content root",
+      access: "readWrite",
+      requiredDirectories: ["sources", "pages"],
+      requiredFiles: ["schema.md"],
+    },
+  ],
+};
+```
+
+Use this when:
+
+- The data lives outside any project workspace.
+- Reads and writes need company-scoped configuration.
+- The operator picks the path once in plugin settings and the worker resolves
+  files relative to that root.
+
+Do not use `localFolders` to grant the UI direct browser-side access to the
+filesystem — there is no such capability. The browser still goes through the
+worker via `getData` / `performAction`, and the worker only exposes paths it
+chose to expose.
+
+### When to keep worker-mediated project workspace browsing
+
+When the data lives inside an existing project workspace, keep the browsing
+flow worker-mediated:
+
+- The worker uses `ctx.projects.listWorkspaces()` to resolve the workspace
+  path, then reads its filesystem with normal Node APIs.
+- The plugin UI calls a `getData` handler for the root listing and an action
+  for lazy children, then renders them through `FileTree`.
+- The worker is the only side that touches the disk. The browser receives a
+  serializable tree and never sees raw absolute paths it can replay.
+
+The example `plugin-file-browser-example` is the reference for this pattern:
+the worker registers `fileList` (data) and `loadFileList` (action) over the
+same handler, and the UI uses the action for on-toggle directory loading so the
+shared `FileTree` stays the rendering surface.
+
+### Mixing surfaces
+
+A single plugin can use more than one of these. The LLM Wiki uses
+`localFolders` for its content root, then renders the resulting page list
+through `FileTree`. The file browser example uses `ctx.projects.listWorkspaces`
+to pick a workspace and renders its on-disk tree through `FileTree` with lazy
+loading. Pick the boundary per data source, not per plugin.
+
 ## Company routes
 
 Plugins may declare a `page` slot with `routePath` to own a company route like:

doc/plugins/PLUGIN_SPEC.md

@@ -27,7 +27,7 @@ Current limitations to keep in mind:
 - Published npm packages are the intended install artifact for deployed plugins.
 - The repo example plugins under `packages/plugins/examples/` are development conveniences. They work from a source checkout and should not be assumed to exist in a generic published build unless they are explicitly shipped with that build.
 - Dynamic plugin install is not yet cloud-ready for horizontally scaled or ephemeral deployments. There is no shared artifact store, install coordination, or cross-node distribution layer yet.
-- The current runtime does not yet ship a real host-provided plugin UI component kit, and it does not support plugin asset uploads/reads. Treat those as future-scope ideas in this spec, not current implementation promises.
+- The current runtime ships a small host-provided plugin UI component kit through `@paperclipai/plugin-sdk/ui`, but does not support plugin asset uploads/reads yet. Treat plugin asset APIs as future-scope ideas, not current implementation promises.
 - Scoped plugin API routes are JSON-only and must be declared in `apiRoutes`.
   They mount under `/api/plugins/:pluginId/api/*`; plugins cannot shadow core
   API routes.
@@ -976,13 +976,23 @@ export function DashboardWidget({ context }: PluginWidgetProps) {
 
 The SDK includes a `ui` subpath export that plugin frontends import. This subpath provides:
 
-- **Bridge hooks**: `usePluginData(key, params)`, `usePluginAction(key)`, `useHostContext()`
+- **Bridge hooks**: `usePluginData(key, params)`, `usePluginAction(key)`, `useHostContext()`, `useHostNavigation()`
 - **Design tokens**: colors, spacing, typography, shadows matching the host theme
 - **Shared components**: `MetricCard`, `StatusBadge`, `DataTable`, `LogView`, `ActionBar`, `Spinner`, etc.
 - **Type definitions**: `PluginPageProps`, `PluginWidgetProps`, `PluginDetailTabProps`
 
 Plugins are encouraged but not required to use the shared components. A plugin may render entirely custom UI as long as it communicates through the bridge.
 
+`useHostNavigation()` is the supported way for plugin UI to navigate to
+Paperclip-internal pages. It exposes `resolveHref(to)`, `navigate(to,
+options?)`, and `linkProps(to, options?)`. Plugin links should prefer
+`linkProps()` so anchors keep real `href` values for copy-link, modifier-click,
+middle-click, and open-in-new-tab behavior while plain left-clicks route through
+the host SPA router. The host resolves company-scoped paths against the active
+company prefix without double-prefixing already-prefixed paths. Plugin UI should
+not use raw same-origin `href`s or `window.location.assign()` for internal
+Paperclip navigation because those can force a full document reload.
+
 ### 19.0.2 Bundle Isolation
 
 Plugin UI bundles are loaded as standard ES modules, not iframed. This gives plugins full rendering performance and access to the host's design tokens.
@@ -1062,6 +1072,11 @@ The host SDK ships shared components that plugins can import to quickly build UI
 | `LogView` | Scrollable log output with timestamps | Webhook deliveries, job output, process logs |
 | `JsonTree` | Collapsible JSON tree for debugging | Raw API responses, plugin state inspection |
 | `Spinner` | Loading indicator | Data fetch states |
+| `FileTree` | Host-styled file/directory tree | Wiki pages, workspace files, import previews |
+| `IssuesList` | Host issue list | Plugin pages that need a native issue view |
+| `AssigneePicker` | Host assignee picker for agents and board users | Creating issues, assigning routines, filtering work |
+| `ProjectPicker` | Host project picker | Creating issues, scoping dashboards, filtering work |
+| `ManagedRoutinesList` | Host routine list | Plugin settings pages that manage routines |
 
 Plugins may also use entirely custom components. The shared components exist to reduce boilerplate and keep visual consistency, not to limit what plugins can render.
 

docs/api/routines.md

@@ -75,11 +75,28 @@ Fields:
 ```
 PATCH /api/routines/{routineId}
 {
-  "status": "paused"
+  "status": "paused",
+  "baseRevisionId": "{latestRevisionId}"
 }
 ```
 
-All fields from create are updatable. **Agents can only update routines assigned to themselves and cannot reassign a routine to another agent.**
+All fields from create are updatable. `baseRevisionId` is optional for backward compatibility; when provided, stale values return `409 Conflict` with the current revision id. **Agents can only update routines assigned to themselves and cannot reassign a routine to another agent.**
+
+## List Revisions
+
+```
+GET /api/routines/{routineId}/revisions
+```
+
+Returns append-only routine definition revisions newest first. Snapshots include routine fields and safe trigger metadata only; webhook secret values and `secretId` are never returned.
+
+## Restore Revision
+
+```
+POST /api/routines/{routineId}/revisions/{revisionId}/restore
+```
+
+Restores a historical routine definition by creating a new latest revision copied from the selected revision. Historical revision rows, routine run history, and activity history are preserved. If restoring a deleted webhook trigger requires recreating it, the response can include one-time replacement secret material for that trigger.
 
 ## Add Trigger
 

docs/api/secrets-remote-import.md

@@ -0,0 +1,133 @@
+---
+title: Secrets Remote Import
+summary: AWS Secrets Manager metadata-only remote import API
+---
+
+Remote import lets the board link existing AWS Secrets Manager entries as
+Paperclip `external_reference` secrets without copying plaintext into
+Paperclip.
+
+Both routes are board-only and company-scoped. The selected provider vault must
+belong to the company, use `aws_secrets_manager`, and have a selectable status
+(`ready` or `warning`). Disabled, coming-soon, or cross-company vaults are
+rejected.
+
+Remote import is an inventory and metadata workflow. Preview calls AWS
+`ListSecrets` only and import stores a Paperclip external reference plus
+fingerprint/version metadata. Neither route calls `GetSecretValue` or
+`BatchGetSecretValue`, requests `SecretString`, requires KMS decrypt, logs raw
+remote metadata, or copies secret plaintext into Paperclip.
+
+## Preview Remote AWS Secrets
+
+```
+POST /api/companies/{companyId}/secrets/remote-import/preview
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "query": "stripe",
+  "nextToken": "optional-provider-page-token",
+  "pageSize": 50
+}
+```
+
+`query` is optional and is sent to AWS as an inventory filter. Treat it as
+non-secret metadata because AWS may record list request parameters in
+CloudTrail. `nextToken` is an opaque AWS cursor; pass it back unchanged.
+`pageSize` is capped at 100.
+
+Response:
+
+```json
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "provider": "aws_secrets_manager",
+  "nextToken": null,
+  "candidates": [
+    {
+      "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/stripe",
+      "remoteName": "prod/stripe",
+      "name": "prod/stripe",
+      "key": "prod-stripe",
+      "providerVersionRef": null,
+      "providerMetadata": {
+        "lastChangedDate": "2026-05-06T00:00:00.000Z",
+        "hasDescription": true
+      },
+      "status": "ready",
+      "importable": true,
+      "conflicts": []
+    }
+  ]
+}
+```
+
+Candidate `status` values:
+
+- `ready`: no existing exact external reference and no name/key collision.
+- `duplicate`: an existing secret already has the exact provider `externalRef`.
+- `conflict`: the suggested Paperclip `name` or `key` is already in use.
+
+Conflict `type` values are `exact_reference`, `name`, `key`, and
+`provider_guardrail`. AWS refs under Paperclip's own managed namespace are
+blocked as external references so one company cannot import another company's
+Paperclip-managed AWS secret through a broad runtime role.
+
+## Import Remote AWS Secret References
+
+```
+POST /api/companies/{companyId}/secrets/remote-import
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "secrets": [
+    {
+      "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/stripe",
+      "name": "Stripe production key",
+      "key": "stripe-production-key",
+      "description": "Stripe key used by production checkout",
+      "providerVersionRef": null,
+      "providerMetadata": {
+        "lastChangedDate": "2026-05-06T00:00:00.000Z",
+        "hasDescription": true
+      }
+    }
+  ]
+}
+```
+
+The import response is row-level. Ready rows become active
+`external_reference` secrets with version metadata only. Exact-reference
+duplicates and name/key conflicts are skipped without failing the whole request.
+The `secrets` array accepts 1-100 rows, and the backend re-checks duplicates and
+conflicts at submit time.
+Each row may include an optional Paperclip `description` entered during review;
+blank descriptions are stored as `null`. AWS provider descriptions are not
+copied into this field.
+
+```json
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "provider": "aws_secrets_manager",
+  "importedCount": 1,
+  "skippedCount": 1,
+  "errorCount": 0,
+  "results": [
+    {
+      "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/stripe",
+      "name": "Stripe production key",
+      "key": "stripe-production-key",
+      "status": "imported",
+      "reason": null,
+      "secretId": "<paperclip-secret-id>",
+      "conflicts": []
+    }
+  ]
+}
+```
+
+Activity logs record aggregate counts and provider/vault ids only, not remote
+secret names, ARNs, tags, or values.
+
+Imported references may still fail during a future bound runtime resolution if
+the Paperclip runtime role can list the AWS secret but lacks
+`secretsmanager:GetSecretValue` or required KMS decrypt permission for that
+specific secret.

docs/api/secrets.md

@@ -25,16 +25,357 @@ POST /api/companies/{companyId}/secrets
 
 The value is encrypted at rest. Only the secret ID and metadata are returned.
 
-## Update Secret
+To link a provider-owned secret without copying the value into Paperclip, create
+an external-reference secret:
+
+```json
+{
+  "name": "prod-stripe-key",
+  "provider": "aws_secrets_manager",
+  "managedMode": "external_reference",
+  "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:paperclip/prod/stripe",
+  "providerVersionRef": "version-id-or-label"
+}
+```
+
+Paperclip stores the provider reference and a non-sensitive fingerprint only.
+The value is resolved, when the provider is configured, through the server
+runtime path that enforces binding context and records access events.
+
+## Provider Health
 
 ```
-PATCH /api/secrets/{secretId}
+GET /api/companies/{companyId}/secret-providers/health
+```
+
+Returns provider setup diagnostics, warnings, and local backup guidance. Health
+responses must not include secret values or provider credentials.
+
+For `aws_secrets_manager`, an unready health response names the missing
+non-secret provider environment variables, the AWS SDK default credential source
+expected by the server runtime, and the custody rule that AWS bootstrap
+credentials must not be stored in Paperclip `company_secrets`.
+
+The equivalent CLI check is:
+
+```sh
+pnpm paperclipai secrets doctor --company-id {companyId}
+```
+
+## Provider Vaults
+
+Provider vaults are named, company-scoped configurations that route secret
+material to one of the supported provider backends. See the
+[secrets deploy guide](/deploy/secrets#provider-vaults) for the operator model
+and custody rules.
+
+All routes below require board auth and company access. Mutating routes emit
+`secret_provider_config.*` activity-log entries. No route in this surface
+returns provider credential values; submitting credential-shaped fields in
+`config` is rejected at validation time.
+
+### List Vaults
+
+```
+GET /api/companies/{companyId}/secret-provider-configs
+```
+
+Returns every vault for the company (including disabled rows for audit), each
+with id, provider, displayName, status, isDefault, non-sensitive `config`,
+latest health snapshot (`healthStatus`, `healthCheckedAt`, `healthMessage`,
+`healthDetails`), `disabledAt`, and audit columns.
+
+### Create Vault
+
+```
+POST /api/companies/{companyId}/secret-provider-configs
+{
+  "provider": "aws_secrets_manager",
+  "displayName": "Prod US-East",
+  "isDefault": true,
+  "config": {
+    "region": "us-east-1",
+    "namespace": "paperclip",
+    "secretNamePrefix": "paperclip",
+    "kmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/abcd-...",
+    "environmentTag": "production"
+  }
+}
+```
+
+Per-provider `config` shapes:
+
+- `local_encrypted`: optional `backupReminderAcknowledged: boolean`.
+- `aws_secrets_manager`: required `region`; optional `namespace`,
+  `secretNamePrefix`, `kmsKeyId`, `ownerTag`, `environmentTag`.
+- `gcp_secret_manager` (coming soon): optional `projectId`, `location`,
+  `namespace`, `secretNamePrefix`.
+- `vault` (coming soon): optional origin-only HTTPS `address`, `namespace`,
+  `mountPath`, `secretPathPrefix`. `address` values with embedded credentials,
+  paths, query strings, or fragments are rejected.
+
+`status` defaults to `ready` for `local_encrypted` and `aws_secrets_manager`,
+and to `coming_soon` for `gcp_secret_manager` and `vault`. Coming-soon and
+disabled vaults cannot be marked `isDefault`. Setting `isDefault: true` clears
+the previous default for the same provider in the same transaction.
+
+### Get Vault
+
+```
+GET /api/secret-provider-configs/{id}
+```
+
+### Update Vault
+
+```
+PATCH /api/secret-provider-configs/{id}
+{
+  "displayName": "Prod US-East-2",
+  "config": {
+    "region": "us-east-2",
+    "kmsKeyId": "arn:aws:kms:us-east-2:123456789012:key/abcd-..."
+  }
+}
+```
+
+`config` is replaced wholesale on update — pass the full provider config
+payload, not a partial diff. Status transitions for `gcp_secret_manager` and
+`vault` are constrained to `coming_soon` and `disabled` until their runtime
+modules ship.
+
+### Disable Vault
+
+```
+DELETE /api/secret-provider-configs/{id}
+```
+
+Soft-deletes the vault: status flips to `disabled`, `isDefault` clears, and
+`disabledAt` is stamped. Disabled vaults remain in `GET` results for audit
+purposes but are no longer offered in the secret create/rotate flow.
+
+### Set Default
+
+```
+POST /api/secret-provider-configs/{id}/default
+```
+
+Marks the target vault as the default for its provider family and clears the
+previous default. Returns 422 when the target is `coming_soon` or `disabled`.
+
+### Run Health Check
+
+```
+POST /api/secret-provider-configs/{id}/health
+```
+
+Runs a provider-specific health probe and persists the result on the vault.
+Response shape:
+
+```json
+{
+  "configId": "<uuid>",
+  "provider": "aws_secrets_manager",
+  "status": "ready" | "warning" | "error" | "coming_soon" | "disabled",
+  "message": "Provider vault is ready to handle managed writes",
+  "details": {
+    "code": "provider_ready",
+    "message": "...",
+    "guidance": ["..."]
+  },
+  "checkedAt": "2026-05-06T14:00:00.000Z"
+}
+```
+
+Health responses never include provider credentials or secret values. For AWS
+vaults, `details.guidance` may include missing non-secret env names and the
+expected AWS SDK credential source; coming-soon vaults always return
+`status: "coming_soon"` with `code: "runtime_locked"` and never call into
+provider modules.
+
+### Selecting A Vault When Creating Or Rotating Secrets
+
+`POST /api/companies/{companyId}/secrets` and
+`POST /api/secrets/{secretId}/rotate` both accept an optional
+`providerConfigId` field that pins the secret to a specific vault. When
+omitted (or null), the operation runs through the deployment-level provider
+configuration — the same path existing installs already use. The board UI
+preselects the company's default vault for the chosen provider before
+submitting, so callers should usually send an explicit `providerConfigId`.
+Coming-soon and disabled vaults are rejected with a 422; a vault that does not
+match the secret's provider is rejected the same way.
+
+```json
+POST /api/companies/{companyId}/secrets
+{
+  "name": "prod-stripe-key",
+  "provider": "aws_secrets_manager",
+  "providerConfigId": "<vault-uuid>",
+  "managedMode": "external_reference",
+  "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:paperclip/prod/stripe"
+}
+```
+
+### Response Redaction Rules
+
+Every route in this surface enforces the same redaction contract:
+
+- Secret values are never returned. The board UI never has a "reveal value"
+  affordance; resolution happens server-side at runtime under a binding.
+- Provider credential values are never accepted, stored, returned, logged, or
+  echoed in error messages. Submitting credential-shaped fields fails
+  validation with a non-leaking error.
+- Activity log entries record vault id, provider, displayName, status, and
+  isDefault transitions — never `config` payloads or health detail bodies.
+
+## Remote Import From AWS Secrets Manager
+
+Remote import links existing AWS Secrets Manager entries into Paperclip as
+`external_reference` secrets. Import stores provider reference metadata only; it
+does not copy the remote secret plaintext into Paperclip.
+
+The routes are board-only and company-scoped. `providerConfigId` must point to
+a same-company AWS provider vault with status `ready` or `warning`. Disabled,
+coming-soon, non-AWS, and cross-company vaults are rejected. Imported secrets
+resolve later through the selected vault, so runtime reads still need
+`secretsmanager:GetSecretValue` and any required KMS decrypt permission on the
+selected external secret.
+
+### Preview Remote Import Candidates
+
+```
+POST /api/companies/{companyId}/secrets/remote-import/preview
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "query": "stripe",
+  "nextToken": "opaque-provider-token",
+  "pageSize": 50
+}
+```
+
+`query` is optional and is passed to AWS Secrets Manager inventory filtering.
+Treat it as non-secret metadata because AWS may record list request parameters
+in CloudTrail. `nextToken` is an opaque AWS cursor; callers must pass it back
+unchanged and must not synthesize offsets. `pageSize` is optional, defaults to
+50 in the UI, and is capped at 100.
+
+Preview uses AWS `ListSecrets` only. It must not call `GetSecretValue` or
+`BatchGetSecretValue`, must not request `SecretString`, and must not require KMS
+decrypt. The response contains sanitized metadata for display and conflict
+decisions:
+
+```json
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "provider": "aws_secrets_manager",
+  "nextToken": null,
+  "candidates": [
+    {
+      "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/stripe",
+      "remoteName": "prod/stripe",
+      "name": "prod/stripe",
+      "key": "prod-stripe",
+      "providerVersionRef": null,
+      "providerMetadata": {
+        "createdDate": "2026-05-06T00:00:00.000Z",
+        "lastChangedDate": "2026-05-06T00:00:00.000Z",
+        "hasDescription": true,
+        "hasKmsKey": true,
+        "tagCount": 3
+      },
+      "status": "ready",
+      "importable": true,
+      "conflicts": []
+    }
+  ]
+}
+```
+
+Candidate statuses:
+
+- `ready`: the row can be selected for import.
+- `duplicate`: a Paperclip secret already links the same canonical provider
+  reference for the same provider vault.
+- `conflict`: the row has a name/key collision or provider guardrail failure.
+
+Conflict types are `exact_reference`, `name`, `key`, and
+`provider_guardrail`. AWS refs under Paperclip's own managed namespace are
+blocked as external references; use the Paperclip-managed secret flow for those
+resources instead.
+
+### Import Selected Remote References
+
+```
+POST /api/companies/{companyId}/secrets/remote-import
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "secrets": [
+    {
+      "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/stripe",
+      "name": "Stripe production key",
+      "key": "stripe-production-key",
+      "description": "Stripe key used by production checkout",
+      "providerVersionRef": null,
+      "providerMetadata": {
+        "createdDate": "2026-05-06T00:00:00.000Z"
+      }
+    }
+  ]
+}
+```
+
+The `secrets` array accepts 1-100 rows. Each row may override the suggested
+Paperclip `name`, `key`, optional Paperclip `description`,
+`providerVersionRef`, and sanitized `providerMetadata`. Blank descriptions are
+stored as `null`; AWS provider descriptions are not copied into Paperclip
+descriptions. The backend re-checks duplicate refs and name/key conflicts at
+submit time; a stale preview does not bypass those checks.
+
+The import response is row-level:
+
+```json
+{
+  "providerConfigId": "<aws-vault-uuid>",
+  "provider": "aws_secrets_manager",
+  "importedCount": 1,
+  "skippedCount": 1,
+  "errorCount": 0,
+  "results": [
+    {
+      "externalRef": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/stripe",
+      "name": "Stripe production key",
+      "key": "stripe-production-key",
+      "status": "imported",
+      "reason": null,
+      "secretId": "<paperclip-secret-id>",
+      "conflicts": []
+    }
+  ]
+}
+```
+
+Row statuses:
+
+- `imported`: Paperclip created an active `external_reference` secret and one
+  metadata-only version row.
+- `skipped`: the row had an exact-reference duplicate or name/key conflict.
+- `error`: the provider rejected the reference or the row failed validation.
+
+Activity logs for preview/import store aggregate counts, provider id, and vault
+id only. They must not store remote secret names, ARNs, descriptions, tags,
+plaintext values, provider credentials, or raw AWS error blobs.
+
+## Rotate Secret
+
+```
+POST /api/secrets/{secretId}/rotate
 {
   "value": "sk-ant-new-value..."
 }
 ```
 
-Creates a new version of the secret. Agents referencing `"version": "latest"` automatically get the new value on next heartbeat.
+Creates a new version of the secret. Agents referencing `"version": "latest"`
+automatically get the new value on next heartbeat. Pin to a specific version
+when a bad `latest` rollout would affect many agents at once.
 
 ## Using Secrets in Agent Config
 
@@ -52,4 +393,20 @@ Reference secrets in agent adapter config instead of inline values:
 }
 ```
 
-The server resolves and decrypts secret references at runtime, injecting the real value into the agent process environment.
+The server resolves and decrypts secret references at runtime, injecting the
+real value into the agent process environment. Paperclip's custody guarantees
+end at injection: the agent process can read, log, or forward the value, so
+treat any secret bound to an agent as exposed to that agent. See the custody
+boundaries note in the [secrets deploy guide](/deploy/secrets#custody-boundaries).
+
+## Portability
+
+Company export/import APIs represent agent and project environment requirements
+as declarations in the package manifest. Exports omit secret values, secret IDs,
+provider references, and encrypted provider material. Use:
+
+```sh
+pnpm paperclipai secrets declarations --company-id {companyId}
+```
+
+to inspect the declarations that an export would emit before moving a package.

docs/cli/overview.md

@@ -57,6 +57,16 @@ pnpm paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
 export PAPERCLIP_API_KEY=...
 ```
 
+Secret operations are available under `paperclipai secrets`:
+
+```sh
+pnpm paperclipai secrets declarations --company-id <company-id> --kind secret
+pnpm paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
+pnpm paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
+pnpm paperclipai secrets doctor --company-id <company-id>
+pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+```
+
 Context is stored at `~/.paperclip/context.json`.
 
 ## Command Categories

docs/cli/setup-commands.md

@@ -67,7 +67,8 @@ Validates:
 
 - Server configuration
 - Database connectivity
-- Secrets adapter configuration
+- Secrets adapter configuration, including AWS Secrets Manager non-secret env
+  config when selected
 - Storage configuration
 - Missing key files
 
@@ -81,6 +82,13 @@ pnpm paperclipai configure --section secrets
 pnpm paperclipai configure --section storage
 ```
 
+`--section secrets` updates the deployment-level provider used as the fallback
+for secrets that do not target a specific company vault. Per-company provider
+vaults (named instances, default vault selection, multiple vaults per provider,
+coming-soon GCP/Vault) live in the board UI under
+`Company Settings → Secrets → Provider vaults` and the
+`/api/companies/{companyId}/secret-provider-configs` API.
+
 ## `paperclipai env`
 
 Show resolved environment configuration:

docs/deploy/secrets.md

@@ -5,6 +5,52 @@ summary: Master key, encryption, and strict mode
 
 Paperclip encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references.
 
+## Custody Boundaries
+
+Paperclip protects secret values up to the moment they are handed to an agent
+or workload:
+
+- Storage: values are encrypted at rest by the active provider. The local
+  provider keeps them encrypted with a key that never leaves the host.
+- Transport: values are decrypted server-side and injected into the agent
+  process environment, SSH command env, sandbox driver, or HTTP request
+  immediately before the call. Paperclip does not return decrypted values to
+  the board UI.
+- Audit: each resolution records a non-sensitive event (secret id, version,
+  provider id, consumer, outcome) without the value or provider credentials.
+
+Once a value reaches the consuming process, Paperclip can no longer guarantee
+secrecy. The agent (or sandbox, or remote host) can read the value, write it to
+its own logs or transcript, or pass it to downstream tools. Treat any secret
+you bind to an agent as exposed to that agent. Limit blast radius with bindings
+(only bind what each agent needs), short-lived provider credentials where the
+provider supports them, and rotation when an agent transcript or downstream
+system might have captured a value.
+
+## Using Secrets In Runs
+
+Creating a company secret does not automatically create an environment variable.
+You use a secret by binding it into an agent, project, environment, or plugin
+configuration field that supports secret references.
+
+For agent and project environment variables:
+
+1. Create or link the secret in `Company Settings > Secrets`.
+2. Open the agent's `Environment variables` field, or the project's `Env`
+   field.
+3. Add the environment variable key the process expects, such as `GH_TOKEN` or
+   `OPENAI_API_KEY`.
+4. Set the row source to `Secret`, select the stored secret, and choose either
+   `latest` or a pinned version.
+
+At runtime, Paperclip resolves the selected secret server-side and injects the
+resolved value under the env key from the binding row. The stored secret name
+can be human-readable; the binding key is what the agent process receives.
+
+Project env applies to every issue run in that project. When a project env key
+matches an agent env key, the project value wins before Paperclip injects its
+own `PAPERCLIP_*` runtime variables.
+
 ## Default Provider: `local_encrypted`
 
 Secrets are encrypted with a local master key stored at:
@@ -14,6 +60,13 @@ Secrets are encrypted with a local master key stored at:
 ```
 
 This key is auto-created during onboarding. The key never leaves your machine.
+Paperclip best-effort enforces `0600` permissions when it creates or loads the
+key file. `paperclipai doctor` and the provider health API warn when the file is
+readable by group or other users.
+
+Back up the key file together with database backups. A database backup without
+the key cannot decrypt local secrets, and a key backup without the database
+metadata is not enough to restore named secret versions.
 
 ## Configuration
 
@@ -35,6 +88,7 @@ Validate secrets config:
 
 ```sh
 pnpm paperclipai doctor
+pnpm paperclipai secrets doctor --company-id <company-id>
 ```
 
 ### Environment Overrides
@@ -55,15 +109,279 @@ PAPERCLIP_SECRETS_STRICT_MODE=true
 
 Recommended for any deployment beyond local trusted.
 
+Authenticated deployments default strict mode on unless explicitly overridden by
+configuration or `PAPERCLIP_SECRETS_STRICT_MODE=false`.
+
+## External References
+
+Provider-owned secrets can be linked without copying values into Paperclip by
+using `managedMode: "external_reference"` plus a provider `externalRef`.
+Paperclip stores metadata and a non-sensitive fingerprint, never the value.
+Runtime resolution remains server-side and binding-enforced.
+
+The built-in AWS, GCP, and Vault provider IDs currently accept external
+reference metadata, but runtime resolution requires provider configuration in the
+deployment. Their provider health check reports this as a warning until
+configured.
+
+For hosted Paperclip Cloud on AWS, see the AWS Secrets Manager operational
+contract — required env vars, IAM/KMS scoping, naming and tag conventions, and
+backup/rotation/incident runbooks — in `doc/SECRETS-AWS-PROVIDER.md`.
+
+## Provider Vaults
+
+A *provider vault* is a named, company-scoped configuration that points secret
+material at one of the supported provider backends. Each company can configure
+multiple vaults, including more than one vault per provider family, and pick a
+default vault per family for new secret operations. Existing secrets created
+before any vault was configured continue to resolve through the deployment-level
+default provider — no migration is required.
+
+### Where to configure
+
+Open `Company Settings → Secrets` in the board UI and switch to the
+`Provider vaults` tab. From there you can:
+
+- Create a vault for any supported provider family.
+- Edit the non-secret config of an existing vault.
+- Set one ready vault per provider family as the company default.
+- Disable a vault (a soft delete that keeps audit history).
+- Run a health check against a vault and read the latest result inline.
+
+The same operations are exposed under
+`/api/companies/{companyId}/secret-provider-configs` for automation. See the
+[secrets API reference](/api/secrets#provider-vaults) for the full route table.
+
+### Custody Of Provider Credentials
+
+Provider vaults intentionally store only **non-sensitive** configuration:
+region, project id, namespace, prefix, KMS key id, mount path, address, and
+similar routing metadata. The API, UI, and activity log never accept, return,
+or display provider credential values. Submitting fields with names like
+`accessKeyId`, `secretAccessKey`, `token`, `password`, `serviceAccountJson`,
+`privateKey`, `keyFile`, `unsealKey`, or any common credential alias is rejected
+at validation time.
+
+That keeps the bootstrap rule from the AWS provider applicable to every
+provider family: **provider credentials live in deployment infrastructure
+identity, not in Paperclip company secrets**. Allowed credential sources are
+workload identity attached to the Paperclip server (instance profile, IRSA, ECS
+task role), `AWS_PROFILE` / SSO / shared config for local runs, an orchestrator
+secret store that boots the server, or short-lived shell credentials for local
+development. Do not paste long-lived API keys into the vault config.
+
+### Vault Status
+
+Each vault carries a status that drives what the runtime can do with it:
+
+| Status        | Meaning                                                                                       |
+|---------------|-----------------------------------------------------------------------------------------------|
+| `ready`       | Selectable for create/rotate/resolve. Eligible to be the default.                             |
+| `warning`     | Saved config exists but health needs attention (for example missing AWS env). Still selectable. |
+| `coming_soon` | Visible and editable as draft metadata, but locked out of all runtime operations.            |
+| `disabled`    | Soft-deleted. Hidden from the secret create/rotate flow.                                      |
+
+`gcp_secret_manager` and `vault` are pinned to `coming_soon` until their
+runtime modules ship. The settings UI lets you save draft configuration for
+those providers (and surfaces them on the vault list), but secret create,
+rotate, and resolve calls that target a coming-soon vault fail with a clear
+runtime-locked error.
+
+### Default Vault Behavior
+
+A company can mark **one** ready (or warning) vault per provider family as the
+default. The secret create and rotate dialogs preselect the default vault for
+the chosen provider so operators don't have to remember which vault to pick.
+Coming-soon and disabled vaults cannot be marked default; attempting to do so
+returns a validation error. Setting a new default automatically clears the
+previous default for that provider.
+
+If a secret is created without any `providerConfigId` (no vaults exist yet, or
+the operator clears the selector), runtime resolution falls back to the
+deployment-level provider configuration — the same path existing installs use.
+This keeps secrets created before any provider vault was configured working
+without migration. Picking the default in the UI is an explicit selection, not
+a runtime fallback: the create call still sends an explicit `providerConfigId`.
+
+### Multiple Vaults Per Provider
+
+Multiple vaults from the same provider family are first-class. Common patterns:
+
+- Two AWS vaults pointing at different regions or KMS keys for environment
+  separation.
+- A staging Vault address alongside a production address.
+- A dedicated GCP project for a single product line while the rest of the
+  company uses another.
+
+Each vault has its own display name, status, default flag, and health record.
+Operators choose the vault explicitly when creating or rotating a secret; the
+default vault is preselected to avoid accidental routing to the wrong account.
+
+### Per-Vault Health Checks
+
+`POST /api/secret-provider-configs/{id}/health` runs a provider-specific health
+probe and stores the result on the vault row. The settings UI exposes the same
+action and renders the result inline. Health responses include a status,
+operator-facing message, and structured guidance (such as missing env var
+names, expected credential sources, and backup reminders). They never include
+provider credentials or secret values. Coming-soon vaults always return a
+`runtime_locked` health code and never call into provider modules.
+
+### Provider-Specific Notes
+
+**Local encrypted vaults** wrap the existing `local_encrypted` provider. The
+master key path and rotation guidance described above still applies. A local
+vault config is mostly bookkeeping plus an explicit acknowledgement that the
+key file is backed up alongside the database.
+
+**AWS Secrets Manager vaults** read the per-vault `region`, `namespace`,
+`secretNamePrefix`, `kmsKeyId`, `ownerTag`, and `environmentTag` to route
+managed writes and external-reference reads. The vault config supplements (and
+can override) the deployment-level `PAPERCLIP_SECRETS_AWS_*` env. Bootstrap
+credentials still come from the AWS SDK default credential chain — see
+`doc/SECRETS-AWS-PROVIDER.md` for the full IAM and KMS contract.
+
+**GCP Secret Manager** and **HashiCorp Vault** vaults are coming soon. You can
+save draft `projectId`, `location`, `namespace`, `address`, and `mountPath`
+metadata so the company is ready to flip them on when the provider modules
+ship. Vault `address` values must be origin-only `http(s)://host[:port]` URLs;
+addresses with embedded credentials, paths, query strings, or fragments are
+rejected.
+
+### Remote Import From AWS Vaults
+
+AWS provider vaults can import existing AWS Secrets Manager entries as
+Paperclip `external_reference` secrets. This is a metadata-only link: Paperclip
+stores the AWS ARN/path, a fingerprint/version reference, and binding metadata.
+It does not read, copy, store, log, or display the remote plaintext secret
+value during preview or import.
+
+Operator flow in the board UI:
+
+1. Open `Company Settings -> Secrets`.
+2. Confirm at least one AWS provider vault is `ready` or `warning`.
+3. In the `Secrets` tab, choose `Import from vault`.
+4. Select an AWS vault, search the remote inventory, and load more pages as
+   needed.
+5. Check the rows to import, review/edit the Paperclip name and key, then
+   submit.
+6. Review the result summary for created, skipped, and failed rows.
+
+The preview list is intentionally paged and search-first. AWS accounts can have
+large per-Region inventories, and `ListSecrets` returns opaque `NextToken`
+cursors. Do not expect Paperclip to crawl a whole account in the background;
+load pages deliberately and retry throttled requests with backoff.
+
+Remote import exposes AWS secret metadata visible to the Paperclip runtime
+role, including names/ARNs and safe derived fields such as dates, whether a
+description or KMS key exists, and tag count. Treat names, ARNs, tags, and
+search text as operational metadata that may be sensitive. The API and activity
+log must not store raw descriptions, tags, plaintext values, provider
+credentials, or raw AWS error blobs.
+
+Required AWS posture:
+
+- Preview needs optional `secretsmanager:ListSecrets` permission on
+  `Resource: "*"`. AWS does not support constraining `ListSecrets` to
+  individual secret ARNs or tags as an IAM boundary.
+- Preview/import must not call `secretsmanager:GetSecretValue`,
+  `secretsmanager:BatchGetSecretValue`, or KMS decrypt.
+- Runtime resolution of an imported reference still needs
+  `secretsmanager:GetSecretValue` on the selected external ARN/path and KMS
+  decrypt when that secret uses a customer-managed key.
+- Keep managed create/rotate/delete permissions scoped to the Paperclip
+  deployment prefix. Do not broaden managed write/delete permissions just
+  because import inventory is enabled.
+
+Safe scoping comes from deployment posture rather than AWS list filtering:
+dedicated Paperclip runtime roles per environment/account, AWS vaults pointed at
+the intended account and Region, import-enabled roles only where inventory
+exposure is acceptable, and board-only access to the import routes. Tags and
+name filters are search aids, not a permission model.
+
+If import preview fails:
+
+- `AccessDenied` or `not authorized`: the runtime role is missing
+  `secretsmanager:ListSecrets`; add the optional inventory statement only if
+  remote import should be enabled for that vault.
+- Throttling: retry after a short delay and narrow the search before loading
+  more pages.
+- Invalid cursor: refresh the preview; AWS `NextToken` values are opaque and
+  can expire or become stale.
+- Runtime resolution failure after import: verify `GetSecretValue` and KMS
+  decrypt scope for the selected external secret. Being visible in inventory is
+  not proof that the runtime role can read the value.
+
+### Backup And Restore
+
+Each provider family has a different backup story:
+
+- `local_encrypted`: back up the local master key file and the Paperclip
+  database together. Either alone is not enough to restore the encrypted
+  values, and the vault row only records the path and acknowledgement, not the
+  key bytes.
+- `aws_secrets_manager`: back up Paperclip's database for vault metadata
+  (vault id, region, prefix, KMS key id, default flag, bindings, version
+  pointers). The actual secret values live in AWS Secrets Manager under the
+  configured prefix; restore by pointing the same Paperclip company at the
+  same AWS namespace and confirming the runtime role still has
+  `GetSecretValue` plus KMS decrypt. The full restore checklist lives in
+  `doc/SECRETS-AWS-PROVIDER.md`.
+- `gcp_secret_manager` and `vault`: while these are coming soon, only the
+  draft vault config exists in Paperclip. Database backups capture it. There
+  is nothing to restore on the provider side until runtime support lands.
+
+### AWS Provider Bootstrap Boundary
+
+The AWS Secrets Manager provider cannot bootstrap itself from Paperclip
+`company_secrets`. Its initial AWS access must be present before the server can
+create or resolve AWS-backed company secrets, regardless of whether you use the
+deployment-level default or a per-company vault.
+
+For Paperclip Cloud, provision the server runtime IAM role/workload identity,
+KMS key, deployment prefix, and non-secret `PAPERCLIP_SECRETS_AWS_*` environment
+configuration before enabling AWS-backed secrets in the board UI. For
+self-hosted and local runs, use the AWS SDK default credential chain: instance
+profile, ECS task role, EKS IRSA/OIDC web identity, AWS SSO/shared config via
+`AWS_PROFILE`, or short-lived shell credentials for local development.
+
+Do not store AWS root credentials or long-lived IAM user access keys in
+Paperclip secrets. Bootstrap material belongs in infrastructure IAM/workload
+identity, the process environment, an AWS profile, or the orchestrator secret
+store.
+
 ## Migrating Inline Secrets
 
 If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:
 
 ```sh
+pnpm paperclipai secrets migrate-inline-env --company-id <company-id>
+pnpm paperclipai secrets migrate-inline-env --company-id <company-id> --apply
+
+# low-level script for direct database maintenance
 pnpm secrets:migrate-inline-env         # dry run
 pnpm secrets:migrate-inline-env --apply # apply migration
 ```
 
+Use the CLI command for normal operations because it goes through the Paperclip
+API, creates or rotates secret records, and updates agent env bindings with
+audit logging.
+
+## Portable Declarations
+
+Company exports include only environment declarations. They do not include
+secret IDs, provider references, encrypted material, or plaintext values.
+
+```sh
+pnpm paperclipai secrets declarations --company-id <company-id> --kind secret
+```
+
+Before importing a package into another instance, use those declarations to
+create local values or link hosted provider references in the target deployment.
+For hosted providers such as AWS Secrets Manager, the hosted provider remains
+the value custodian; Paperclip stores metadata and provider version references,
+not provider credentials or plaintext secret values.
+
 ## Secret References in Agent Config
 
 Agent environment variables use secret references:

package.json

@@ -15,9 +15,12 @@
     "build-storybook": "pnpm --filter @paperclipai/ui build-storybook",
     "build": "pnpm run preflight:workspace-links && pnpm -r build",
     "typecheck": "pnpm run preflight:workspace-links && pnpm -r typecheck",
+    "typecheck:build-gaps": "pnpm run preflight:workspace-links && node scripts/run-typecheck-build-gaps.mjs",
     "test": "pnpm run test:run",
     "test:watch": "pnpm run preflight:workspace-links && vitest",
     "test:run": "pnpm run preflight:workspace-links && node scripts/run-vitest-stable.mjs",
+    "test:run:general": "pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk build && node scripts/run-vitest-stable.mjs --mode general",
+    "test:run:serialized": "pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk build && node scripts/run-vitest-stable.mjs --mode serialized",
     "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",
@@ -30,13 +33,14 @@
     "release:stable": "./scripts/release.sh stable",
     "release:github": "./scripts/create-github-release.sh",
     "release:rollback": "./scripts/rollback-latest.sh",
+    "release:bootstrap-package": "node scripts/bootstrap-npm-package.mjs",
     "check:tokens": "node scripts/check-forbidden-tokens.mjs",
     "docs:dev": "cd docs && npx mintlify dev",
     "smoke:openclaw-join": "./scripts/smoke/openclaw-join.sh",
     "smoke:openclaw-docker-ui": "./scripts/smoke/openclaw-docker-ui.sh",
     "smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh",
     "smoke:terminal-bench-loop-skill": "node scripts/smoke/terminal-bench-loop-skill-smoke.mjs",
-    "test:release-registry": "node --test scripts/verify-release-registry-state.test.mjs",
+    "test:release-registry": "node --test scripts/verify-release-registry-state.test.mjs scripts/release-package-map.test.mjs scripts/check-release-package-bootstrap.test.mjs",
     "test:e2e": "npx playwright test --config tests/e2e/playwright.config.ts",
     "test:e2e:headed": "npx playwright test --config tests/e2e/playwright.config.ts --headed",
     "test:e2e:multiuser-authenticated": "npx playwright test --config tests/e2e/playwright-multiuser-authenticated.config.ts",

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

@@ -55,9 +55,15 @@ describe("command managed runtime", () => {
           ...process.env,
           ...input.env,
         };
-        const command = input.command === "sh" ? "/bin/sh" : input.command;
+        const command =
+          input.command === "sh" ? "/bin/sh" : input.command === "bash" ? "/bin/bash" : input.command;
         const args = [...(input.args ?? [])];
-        if (input.stdin != null && input.command === "sh" && args[0] === "-lc" && typeof args[1] === "string") {
+        if (
+          input.stdin != null &&
+          (input.command === "sh" || input.command === "bash") &&
+          (args[0] === "-c" || args[0] === "-lc") &&
+          typeof args[1] === "string"
+        ) {
           env.PAPERCLIP_TEST_STDIN = input.stdin;
           args[1] = `printf '%s' \"$PAPERCLIP_TEST_STDIN\" | (${args[1]})`;
         }
@@ -125,4 +131,90 @@ describe("command managed runtime", () => {
       .toMatchObject({ code: "ENOENT" });
     expect(calls.every((call) => call.stdin == null)).toBe(true);
   });
+
+  it("runs setup commands from a stable root cwd when staging into a nested remote workspace dir", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-command-runtime-nested-"));
+    cleanupDirs.push(rootDir);
+
+    const localWorkspaceDir = path.join(rootDir, "local-workspace");
+    const remoteBaseDir = path.join(rootDir, "remote-base");
+    const remoteWorkspaceDir = path.join(remoteBaseDir, ".paperclip-runtime", "runs", "test", "workspace");
+    await mkdir(localWorkspaceDir, { recursive: true });
+    await mkdir(remoteBaseDir, { recursive: true });
+    await writeFile(path.join(localWorkspaceDir, "README.md"), "local workspace\n", "utf8");
+
+    const calls: Array<{
+      command: string;
+      args?: string[];
+      cwd?: string;
+      env?: Record<string, string>;
+      stdin?: string;
+      timeoutMs?: number;
+    }> = [];
+    const runner = {
+      execute: async (input: {
+        command: string;
+        args?: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        stdin?: string;
+        timeoutMs?: number;
+      }): Promise<RunProcessResult> => {
+        calls.push({ ...input });
+        const startedAt = new Date().toISOString();
+        try {
+          const result = await execFile(input.command === "sh" ? "/bin/sh" : input.command, input.args ?? [], {
+            cwd: input.cwd,
+            env: {
+              ...process.env,
+              ...input.env,
+            },
+            maxBuffer: 32 * 1024 * 1024,
+            timeout: input.timeoutMs,
+          });
+          return {
+            exitCode: 0,
+            signal: null,
+            timedOut: false,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            pid: null,
+            startedAt,
+          };
+        } catch (error) {
+          const err = error as NodeJS.ErrnoException & {
+            stdout?: string;
+            stderr?: string;
+            code?: string | number | null;
+            signal?: NodeJS.Signals | null;
+            killed?: boolean;
+          };
+          return {
+            exitCode: typeof err.code === "number" ? err.code : null,
+            signal: err.signal ?? null,
+            timedOut: Boolean(err.killed && input.timeoutMs),
+            stdout: err.stdout ?? "",
+            stderr: err.stderr ?? "",
+            pid: null,
+            startedAt,
+          };
+        }
+      },
+    };
+
+    await prepareCommandManagedRuntime({
+      runner,
+      spec: {
+        remoteCwd: remoteBaseDir,
+        timeoutMs: 30_000,
+      },
+      adapterKey: "codex",
+      workspaceLocalDir: localWorkspaceDir,
+      workspaceRemoteDir: remoteWorkspaceDir,
+    });
+
+    expect(calls.length).toBeGreaterThan(0);
+    expect(calls.every((call) => call.cwd === "/")).toBe(true);
+    await expect(readFile(path.join(remoteWorkspaceDir, "README.md"), "utf8")).resolves.toBe("local workspace\n");
+  });
 });

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

@@ -6,6 +6,7 @@ import {
   type SandboxManagedRuntimeClient,
   type SandboxRemoteExecutionSpec,
 } from "./sandbox-managed-runtime.js";
+import { preferredShellForSandbox, shellCommandArgs } from "./sandbox-shell.js";
 import type { RunProcessResult } from "./server-utils.js";
 
 export interface CommandManagedRuntimeRunner {
@@ -23,10 +24,10 @@ export interface CommandManagedRuntimeRunner {
 
 export interface CommandManagedRuntimeSpec {
   providerKey?: string | null;
+  shellCommand?: "bash" | "sh" | null;
   leaseId?: string | null;
   remoteCwd: string;
   timeoutMs?: number | null;
-  paperclipApiUrl?: string | null;
 }
 
 export type CommandManagedRuntimeAsset = SandboxManagedRuntimeAsset;
@@ -56,14 +57,16 @@ function requireSuccessfulResult(result: RunProcessResult, action: string): void
 
 export function createCommandManagedRuntimeClient(input: {
   runner: CommandManagedRuntimeRunner;
-  remoteCwd: string;
+  commandCwd: string;
   timeoutMs: number;
+  shellCommand?: "bash" | "sh" | null;
 }): SandboxManagedRuntimeClient {
+  const shellCommand = preferredShellForSandbox(input.shellCommand);
   const runShell = async (script: string, opts: { stdin?: string; timeoutMs?: number } = {}) => {
     const result = await input.runner.execute({
-      command: "sh",
-      args: ["-lc", script],
-      cwd: input.remoteCwd,
+      command: shellCommand,
+      args: shellCommandArgs(script),
+      cwd: input.commandCwd,
       stdin: opts.stdin,
       timeoutMs: opts.timeoutMs ?? input.timeoutMs,
     });
@@ -112,18 +115,18 @@ export function createCommandManagedRuntimeClient(input: {
     },
     remove: async (remotePath) => {
       const result = await input.runner.execute({
-        command: "sh",
-        args: ["-lc", `rm -rf ${shellQuote(remotePath)}`],
-        cwd: input.remoteCwd,
+        command: shellCommand,
+        args: shellCommandArgs(`rm -rf ${shellQuote(remotePath)}`),
+        cwd: input.commandCwd,
         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,
+        command: shellCommand,
+        args: shellCommandArgs(command),
+        cwd: input.commandCwd,
         timeoutMs: options.timeoutMs,
       });
       requireSuccessfulResult(result, command);
@@ -141,9 +144,15 @@ export async function prepareCommandManagedRuntime(input: {
   preserveAbsentOnRestore?: string[];
   assets?: CommandManagedRuntimeAsset[];
   installCommand?: string | null;
+  /** When provided alongside `installCommand`, skip the install if `command -v <detectCommand>` succeeds. */
+  detectCommand?: 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;
+  // Managed-runtime sync/restore scripts use absolute paths throughout, so
+  // run them from a stable cwd. The target workspace itself may be removed or
+  // recreated during a run, which breaks shell startup if we chdir into it.
+  const commandCwd = "/";
   const runtimeSpec: SandboxRemoteExecutionSpec = {
     transport: "sandbox",
     provider: input.spec.providerKey ?? "sandbox",
@@ -151,22 +160,62 @@ export async function prepareCommandManagedRuntime(input: {
     remoteCwd: workspaceRemoteDir,
     timeoutMs,
     apiKey: null,
-    paperclipApiUrl: input.spec.paperclipApiUrl ?? null,
   };
   const client = createCommandManagedRuntimeClient({
     runner: input.runner,
-    remoteCwd: workspaceRemoteDir,
+    commandCwd,
     timeoutMs,
+    shellCommand: input.spec.shellCommand,
   });
+  const shellCommand = preferredShellForSandbox(input.spec.shellCommand);
 
   if (input.installCommand?.trim()) {
+    const installCommand = input.installCommand.trim();
+    const detectCommand = input.detectCommand?.trim();
+    // Skip the install when the binary is already on PATH. Without this
+    // probe the install runs unconditionally on every execute() call (and
+    // also runs a second time after `ensureAdapterExecutionTargetCommandResolvable`
+    // has already installed it during the resolvability gate).
+    if (detectCommand) {
+      const probe = await input.runner.execute({
+        command: shellCommand,
+        args: shellCommandArgs(`command -v ${shellQuote(detectCommand)} >/dev/null 2>&1`),
+        cwd: commandCwd,
+        timeoutMs,
+      });
+      if (!probe.timedOut && (probe.exitCode ?? 1) === 0) {
+        return await prepareSandboxManagedRuntime({
+          spec: runtimeSpec,
+          client,
+          adapterKey: input.adapterKey,
+          workspaceLocalDir: input.workspaceLocalDir,
+          workspaceRemoteDir,
+          workspaceExclude: mergeRuntimeExcludes(input.workspaceExclude),
+          preserveAbsentOnRestore: input.preserveAbsentOnRestore,
+          assets: input.assets,
+        });
+      }
+    }
     const result = await input.runner.execute({
-      command: "sh",
-      args: ["-lc", input.installCommand.trim()],
-      cwd: workspaceRemoteDir,
+      command: shellCommand,
+      args: shellCommandArgs(installCommand),
+      cwd: commandCwd,
       timeoutMs,
     });
-    requireSuccessfulResult(result, input.installCommand.trim());
+    // A failed install is not always fatal: the CLI may already be on PATH
+    // from a previous lease, the template image, or another path entry. Log
+    // and continue rather than aborting the agent run; downstream code that
+    // exec's the CLI will surface a clear "command not found" if it is in
+    // fact missing. The test path's `maybeRunSandboxInstallCommand` already
+    // honors this contract — keep them consistent.
+    if (result.timedOut || (result.exitCode ?? 0) !== 0) {
+      const tail = (text: string) =>
+        text.split(/\r?\n/).filter((line) => line.trim().length > 0).slice(-3).join(" | ").slice(0, 480);
+      const reason = result.timedOut ? "timed out" : `exited ${result.exitCode ?? "?"}`;
+      console.warn(
+        `[paperclip] managed-runtime install command ${reason}: ${installCommand} :: ${tail(result.stderr || result.stdout)}`,
+      );
+    }
   }
 
   return await prepareSandboxManagedRuntime({

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

@@ -5,8 +5,12 @@ import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {
+  DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
   adapterExecutionTargetSessionIdentity,
   adapterExecutionTargetToRemoteSpec,
+  adapterExecutionTargetUsesPaperclipBridge,
+  ensureAdapterExecutionTargetCommandResolvable,
+  resolveAdapterExecutionTargetTimeoutSec,
   runAdapterExecutionTargetProcess,
   runAdapterExecutionTargetShellCommand,
   startAdapterExecutionTargetPaperclipBridge,
@@ -18,6 +22,7 @@ describe("sandbox adapter execution targets", () => {
   const cleanupDirs: string[] = [];
 
   afterEach(async () => {
+    vi.unstubAllEnvs();
     while (cleanupDirs.length > 0) {
       const dir = cleanupDirs.pop();
       if (!dir) continue;
@@ -39,7 +44,8 @@ describe("sandbox adapter execution targets", () => {
         onSpawn?: (meta: { pid: number; startedAt: string }) => Promise<void>;
       }) => {
         counter += 1;
-        return runChildProcess(`sandbox-run-${counter}`, input.command, input.args ?? [], {
+        const command = input.command === "bash" ? "/bin/bash" : input.command;
+        return runChildProcess(`sandbox-run-${counter}`, command, input.args ?? [], {
           cwd: input.cwd ?? process.cwd(),
           env: input.env ?? {},
           stdin: input.stdin,
@@ -103,10 +109,92 @@ describe("sandbox adapter execution targets", () => {
       environmentId: "env-1",
       leaseId: "lease-1",
       remoteCwd: "/workspace",
-      paperclipTransport: "bridge",
     });
   });
 
+  it("applies the remote sandbox fallback when adapter timeoutSec is unset", () => {
+    const sandboxTarget: AdapterSandboxExecutionTarget = {
+      kind: "remote",
+      transport: "sandbox",
+      remoteCwd: "/workspace",
+      runner: createLocalSandboxRunner(),
+    };
+
+    expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, 0)).toBe(
+      DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+    );
+    expect(resolveAdapterExecutionTargetTimeoutSec(sandboxTarget, 90)).toBe(90);
+    expect(resolveAdapterExecutionTargetTimeoutSec({
+      kind: "remote",
+      transport: "ssh",
+      remoteCwd: "/workspace",
+      spec: {
+        host: "127.0.0.1",
+        port: 22,
+        username: "fixture",
+        remoteWorkspacePath: "/workspace",
+        remoteCwd: "/workspace",
+        privateKey: "KEY",
+        knownHosts: "host key",
+        strictHostKeyChecking: true,
+      },
+    }, 0)).toBe(0);
+  });
+
+  it("uses the caller timeout override when installing a missing sandbox command", async () => {
+    const runner = {
+      execute: vi.fn()
+        .mockResolvedValueOnce({
+          exitCode: 1,
+          signal: null,
+          timedOut: false,
+          stdout: "",
+          stderr: "",
+          pid: null,
+          startedAt: new Date().toISOString(),
+        })
+        .mockResolvedValueOnce({
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          stdout: "",
+          stderr: "",
+          pid: null,
+          startedAt: new Date().toISOString(),
+        })
+        .mockResolvedValueOnce({
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          stdout: "/usr/bin/opencode\n",
+          stderr: "",
+          pid: null,
+          startedAt: new Date().toISOString(),
+        }),
+    };
+    const target: AdapterSandboxExecutionTarget = {
+      kind: "remote",
+      transport: "sandbox",
+      remoteCwd: "/workspace",
+      timeoutMs: 300_000,
+      runner,
+    };
+
+    await ensureAdapterExecutionTargetCommandResolvable(
+      "opencode",
+      target,
+      "/local/workspace",
+      {},
+      { installCommand: "npm install -g opencode", timeoutSec: 1800 },
+    );
+
+    expect(runner.execute).toHaveBeenNthCalledWith(2, expect.objectContaining({
+      command: "sh",
+      args: ["-c", "npm install -g opencode"],
+      timeoutMs: 1_800_000,
+    }));
+  });
+
   it("runs shell commands through the same runner", async () => {
     const runner = {
       execute: vi.fn(async () => ({
@@ -134,7 +222,155 @@ describe("sandbox adapter execution targets", () => {
 
     expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
       command: "sh",
-      args: ["-lc", 'printf %s "$HOME"'],
+      args: ["-c", 'printf %s "$HOME"'],
+      cwd: "/workspace",
+      timeoutMs: 7000,
+    }));
+  });
+
+  it("strips inherited host identity env before sandbox execution", async () => {
+    vi.stubEnv("PATH", "/host/bin:/usr/bin");
+    vi.stubEnv("HOME", "/Users/local");
+    vi.stubEnv("TMPDIR", "/var/folders/local/T");
+
+    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",
+      remoteCwd: "/workspace",
+      runner,
+    };
+
+    await runAdapterExecutionTargetProcess("run-1b", target, "agent-cli", ["--json"], {
+      cwd: "/local/workspace",
+      env: {
+        PATH: "/host/bin:/usr/bin",
+        HOME: "/Users/local",
+        TMPDIR: "/var/folders/local/T",
+        SAFE_VALUE: "visible",
+      },
+      timeoutSec: 5,
+      graceSec: 1,
+      onLog: async () => {},
+    });
+
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      env: {
+        SAFE_VALUE: "visible",
+      },
+    }));
+  });
+
+  it("preserves explicit remote identity env overrides for sandbox execution", async () => {
+    vi.stubEnv("PATH", "/host/bin:/usr/bin");
+    vi.stubEnv("HOME", "/Users/local");
+
+    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",
+      remoteCwd: "/workspace",
+      runner,
+    };
+
+    await runAdapterExecutionTargetProcess("run-1c", target, "agent-cli", ["--json"], {
+      cwd: "/local/workspace",
+      env: {
+        PATH: "/custom/remote/bin:/usr/bin",
+        HOME: "/home/sandbox",
+        SAFE_VALUE: "visible",
+      },
+      timeoutSec: 5,
+      graceSec: 1,
+      onLog: async () => {},
+    });
+
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      env: {
+        PATH: "/custom/remote/bin:/usr/bin",
+        HOME: "/home/sandbox",
+        SAFE_VALUE: "visible",
+      },
+    }));
+  });
+
+  it("treats SSH targets as bridge-only", () => {
+    const target = {
+      kind: "remote" as const,
+      transport: "ssh" as const,
+      remoteCwd: "/workspace",
+      spec: {
+        host: "ssh.example.test",
+        port: 22,
+        username: "paperclip",
+        remoteWorkspacePath: "/workspace",
+        remoteCwd: "/workspace",
+        privateKey: null,
+        knownHosts: null,
+        strictHostKeyChecking: true,
+      },
+    };
+
+    expect(adapterExecutionTargetUsesPaperclipBridge(target)).toBe(true);
+    expect(adapterExecutionTargetSessionIdentity(target)).toEqual({
+      transport: "ssh",
+      host: "ssh.example.test",
+      port: 22,
+      username: "paperclip",
+      remoteCwd: "/workspace",
+    });
+  });
+
+  it("uses the provider-declared shell for sandbox helper commands", 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",
+      providerKey: "custom-provider",
+      shellCommand: "bash",
+      remoteCwd: "/workspace",
+      runner,
+    };
+
+    await runAdapterExecutionTargetShellCommand("run-2b", target, 'printf %s "$HOME"', {
+      cwd: "/local/workspace",
+      env: {},
+      timeoutSec: 7,
+    });
+
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      command: "bash",
+      args: ["-c", 'printf %s "$HOME"'],
       cwd: "/workspace",
       timeoutMs: 7000,
     }));
@@ -174,7 +410,6 @@ describe("sandbox adapter execution targets", () => {
       environmentId: "env-1",
       leaseId: "lease-1",
       remoteCwd,
-      paperclipTransport: "bridge",
       runner: createLocalSandboxRunner(),
       timeoutMs: 30_000,
     };
@@ -214,6 +449,60 @@ describe("sandbox adapter execution targets", () => {
     }
   });
 
+  it("uses the effective adapter timeout when starting the sandbox callback bridge", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-execution-target-bridge-timeout-"));
+    cleanupDirs.push(rootDir);
+    const remoteCwd = path.join(rootDir, "workspace");
+    const runtimeRootDir = path.join(remoteCwd, ".paperclip-runtime", "codex");
+    await mkdir(runtimeRootDir, { recursive: true });
+
+    const delegateRunner = createLocalSandboxRunner();
+    const runner = {
+      execute: vi.fn(async (input: Parameters<typeof delegateRunner.execute>[0]) => delegateRunner.execute(input)),
+    };
+    const apiServer = createServer((req, res) => {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+    });
+    await new Promise<void>((resolve, reject) => {
+      apiServer.once("error", reject);
+      apiServer.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = apiServer.address();
+    if (!address || typeof address === "string") {
+      throw new Error("Expected the bridge timeout test API server to listen on a TCP port.");
+    }
+
+    const target: AdapterSandboxExecutionTarget = {
+      kind: "remote",
+      transport: "sandbox",
+      providerKey: "cloudflare",
+      environmentId: "env-1",
+      leaseId: "lease-1",
+      remoteCwd,
+      runner,
+      timeoutMs: 30_000,
+    };
+
+    const bridge = await startAdapterExecutionTargetPaperclipBridge({
+      runId: "run-bridge-timeout",
+      target,
+      runtimeRootDir,
+      adapterKey: "codex",
+      timeoutSec: DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC,
+      hostApiToken: "real-run-jwt",
+      hostApiUrl: `http://127.0.0.1:${address.port}`,
+    });
+    try {
+      expect(bridge).not.toBeNull();
+      expect(runner.execute).toHaveBeenCalled();
+      expect(runner.execute.mock.calls.some(([input]) => input.timeoutMs === 1_800_000)).toBe(true);
+    } finally {
+      await bridge?.stop();
+      await new Promise<void>((resolve) => apiServer.close(() => resolve()));
+    }
+  });
+
   it("fails oversized host responses with a 502 before returning them to the sandbox client", async () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-execution-target-bridge-limit-"));
     cleanupDirs.push(rootDir);
@@ -252,7 +541,6 @@ describe("sandbox adapter execution targets", () => {
       environmentId: "env-1",
       leaseId: "lease-1",
       remoteCwd,
-      paperclipTransport: "bridge",
       runner: createLocalSandboxRunner(),
       timeoutMs: 30_000,
     };

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

@@ -1,14 +1,18 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import * as ssh from "./ssh.js";
+import * as serverUtils from "./server-utils.js";
 import {
   adapterExecutionTargetUsesManagedHome,
+  ensureAdapterExecutionTargetRuntimeCommandInstalled,
   resolveAdapterExecutionTargetCwd,
+  runAdapterExecutionTargetProcess,
   runAdapterExecutionTargetShellCommand,
 } from "./execution-target.js";
 
 describe("runAdapterExecutionTargetShellCommand", () => {
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.unstubAllEnvs();
   });
 
   it("quotes remote shell commands with the shared SSH quoting helper", async () => {
@@ -41,16 +45,68 @@ describe("runAdapterExecutionTargetShellCommand", () => {
       },
     );
 
+    // runSshCommand owns profile sourcing and the outer shell wrapper —
+    // the caller passes the raw command string. Wrapping it here would
+    // double-nest the login shell and re-source profiles after the explicit
+    // env override, silently undoing identity-var preservation.
     expect(runSshCommandSpy).toHaveBeenCalledWith(
       expect.objectContaining({
         host: "ssh.example.test",
         username: "ssh-user",
       }),
-      `sh -lc ${ssh.shellQuote(`printf '%s\\n' "$HOME" && echo "it's ok"`)}`,
+      `printf '%s\\n' "$HOME" && echo "it's ok"`,
       expect.any(Object),
     );
   });
 
+  it("sanitizes inherited host env before SSH shell execution", async () => {
+    vi.stubEnv("PATH", "/host/bin:/usr/bin");
+    vi.stubEnv("HOME", "/Users/local");
+
+    const runSshCommandSpy = vi.spyOn(ssh, "runSshCommand").mockResolvedValue({
+      stdout: "",
+      stderr: "",
+    });
+
+    await runAdapterExecutionTargetShellCommand(
+      "run-1b",
+      {
+        kind: "remote",
+        transport: "ssh",
+        remoteCwd: "/srv/paperclip/workspace",
+        spec: {
+          host: "ssh.example.test",
+          port: 22,
+          username: "ssh-user",
+          remoteCwd: "/srv/paperclip/workspace",
+          remoteWorkspacePath: "/srv/paperclip/workspace",
+          privateKey: null,
+          knownHosts: null,
+          strictHostKeyChecking: true,
+        },
+      },
+      "env",
+      {
+        cwd: "/tmp/local",
+        env: {
+          PATH: "/host/bin:/usr/bin",
+          HOME: "/Users/local",
+          SAFE_VALUE: "visible",
+        },
+      },
+    );
+
+    expect(runSshCommandSpy).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.any(String),
+      expect.objectContaining({
+        env: {
+          SAFE_VALUE: "visible",
+        },
+      }),
+    );
+  });
+
   it("returns a timedOut result when the SSH shell command times out", async () => {
     vi.spyOn(ssh, "runSshCommand").mockRejectedValue(Object.assign(new Error("timed out"), {
       code: "ETIMEDOUT",
@@ -161,6 +217,145 @@ describe("runAdapterExecutionTargetShellCommand", () => {
   });
 });
 
+describe("runAdapterExecutionTargetProcess", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("sanitizes inherited host env before SSH process execution", async () => {
+    vi.stubEnv("PATH", "/host/bin:/usr/bin");
+    vi.stubEnv("HOME", "/Users/local");
+
+    const runChildProcessSpy = vi.spyOn(serverUtils, "runChildProcess").mockResolvedValue({
+      exitCode: 0,
+      signal: null,
+      timedOut: false,
+      stdout: "",
+      stderr: "",
+      pid: null,
+      startedAt: new Date().toISOString(),
+    });
+
+    await runAdapterExecutionTargetProcess(
+      "run-ssh-process",
+      {
+        kind: "remote",
+        transport: "ssh",
+        remoteCwd: "/srv/paperclip/workspace",
+        spec: {
+          host: "ssh.example.test",
+          port: 22,
+          username: "ssh-user",
+          remoteCwd: "/srv/paperclip/workspace",
+          remoteWorkspacePath: "/srv/paperclip/workspace",
+          privateKey: null,
+          knownHosts: null,
+          strictHostKeyChecking: true,
+        },
+      },
+      "agent-cli",
+      ["--json"],
+      {
+        cwd: "/tmp/local",
+        env: {
+          PATH: "/host/bin:/usr/bin",
+          HOME: "/Users/local",
+          SAFE_VALUE: "visible",
+        },
+        timeoutSec: 5,
+        graceSec: 1,
+        onLog: async () => {},
+      },
+    );
+
+    expect(runChildProcessSpy).toHaveBeenCalledWith(
+      "run-ssh-process",
+      "agent-cli",
+      ["--json"],
+      expect.objectContaining({
+        env: {
+          SAFE_VALUE: "visible",
+        },
+      }),
+    );
+  });
+});
+
+describe("ensureAdapterExecutionTargetRuntimeCommandInstalled", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("runs install commands for sandbox targets", async () => {
+    const runner = {
+      execute: vi.fn(async () => ({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: "",
+        stderr: "",
+        pid: null,
+        startedAt: new Date().toISOString(),
+      })),
+    };
+
+    await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+      runId: "run-install",
+      target: {
+        kind: "remote",
+        transport: "sandbox",
+        providerKey: "e2b",
+        remoteCwd: "/remote/workspace",
+        runner,
+      },
+      installCommand: "npm install -g @google/gemini-cli",
+      cwd: "/local/workspace",
+      env: { PATH: "/usr/bin" },
+      timeoutSec: 30,
+    });
+
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      command: "sh",
+      args: ["-c", "npm install -g @google/gemini-cli"],
+      cwd: "/remote/workspace",
+      env: { PATH: "/usr/bin" },
+      timeoutMs: 30_000,
+    }));
+  });
+
+  it("skips install commands for SSH targets", async () => {
+    const runSshCommandSpy = vi.spyOn(ssh, "runSshCommand").mockResolvedValue({
+      stdout: "",
+      stderr: "",
+    });
+
+    await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+      runId: "run-skip",
+      target: {
+        kind: "remote",
+        transport: "ssh",
+        remoteCwd: "/srv/paperclip/workspace",
+        spec: {
+          host: "ssh.example.test",
+          port: 22,
+          username: "ssh-user",
+          remoteCwd: "/srv/paperclip/workspace",
+          remoteWorkspacePath: "/srv/paperclip/workspace",
+          privateKey: null,
+          knownHosts: null,
+          strictHostKeyChecking: true,
+        },
+      },
+      installCommand: "npm install -g @google/gemini-cli",
+      cwd: "/tmp/local",
+      env: {},
+    });
+
+    expect(runSshCommandSpy).not.toHaveBeenCalled();
+  });
+});
+
 describe("resolveAdapterExecutionTargetCwd", () => {
   const sshTarget = {
     kind: "remote" as const,

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

@@ -18,7 +18,7 @@ import {
   startSandboxCallbackBridgeServer,
   startSandboxCallbackBridgeWorker,
 } from "./sandbox-callback-bridge.js";
-import { parseSshRemoteExecutionSpec, runSshCommand, shellQuote } from "./ssh.js";
+import { createSshCommandManagedRuntimeRunner, parseSshRemoteExecutionSpec, runSshCommand, shellQuote } from "./ssh.js";
 import {
   ensureCommandResolvable,
   resolveCommandForLogs,
@@ -26,6 +26,8 @@ import {
   type RunProcessResult,
   type TerminalResultCleanupOptions,
 } from "./server-utils.js";
+import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
+import { preferredShellForSandbox, shellCommandArgs } from "./sandbox-shell.js";
 
 export interface AdapterLocalExecutionTarget {
   kind: "local";
@@ -39,7 +41,6 @@ export interface AdapterSshExecutionTarget {
   environmentId?: string | null;
   leaseId?: string | null;
   remoteCwd: string;
-  paperclipApiUrl?: string | null;
   spec: SshRemoteExecutionSpec;
 }
 
@@ -47,11 +48,10 @@ export interface AdapterSandboxExecutionTarget {
   kind: "remote";
   transport: "sandbox";
   providerKey?: string | null;
+  shellCommand?: "bash" | "sh" | null;
   environmentId?: string | null;
   leaseId?: string | null;
   remoteCwd: string;
-  paperclipApiUrl?: string | null;
-  paperclipTransport?: "direct" | "bridge";
   timeoutMs?: number | null;
   runner?: CommandManagedRuntimeRunner;
 }
@@ -67,6 +67,7 @@ export type AdapterManagedRuntimeAsset = RemoteManagedRuntimeAsset;
 
 export interface PreparedAdapterExecutionTargetRuntime {
   target: AdapterExecutionTarget;
+  workspaceRemoteDir: string | null;
   runtimeRootDir: string | null;
   assetDirs: Record<string, string>;
   restoreWorkspace(): Promise<void>;
@@ -96,6 +97,10 @@ export interface AdapterExecutionTargetPaperclipBridgeHandle {
   stop(): Promise<void>;
 }
 
+export { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
+
+export const DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC = 1_800;
+
 function parseObject(value: unknown): Record<string, unknown> {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -126,13 +131,9 @@ function resolveDefaultPaperclipApiUrl(): string {
   return `http://${runtimeHost}:${runtimePort}`;
 }
 
-function resolveSandboxPaperclipTransport(
-  target: Pick<AdapterSandboxExecutionTarget, "paperclipTransport" | "paperclipApiUrl">,
-): "direct" | "bridge" {
-  if (target.paperclipTransport === "direct" || target.paperclipTransport === "bridge") {
-    return target.paperclipTransport;
-  }
-  return target.paperclipApiUrl ? "direct" : "bridge";
+function isBridgeDebugEnabled(env: NodeJS.ProcessEnv): boolean {
+  const value = env.PAPERCLIP_BRIDGE_DEBUG?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
 }
 
 function isAdapterExecutionTargetInstance(value: unknown): value is AdapterExecutionTarget {
@@ -169,6 +170,33 @@ export function adapterExecutionTargetRemoteCwd(
   return target?.kind === "remote" ? target.remoteCwd : localCwd;
 }
 
+export function overrideAdapterExecutionTargetRemoteCwd(
+  target: AdapterExecutionTarget | null | undefined,
+  remoteCwd: string | null | undefined,
+): AdapterExecutionTarget | null | undefined {
+  const nextRemoteCwd = remoteCwd?.trim();
+  if (!target || target.kind !== "remote" || !nextRemoteCwd) {
+    return target;
+  }
+  if (target.remoteCwd === nextRemoteCwd) {
+    return target;
+  }
+  if (target.transport === "ssh") {
+    return {
+      ...target,
+      remoteCwd: nextRemoteCwd,
+      spec: {
+        ...target.spec,
+        remoteCwd: nextRemoteCwd,
+      },
+    };
+  }
+  return {
+    ...target,
+    remoteCwd: nextRemoteCwd,
+  };
+}
+
 export function resolveAdapterExecutionTargetCwd(
   target: AdapterExecutionTarget | null | undefined,
   configuredCwd: string | null | undefined,
@@ -180,21 +208,10 @@ export function resolveAdapterExecutionTargetCwd(
   return adapterExecutionTargetRemoteCwd(target, localFallbackCwd);
 }
 
-export function adapterExecutionTargetPaperclipApiUrl(
-  target: AdapterExecutionTarget | null | undefined,
-): string | null {
-  if (target?.kind !== "remote") return null;
-  if (target.transport === "ssh") return target.paperclipApiUrl ?? target.spec.paperclipApiUrl ?? null;
-  if (resolveSandboxPaperclipTransport(target) === "bridge") return null;
-  return target.paperclipApiUrl ?? null;
-}
-
 export function adapterExecutionTargetUsesPaperclipBridge(
   target: AdapterExecutionTarget | null | undefined,
 ): boolean {
-  return target?.kind === "remote" &&
-    target.transport === "sandbox" &&
-    resolveSandboxPaperclipTransport(target) === "bridge";
+  return target?.kind === "remote";
 }
 
 export function describeAdapterExecutionTarget(
@@ -207,6 +224,26 @@ export function describeAdapterExecutionTarget(
   return `sandbox environment${target.providerKey ? ` (${target.providerKey})` : ""}`;
 }
 
+export function resolveAdapterExecutionTargetTimeoutSec(
+  target: AdapterExecutionTarget | null | undefined,
+  configuredTimeoutSec: number | null | undefined,
+): number {
+  const normalizedConfiguredTimeoutSec =
+    typeof configuredTimeoutSec === "number" && Number.isFinite(configuredTimeoutSec) && configuredTimeoutSec > 0
+      ? Math.floor(configuredTimeoutSec)
+      : 0;
+  if (normalizedConfiguredTimeoutSec > 0) return normalizedConfiguredTimeoutSec;
+  // Local and SSH adapters preserve the historical "0 means no adapter
+  // timeout" behavior. Sandbox-backed runs execute through provider RPCs
+  // that usually apply their own shorter command defaults, so request an
+  // explicit longer timeout for full adapter runs when the adapter leaves
+  // timeoutSec unset.
+  if (target?.kind === "remote" && target.transport === "sandbox") {
+    return DEFAULT_REMOTE_SANDBOX_ADAPTER_TIMEOUT_SEC;
+  }
+  return 0;
+}
+
 function requireSandboxRunner(target: AdapterSandboxExecutionTarget): CommandManagedRuntimeRunner {
   if (target.runner) return target.runner;
   throw new Error(
@@ -214,13 +251,47 @@ function requireSandboxRunner(target: AdapterSandboxExecutionTarget): CommandMan
   );
 }
 
+function preferredSandboxShell(target: AdapterSandboxExecutionTarget): "bash" | "sh" {
+  return preferredShellForSandbox(target.shellCommand);
+}
+
+type AdapterCommandCapableExecutionTarget = AdapterSshExecutionTarget | AdapterSandboxExecutionTarget;
+
+function adapterExecutionTargetCommandRunner(target: AdapterCommandCapableExecutionTarget): CommandManagedRuntimeRunner {
+  if (target.transport === "ssh") {
+    return createSshCommandManagedRuntimeRunner({
+      spec: target.spec,
+      defaultCwd: target.remoteCwd,
+      maxBufferBytes: DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES * 4,
+    });
+  }
+  return requireSandboxRunner(target);
+}
+
+function adapterExecutionTargetShellCommand(target: AdapterCommandCapableExecutionTarget): "bash" | "sh" {
+  return target.transport === "ssh" ? "sh" : preferredSandboxShell(target);
+}
+
+function adapterExecutionTargetTimeoutMs(
+  target: AdapterCommandCapableExecutionTarget,
+): number | null | undefined {
+  return target.transport === "sandbox" ? target.timeoutMs : undefined;
+}
+
 export async function ensureAdapterExecutionTargetCommandResolvable(
   command: string,
   target: AdapterExecutionTarget | null | undefined,
   cwd: string,
   env: NodeJS.ProcessEnv,
+  options: { installCommand?: string | null; timeoutSec?: number | null } = {},
 ) {
   if (target?.kind === "remote" && target.transport === "sandbox") {
+    await ensureSandboxCommandResolvable(
+      command,
+      target,
+      options.installCommand?.trim() || null,
+      options.timeoutSec,
+    );
     return;
   }
   await ensureCommandResolvable(command, cwd, env, {
@@ -228,6 +299,87 @@ export async function ensureAdapterExecutionTargetCommandResolvable(
   });
 }
 
+async function probeSandboxCommandResolvable(
+  command: string,
+  target: AdapterSandboxExecutionTarget,
+): Promise<{ resolved: boolean; timedOut: boolean; stderr: string }> {
+  const runner = requireSandboxRunner(target);
+  const probeScript = `command -v ${shellQuote(command)}`;
+  const result = await runner.execute({
+    command: "sh",
+    args: ["-c", probeScript],
+    cwd: target.remoteCwd,
+    timeoutMs: target.timeoutMs ?? 15_000,
+  });
+  return {
+    resolved: !result.timedOut && (result.exitCode ?? 1) === 0,
+    timedOut: result.timedOut,
+    stderr: result.stderr.trim(),
+  };
+}
+
+async function ensureSandboxCommandResolvable(
+  command: string,
+  target: AdapterSandboxExecutionTarget,
+  installCommand: string | null,
+  timeoutSec?: number | null,
+): Promise<void> {
+  // Probe whether the binary is resolvable inside the sandbox. We previously
+  // short-circuited this for sandbox targets, which let the caller report a
+  // success message even when the CLI was missing from the image. Now we run
+  // a real `command -v` through the same runner the hello probe will use, so
+  // the first step honestly reflects whether the binary is on PATH. The
+  // sandbox provider is responsible for sourcing login profiles (e2b mirrors
+  // SSH's buildSshSpawnTarget) so this and the hello probe agree on PATH.
+  let probe = await probeSandboxCommandResolvable(command, target);
+  if (probe.resolved) return;
+  if (probe.timedOut) {
+    throw new Error(`Timed out checking command "${command}" on sandbox target.`);
+  }
+
+  // If the caller supplied an install command, attempt the install once via
+  // the sandbox runner (which the sandbox provider wraps in a login shell)
+  // and re-probe before reporting failure. This lets fresh sandbox leases
+  // bring up the CLI before the resolvability gate, mirroring the test path.
+  let installFailureDetail: string | null = null;
+  if (installCommand) {
+    const runner = requireSandboxRunner(target);
+    const installTimeoutMs =
+      typeof timeoutSec === "number" && Number.isFinite(timeoutSec) && timeoutSec > 0
+        ? Math.floor(timeoutSec * 1000)
+        : target.timeoutMs ?? 300_000;
+    try {
+      const installResult = await runner.execute({
+        command: "sh",
+        args: shellCommandArgs(installCommand),
+        cwd: target.remoteCwd,
+        timeoutMs: installTimeoutMs,
+      });
+      if (installResult.timedOut) {
+        installFailureDetail = `install command timed out: ${installCommand}`;
+      } else if ((installResult.exitCode ?? 0) !== 0) {
+        const tail = (text: string) =>
+          text.split(/\r?\n/).filter((line) => line.trim().length > 0).slice(-2).join(" | ").slice(0, 240);
+        const reason = tail(installResult.stderr || installResult.stdout) || `exit ${installResult.exitCode ?? "?"}`;
+        installFailureDetail = `install command exited ${installResult.exitCode ?? "?"}: ${reason}`;
+      }
+    } catch (err) {
+      installFailureDetail = `install command threw: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    probe = await probeSandboxCommandResolvable(command, target);
+    if (probe.resolved) return;
+    if (probe.timedOut) {
+      throw new Error(`Timed out checking command "${command}" on sandbox target.`);
+    }
+  }
+
+  const probeStderr = probe.stderr.length > 0 ? ` probe stderr: ${probe.stderr}` : "";
+  const installDetail = installFailureDetail ? `; ${installFailureDetail}` : "";
+  throw new Error(
+    `Command "${command}" is not installed or not on PATH in the sandbox environment${installDetail}.${probeStderr}`,
+  );
+}
+
 export async function resolveAdapterExecutionTargetCommandForLogs(
   command: string,
   target: AdapterExecutionTarget | null | undefined,
@@ -251,11 +403,12 @@ export async function runAdapterExecutionTargetProcess(
 ): Promise<RunProcessResult> {
   if (target?.kind === "remote" && target.transport === "sandbox") {
     const runner = requireSandboxRunner(target);
+    const env = sanitizeRemoteExecutionEnv(options.env);
     return await runner.execute({
       command,
       args,
       cwd: target.remoteCwd,
-      env: options.env,
+      env,
       stdin: options.stdin,
       timeoutMs: options.timeoutSec > 0 ? options.timeoutSec * 1000 : target.timeoutMs ?? undefined,
       onLog: options.onLog,
@@ -265,9 +418,14 @@ export async function runAdapterExecutionTargetProcess(
     });
   }
 
+  const env =
+    target?.kind === "remote" && target.transport === "ssh"
+      ? sanitizeRemoteExecutionEnv(options.env)
+      : options.env;
+
   return await runChildProcess(runId, command, args, {
     cwd: options.cwd,
-    env: options.env,
+    env,
     stdin: options.stdin,
     timeoutSec: options.timeoutSec,
     graceSec: options.graceSec,
@@ -287,9 +445,16 @@ export async function runAdapterExecutionTargetShellCommand(
   const onLog = options.onLog ?? (async () => {});
   if (target?.kind === "remote") {
     const startedAt = new Date().toISOString();
+    const env = sanitizeRemoteExecutionEnv(options.env);
     if (target.transport === "ssh") {
       try {
-        const result = await runSshCommand(target.spec, `sh -lc ${shellQuote(command)}`, {
+        // Pass the raw command — `runSshCommand` owns profile sourcing and
+        // the outer shell wrapper. Wrapping again here would nest a second
+        // shell after the explicit `env KEY=VAL` overrides, re-sourcing
+        // login profiles AFTER the override and silently undoing any
+        // identity var (NVM_DIR / PATH / etc.) that a profile re-exports.
+        const result = await runSshCommand(target.spec, command, {
+          env,
           timeoutMs: (options.timeoutSec ?? 15) * 1000,
         });
         if (result.stdout) await onLog("stdout", result.stdout);
@@ -341,11 +506,12 @@ export async function runAdapterExecutionTargetShellCommand(
       }
     }
 
+    const shellCommand = preferredSandboxShell(target);
     return await requireSandboxRunner(target).execute({
-      command: "sh",
-      args: ["-lc", command],
+      command: shellCommand,
+      args: shellCommandArgs(command),
       cwd: target.remoteCwd,
-      env: options.env,
+      env,
       timeoutMs: (options.timeoutSec ?? 15) * 1000,
       onLog,
     });
@@ -366,6 +532,111 @@ export async function runAdapterExecutionTargetShellCommand(
   );
 }
 
+export interface AdapterSandboxInstallCommandCheck {
+  code: string;
+  level: "info" | "warn" | "error";
+  message: string;
+  detail?: string;
+  hint?: string;
+}
+
+// Best-effort run of an adapter-supplied install command on a sandbox target
+// before the resolvability + hello probe. Returns null for non-sandbox
+// targets so callers can no-op. Returns a structured check otherwise — never
+// throws — so the rest of the test still runs and reports the post-install
+// state honestly. Caller pushes the check into its result array; the test
+// report shows whether install was attempted and what came back.
+export async function maybeRunSandboxInstallCommand(input: {
+  runId: string;
+  target: AdapterExecutionTarget | null | undefined;
+  adapterKey: string;
+  installCommand: string;
+  /** When provided, skip the install if `command -v <detectCommand>` succeeds. */
+  detectCommand?: string | null;
+  env?: Record<string, string>;
+  timeoutSec?: number;
+}): Promise<AdapterSandboxInstallCommandCheck | null> {
+  const { target, adapterKey, installCommand } = input;
+  if (!target || target.kind !== "remote" || target.transport !== "sandbox") {
+    return null;
+  }
+  const trimmed = installCommand.trim();
+  if (trimmed.length === 0) return null;
+
+  const code = `${adapterKey}_install_command_run`;
+
+  // Skip install when the binary is already on PATH. Avoids running
+  // network-dependent installers (e.g. `curl ... | bash`) on every test
+  // probe when the CLI is preinstalled on the lease/template.
+  const detectCommand = input.detectCommand?.trim();
+  if (detectCommand) {
+    try {
+      const probe = await runAdapterExecutionTargetShellCommand(
+        input.runId,
+        target,
+        `command -v ${shellQuote(detectCommand)} >/dev/null 2>&1`,
+        {
+          cwd: target.remoteCwd,
+          env: input.env ?? {},
+          timeoutSec: 30,
+          graceSec: 5,
+        },
+      );
+      if (!probe.timedOut && probe.exitCode === 0) {
+        return {
+          code,
+          level: "info",
+          message: `${detectCommand} already on PATH; skipped install.`,
+        };
+      }
+    } catch {
+      // Fall through to actually running the install — failure to probe
+      // is not a reason to skip the install gate.
+    }
+  }
+
+  let result;
+  try {
+    result = await runAdapterExecutionTargetShellCommand(input.runId, target, trimmed, {
+      cwd: target.remoteCwd,
+      env: input.env ?? {},
+      timeoutSec: input.timeoutSec ?? 240,
+      graceSec: 10,
+    });
+  } catch (err) {
+    return {
+      code,
+      level: "warn",
+      message: "Install command threw before completion.",
+      detail: err instanceof Error ? err.message : String(err),
+    };
+  }
+  const tail = (text: string) =>
+    text.split(/\r?\n/).filter((line) => line.trim().length > 0).slice(-3).join(" | ").slice(0, 480);
+  if (result.timedOut) {
+    return {
+      code,
+      level: "warn",
+      message: `Install command timed out: ${trimmed}`,
+      detail: tail(result.stderr || result.stdout),
+    };
+  }
+  if ((result.exitCode ?? 1) === 0) {
+    return {
+      code,
+      level: "info",
+      message: `Install command ran: ${trimmed}`,
+      ...(tail(result.stdout) ? { detail: tail(result.stdout) } : {}),
+    };
+  }
+  return {
+    code,
+    level: "warn",
+    message: `Install command exited ${result.exitCode}: ${trimmed}`,
+    detail: tail(result.stderr || result.stdout),
+  };
+}
+
 export async function readAdapterExecutionTargetHomeDir(
   runId: string,
   target: AdapterExecutionTarget | null | undefined,
@@ -381,6 +652,91 @@ export async function readAdapterExecutionTargetHomeDir(
   return homeDir.length > 0 ? homeDir : null;
 }
 
+export async function ensureAdapterExecutionTargetRuntimeCommandInstalled(input: {
+  runId: string;
+  target: AdapterExecutionTarget | null | undefined;
+  installCommand?: string | null;
+  detectCommand?: string | null;
+  cwd: string;
+  env: Record<string, string>;
+  timeoutSec?: number;
+  graceSec?: number;
+  onLog?: AdapterExecutionTargetShellOptions["onLog"];
+}): Promise<void> {
+  const installCommand = input.installCommand?.trim();
+  if (!installCommand || input.target?.kind !== "remote" || input.target.transport !== "sandbox") {
+    return;
+  }
+
+  const detectCommand = input.detectCommand?.trim();
+  if (detectCommand) {
+    const probe = await runAdapterExecutionTargetShellCommand(
+      input.runId,
+      input.target,
+      `command -v ${shellQuote(detectCommand)} >/dev/null 2>&1`,
+      {
+        cwd: input.cwd,
+        env: input.env,
+        timeoutSec: input.timeoutSec,
+        graceSec: input.graceSec,
+      },
+    );
+    if (!probe.timedOut && probe.exitCode === 0) {
+      return;
+    }
+  }
+
+  const result = await runAdapterExecutionTargetShellCommand(
+    input.runId,
+    input.target,
+    installCommand,
+    {
+      cwd: input.cwd,
+      env: input.env,
+      timeoutSec: input.timeoutSec,
+      graceSec: input.graceSec,
+      onLog: input.onLog,
+    },
+  );
+
+  // A failed or timed-out install is not necessarily fatal: the CLI may already
+  // be on PATH from a previous lease's install, the template image, or another
+  // path entry. Re-run the detect probe (when one is configured) so a transient
+  // install failure does not abort the agent run when the binary is reachable.
+  const installFailed = result.timedOut || (result.exitCode ?? 0) !== 0;
+  if (!installFailed) {
+    return;
+  }
+  if (detectCommand) {
+    const recheck = await runAdapterExecutionTargetShellCommand(
+      input.runId,
+      input.target,
+      `command -v ${shellQuote(detectCommand)} >/dev/null 2>&1`,
+      {
+        cwd: input.cwd,
+        env: input.env,
+        timeoutSec: input.timeoutSec,
+        graceSec: input.graceSec,
+      },
+    );
+    if (!recheck.timedOut && recheck.exitCode === 0) {
+      if (input.onLog) {
+        const reason = result.timedOut ? "timed out" : `exited ${result.exitCode ?? "?"}`;
+        await input.onLog(
+          "stderr",
+          `[paperclip] Install command ${reason} (${installCommand}) but ${detectCommand} is on PATH; continuing.\n`,
+        );
+      }
+      return;
+    }
+  }
+
+  if (result.timedOut) {
+    throw new Error(`Timed out while installing the adapter runtime command via: ${installCommand}`);
+  }
+  throw new Error(`Failed to install the adapter runtime command via: ${installCommand}`);
+}
+
 export async function ensureAdapterExecutionTargetFile(
   runId: string,
   target: AdapterExecutionTarget | null | undefined,
@@ -458,15 +814,12 @@ export function adapterExecutionTargetSessionIdentity(
 ): Record<string, unknown> | null {
   if (!target || target.kind === "local") return null;
   if (target.transport === "ssh") return buildRemoteExecutionSessionIdentity(target.spec);
-  const paperclipTransport = resolveSandboxPaperclipTransport(target);
   return {
     transport: "sandbox",
     providerKey: target.providerKey ?? null,
     environmentId: target.environmentId ?? null,
     leaseId: target.leaseId ?? null,
     remoteCwd: target.remoteCwd,
-    paperclipTransport,
-    ...(paperclipTransport === "direct" && target.paperclipApiUrl ? { paperclipApiUrl: target.paperclipApiUrl } : {}),
   };
 }
 
@@ -485,9 +838,7 @@ export function adapterExecutionTargetSessionMatches(
     readStringMeta(parsedSaved, "providerKey") === current?.providerKey &&
     readStringMeta(parsedSaved, "environmentId") === current?.environmentId &&
     readStringMeta(parsedSaved, "leaseId") === current?.leaseId &&
-    readStringMeta(parsedSaved, "remoteCwd") === current?.remoteCwd &&
-    readStringMeta(parsedSaved, "paperclipTransport") === (current?.paperclipTransport ?? null) &&
-    readStringMeta(parsedSaved, "paperclipApiUrl") === (current?.paperclipApiUrl ?? null)
+    readStringMeta(parsedSaved, "remoteCwd") === current?.remoteCwd
   );
 }
 
@@ -512,14 +863,12 @@ export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTar
       environmentId: readStringMeta(parsed, "environmentId"),
       leaseId: readStringMeta(parsed, "leaseId"),
       remoteCwd: spec.remoteCwd,
-      paperclipApiUrl: readStringMeta(parsed, "paperclipApiUrl") ?? spec.paperclipApiUrl ?? null,
       spec,
     };
   }
 
   if (kind === "remote" && readStringMeta(parsed, "transport") === "sandbox") {
     const remoteCwd = readStringMeta(parsed, "remoteCwd");
-    const paperclipTransport = readStringMeta(parsed, "paperclipTransport");
     if (!remoteCwd) return null;
     return {
       kind: "remote",
@@ -528,11 +877,6 @@ export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTar
       environmentId: readStringMeta(parsed, "environmentId"),
       leaseId: readStringMeta(parsed, "leaseId"),
       remoteCwd,
-      paperclipApiUrl: readStringMeta(parsed, "paperclipApiUrl"),
-      paperclipTransport:
-        paperclipTransport === "direct" || paperclipTransport === "bridge"
-          ? paperclipTransport
-          : undefined,
       timeoutMs: typeof parsed.timeoutMs === "number" ? parsed.timeoutMs : null,
     };
   }
@@ -553,7 +897,6 @@ export function adapterExecutionTargetFromRemoteExecution(
       environmentId: metadata.environmentId ?? null,
       leaseId: metadata.leaseId ?? null,
       remoteCwd: ssh.remoteCwd,
-      paperclipApiUrl: ssh.paperclipApiUrl ?? null,
       spec: ssh,
     };
   }
@@ -575,18 +918,24 @@ export function readAdapterExecutionTarget(input: {
 }
 
 export async function prepareAdapterExecutionTargetRuntime(input: {
+  runId: string;
   target: AdapterExecutionTarget | null | undefined;
   adapterKey: string;
   workspaceLocalDir: string;
+  timeoutSec?: number;
+  workspaceRemoteDir?: string;
   workspaceExclude?: string[];
   preserveAbsentOnRestore?: string[];
   assets?: AdapterManagedRuntimeAsset[];
   installCommand?: string | null;
+  /** When provided alongside `installCommand`, skip the install if the binary is already on PATH. */
+  detectCommand?: string | null;
 }): Promise<PreparedAdapterExecutionTargetRuntime> {
   const target = input.target ?? { kind: "local" as const };
   if (target.kind === "local") {
     return {
       target,
+      workspaceRemoteDir: null,
       runtimeRootDir: null,
       assetDirs: {},
       restoreWorkspace: async () => {},
@@ -596,12 +945,15 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
   if (target.transport === "ssh") {
     const prepared = await prepareRemoteManagedRuntime({
       spec: target.spec,
+      runId: input.runId,
       adapterKey: input.adapterKey,
       workspaceLocalDir: input.workspaceLocalDir,
+      workspaceRemoteDir: input.workspaceRemoteDir,
       assets: input.assets,
     });
     return {
       target,
+      workspaceRemoteDir: prepared.workspaceRemoteDir,
       runtimeRootDir: prepared.runtimeRootDir,
       assetDirs: prepared.assetDirs,
       restoreWorkspace: prepared.restoreWorkspace,
@@ -612,20 +964,26 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
     runner: requireSandboxRunner(target),
     spec: {
       providerKey: target.providerKey,
+      shellCommand: target.shellCommand,
       leaseId: target.leaseId,
       remoteCwd: target.remoteCwd,
-      timeoutMs: target.timeoutMs,
-      paperclipApiUrl: target.paperclipApiUrl,
+      timeoutMs:
+        input.timeoutSec && input.timeoutSec > 0
+          ? input.timeoutSec * 1000
+          : target.timeoutMs,
     },
     adapterKey: input.adapterKey,
     workspaceLocalDir: input.workspaceLocalDir,
+    workspaceRemoteDir: input.workspaceRemoteDir,
     workspaceExclude: input.workspaceExclude,
     preserveAbsentOnRestore: input.preserveAbsentOnRestore,
     assets: input.assets,
     installCommand: input.installCommand,
+    detectCommand: input.detectCommand,
   });
   return {
     target,
+    workspaceRemoteDir: prepared.workspaceRemoteDir,
     runtimeRootDir: prepared.runtimeRootDir,
     assetDirs: prepared.assetDirs,
     restoreWorkspace: prepared.restoreWorkspace,
@@ -695,6 +1053,7 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
   target: AdapterExecutionTarget | null | undefined;
   runtimeRootDir: string | null | undefined;
   adapterKey: string;
+  timeoutSec?: number | null;
   hostApiToken: string | null | undefined;
   hostApiUrl?: string | null;
   onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
@@ -703,7 +1062,7 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
   if (!adapterExecutionTargetUsesPaperclipBridge(input.target)) {
     return null;
   }
-  if (!input.target || input.target.kind !== "remote" || input.target.transport !== "sandbox") {
+  if (!input.target || input.target.kind !== "remote") {
     return null;
   }
 
@@ -731,6 +1090,12 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
     process.env.PAPERCLIP_RUNTIME_API_URL?.trim() ||
     process.env.PAPERCLIP_API_URL?.trim() ||
     resolveDefaultPaperclipApiUrl();
+  const shellCommand = adapterExecutionTargetShellCommand(target);
+  const runner = adapterExecutionTargetCommandRunner(target);
+  const bridgeTimeoutMs =
+    typeof input.timeoutSec === "number" && Number.isFinite(input.timeoutSec) && input.timeoutSec > 0
+      ? Math.trunc(input.timeoutSec * 1000)
+      : adapterExecutionTargetTimeoutMs(target);
 
   await onLog(
     "stdout",
@@ -742,15 +1107,30 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
   let worker: Awaited<ReturnType<typeof startSandboxCallbackBridgeWorker>> | null = null;
   try {
     const client = createCommandManagedSandboxCallbackBridgeQueueClient({
-      runner: requireSandboxRunner(target),
+      runner,
       remoteCwd: target.remoteCwd,
-      timeoutMs: target.timeoutMs,
+      timeoutMs: bridgeTimeoutMs,
+      shellCommand,
     });
+    // PAPERCLIP_BRIDGE_DEBUG opts into verbose stdout logs of every bridge
+    // proxy request/response. The query string is logged verbatim, so callers
+    // who pass auth tokens or other sensitive values as query parameters
+    // should be aware those values appear in the host process's stdout when
+    // this flag is enabled. Only intended for active debugging in trusted
+    // environments.
+    const bridgeDebugEnabled = isBridgeDebugEnabled(process.env);
     worker = await startSandboxCallbackBridgeWorker({
       client,
       queueDir,
       maxBodyBytes,
       handleRequest: async (request) => {
+        const method = request.method.trim().toUpperCase() || "GET";
+        if (bridgeDebugEnabled) {
+          await onLog(
+            "stdout",
+            `[paperclip] Bridge proxy ${method} ${request.path}${request.query ? `?${request.query}` : ""}\n`,
+          );
+        }
         const headers = new Headers();
         for (const [key, value] of Object.entries(request.headers)) {
           if (value.trim().length === 0) continue;
@@ -758,13 +1138,18 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
         }
         headers.set("authorization", `Bearer ${hostApiToken}`);
         headers.set("x-paperclip-run-id", input.runId);
-        const method = request.method.trim().toUpperCase() || "GET";
         const response = await fetch(buildBridgeForwardUrl(hostApiUrl, request), {
           method,
           headers,
           ...(method === "GET" || method === "HEAD" ? {} : { body: request.body }),
           signal: AbortSignal.timeout(30_000),
         });
+        if (bridgeDebugEnabled) {
+          await onLog(
+            "stdout",
+            `[paperclip] Bridge proxy response ${response.status} for ${method} ${request.path}${request.query ? `?${request.query}` : ""}\n`,
+          );
+        }
         return {
           status: response.status,
           headers: buildBridgeResponseHeaders(response),
@@ -773,14 +1158,15 @@ export async function startAdapterExecutionTargetPaperclipBridge(input: {
       },
     });
     server = await startSandboxCallbackBridgeServer({
-      runner: requireSandboxRunner(target),
+      runner,
       remoteCwd: target.remoteCwd,
       assetRemoteDir,
       queueDir,
       bridgeToken,
       bridgeAsset,
-      timeoutMs: target.timeoutMs,
+      timeoutMs: bridgeTimeoutMs,
       maxBodyBytes,
+      shellCommand,
     });
   } catch (error) {
     await Promise.allSettled([

packages/adapter-utils/src/index.ts

@@ -27,6 +27,7 @@ export type {
   ConfigFieldOption,
   ConfigFieldSchema,
   AdapterConfigSchema,
+  AdapterRuntimeCommandSpec,
   ServerAdapterModule,
   QuotaWindow,
   ProviderQuotaResult,
@@ -59,6 +60,7 @@ export {
   REDACTED_COMMAND_TEXT_VALUE,
   redactCommandText,
 } from "./command-redaction.js";
+export { buildSandboxNpmInstallCommand } from "./sandbox-install-command.js";
 export { inferOpenAiCompatibleBiller } from "./billing.js";
 // Keep the root adapter-utils entry browser-safe because the UI imports it.
 // The sandbox callback bridge stays available via its dedicated subpath export.

packages/adapter-utils/src/remote-execution-env.ts

@@ -0,0 +1,49 @@
+const REMOTE_EXECUTION_ENV_IDENTITY_KEYS = new Set([
+  "PATH",
+  "HOME",
+  "PWD",
+  "SHELL",
+  "USER",
+  "LOGNAME",
+  "NVM_DIR",
+  "TMPDIR",
+  "TMP",
+  "TEMP",
+  "XDG_CONFIG_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_DATA_HOME",
+  "XDG_STATE_HOME",
+  "XDG_RUNTIME_DIR",
+]);
+
+function readEnvValueCaseInsensitive(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const direct = env[key];
+  if (typeof direct === "string") return direct;
+  const upper = key.toUpperCase();
+  for (const [candidateKey, candidateValue] of Object.entries(env)) {
+    if (candidateKey.toUpperCase() === upper && typeof candidateValue === "string") {
+      return candidateValue;
+    }
+  }
+  return undefined;
+}
+
+export function sanitizeRemoteExecutionEnv(
+  env: Record<string, string>,
+  inheritedEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const sanitized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    const normalizedKey = key.toUpperCase();
+    if (!REMOTE_EXECUTION_ENV_IDENTITY_KEYS.has(normalizedKey)) {
+      sanitized[key] = value;
+      continue;
+    }
+    const inheritedValue = readEnvValueCaseInsensitive(inheritedEnv, key);
+    if (typeof inheritedValue === "string" && inheritedValue === value) {
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}

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

@@ -5,6 +5,7 @@ import {
   restoreWorkspaceFromSshExecution,
   syncDirectoryToSsh,
 } from "./ssh.js";
+import { captureDirectorySnapshot } from "./workspace-restore-merge.js";
 
 export interface RemoteManagedRuntimeAsset {
   key: string;
@@ -44,7 +45,6 @@ export function buildRemoteExecutionSessionIdentity(spec: SshRemoteExecutionSpec
     port: spec.port,
     username: spec.username,
     remoteCwd: spec.remoteCwd,
-    ...(spec.paperclipApiUrl ? { paperclipApiUrl: spec.paperclipApiUrl } : {}),
   } as const;
 }
 
@@ -58,26 +58,37 @@ export function remoteExecutionSessionMatches(saved: unknown, current: SshRemote
     asString(parsedSaved.host) === currentIdentity.host &&
     asNumber(parsedSaved.port) === currentIdentity.port &&
     asString(parsedSaved.username) === currentIdentity.username &&
-    asString(parsedSaved.remoteCwd) === currentIdentity.remoteCwd &&
-    asString(parsedSaved.paperclipApiUrl) === asString(currentIdentity.paperclipApiUrl)
+    asString(parsedSaved.remoteCwd) === currentIdentity.remoteCwd
   );
 }
 
 export async function prepareRemoteManagedRuntime(input: {
   spec: SshRemoteExecutionSpec;
+  runId: string;
   adapterKey: string;
   workspaceLocalDir: string;
   workspaceRemoteDir?: string;
   assets?: RemoteManagedRuntimeAsset[];
 }): Promise<PreparedRemoteManagedRuntime> {
-  const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
+  const baseWorkspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
+  const workspaceRemoteDir = path.posix.join(
+    baseWorkspaceRemoteDir,
+    ".paperclip-runtime",
+    "runs",
+    input.runId,
+    "workspace",
+  );
   const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
 
-  await prepareWorkspaceForSshExecution({
+  const preparedWorkspace = await prepareWorkspaceForSshExecution({
     spec: input.spec,
     localDir: input.workspaceLocalDir,
     remoteDir: workspaceRemoteDir,
   });
+  const restoreExclude = preparedWorkspace.gitBacked ? [".git", ".paperclip-runtime"] : [".paperclip-runtime"];
+  const baselineSnapshot = await captureDirectorySnapshot(input.workspaceLocalDir, {
+    exclude: restoreExclude,
+  });
 
   const assetDirs: Record<string, string> = {};
   try {
@@ -97,6 +108,8 @@ export async function prepareRemoteManagedRuntime(input: {
       spec: input.spec,
       localDir: input.workspaceLocalDir,
       remoteDir: workspaceRemoteDir,
+      baselineSnapshot,
+      restoreGitHistory: preparedWorkspace.gitBacked,
     });
     throw error;
   }
@@ -112,6 +125,8 @@ export async function prepareRemoteManagedRuntime(input: {
         spec: input.spec,
         localDir: input.workspaceLocalDir,
         remoteDir: workspaceRemoteDir,
+        baselineSnapshot,
+        restoreGitHistory: preparedWorkspace.gitBacked,
       });
     },
   };

packages/adapter-utils/src/sandbox-callback-bridge.test.ts

@@ -3,14 +3,17 @@ import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promis
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { prepareCommandManagedRuntime } from "./command-managed-runtime.js";
 import {
+  authorizeSandboxCallbackBridgeRequestWithRoutes,
+  createCommandManagedSandboxCallbackBridgeQueueClient,
   createFileSystemSandboxCallbackBridgeQueueClient,
   createSandboxCallbackBridgeAsset,
   createSandboxCallbackBridgeToken,
   sandboxCallbackBridgeDirectories,
+  syncSandboxCallbackBridgeEntrypoint,
   startSandboxCallbackBridgeServer,
   startSandboxCallbackBridgeWorker,
 } from "./sandbox-callback-bridge.js";
@@ -37,9 +40,15 @@ describe("sandbox callback bridge", () => {
           ...process.env,
           ...input.env,
         };
-        const command = input.command === "sh" ? "/bin/sh" : input.command;
+        const command =
+          input.command === "sh" ? "/bin/sh" : input.command === "bash" ? "/bin/bash" : input.command;
         const args = [...(input.args ?? [])];
-        if (input.stdin != null && input.command === "sh" && args[0] === "-lc" && typeof args[1] === "string") {
+        if (
+          input.stdin != null &&
+          (input.command === "sh" || input.command === "bash") &&
+          (args[0] === "-c" || args[0] === "-lc") &&
+          typeof args[1] === "string"
+        ) {
           env.PAPERCLIP_TEST_STDIN = input.stdin;
           args[1] = `printf '%s' \"$PAPERCLIP_TEST_STDIN\" | (${args[1]})`;
         }
@@ -413,6 +422,145 @@ describe("sandbox callback bridge", () => {
     );
   });
 
+  it("handles SSH queue polling failures without emitting an unhandled rejection", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-bridge-ssh-failure-"));
+    cleanupDirs.push(rootDir);
+
+    const queueDir = path.posix.join(rootDir, "queue");
+    const unhandled: unknown[] = [];
+    const onUnhandledRejection = (reason: unknown) => {
+      unhandled.push(reason);
+    };
+    process.on("unhandledRejection", onUnhandledRejection);
+
+    try {
+      const worker = await startSandboxCallbackBridgeWorker({
+        client: {
+          makeDir: async () => {},
+          listJsonFiles: async () => {
+            throw new Error(
+              "list /remote/.paperclip-runtime/gemini/paperclip-bridge/queue/requests failed with exit code 255: kex_exchange_identification: read: Connection reset by peer",
+            );
+          },
+          readTextFile: async () => {
+            throw new Error("unexpected readTextFile");
+          },
+          writeTextFile: async () => {
+            throw new Error("unexpected writeTextFile");
+          },
+          rename: async () => {
+            throw new Error("unexpected rename");
+          },
+          remove: async () => {},
+        },
+        queueDir,
+        authorizeRequest: async () => null,
+        handleRequest: async () => ({
+          status: 200,
+          body: "ok",
+        }),
+      });
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      await worker.stop();
+      expect(unhandled).toEqual([]);
+    } finally {
+      process.off("unhandledRejection", onUnhandledRejection);
+    }
+  });
+
+  it("serializes remote response writes so stop does not recreate a late orphaned response", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-bridge-response-lock-"));
+    cleanupDirs.push(rootDir);
+
+    const localWorkspaceDir = path.join(rootDir, "local-workspace");
+    const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");
+    await mkdir(localWorkspaceDir, { recursive: true });
+    await mkdir(remoteWorkspaceDir, { recursive: true });
+    await writeFile(path.join(localWorkspaceDir, "README.md"), "bridge response lock test\n", "utf8");
+
+    const runner = createExecRunner();
+    const bridgeAsset = await createSandboxCallbackBridgeAsset();
+    cleanupFns.push(bridgeAsset.cleanup);
+    const prepared = await prepareCommandManagedRuntime({
+      runner,
+      spec: {
+        remoteCwd: remoteWorkspaceDir,
+        timeoutMs: 30_000,
+      },
+      adapterKey: "codex",
+      workspaceLocalDir: localWorkspaceDir,
+      assets: [{ key: "bridge", localDir: bridgeAsset.localDir }],
+    });
+
+    const queueDir = path.posix.join(prepared.runtimeRootDir, "paperclip-bridge");
+    const directories = sandboxCallbackBridgeDirectories(queueDir);
+    const bridgeToken = createSandboxCallbackBridgeToken();
+    const seenRequestIds: string[] = [];
+
+    const worker = await startSandboxCallbackBridgeWorker({
+      client: createCommandManagedSandboxCallbackBridgeQueueClient({
+        runner,
+        remoteCwd: remoteWorkspaceDir,
+        timeoutMs: 30_000,
+      }),
+      queueDir,
+      authorizeRequest: async () => null,
+      handleRequest: async (request) => {
+        seenRequestIds.push(request.id);
+        await new Promise((resolve) => setTimeout(resolve, 250));
+        return {
+          status: 200,
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ ok: true, id: request.id }),
+        };
+      },
+    });
+    cleanupFns.push(async () => {
+      await worker.stop();
+    });
+
+    const bridge = await startSandboxCallbackBridgeServer({
+      runner,
+      remoteCwd: remoteWorkspaceDir,
+      assetRemoteDir: prepared.assetDirs.bridge,
+      queueDir,
+      bridgeToken,
+      timeoutMs: 30_000,
+    });
+    cleanupFns.push(async () => {
+      await bridge.stop();
+    });
+
+    const responsePromise = fetch(`${bridge.baseUrl}/api/agents/me`, {
+      headers: {
+        authorization: `Bearer ${bridgeToken}`,
+      },
+    });
+
+    for (let attempt = 0; attempt < 50 && seenRequestIds.length === 0; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+
+    expect(seenRequestIds).toHaveLength(1);
+    await worker.stop({ drainTimeoutMs: 10 });
+
+    const response = await responsePromise;
+    expect(response.status).toBe(503);
+    await expect(response.json()).resolves.toEqual({
+      error: "Bridge worker stopped before request could be handled.",
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    await expect(readdir(directories.responsesDir)).resolves.toEqual([]);
+    await expect(
+      readdir(directories.responsesDir).then((entries) =>
+        entries.filter((entry) => entry.endsWith(".tmp") || entry.includes(".paperclip-write.lock")),
+      ),
+    ).resolves.toEqual([]);
+  });
+
   it("rejects non-JSON request bodies and full queues at the bridge server", async () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-bridge-server-guards-"));
     cleanupDirs.push(rootDir);
@@ -607,4 +755,229 @@ describe("sandbox callback bridge", () => {
       error: expect.stringMatching(/JSON|Unexpected|Unterminated/i),
     });
   });
+
+  it("reuses an already-uploaded bridge entrypoint when the remote file hash matches", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-bridge-sync-"));
+    cleanupDirs.push(rootDir);
+
+    const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");
+    const remoteAssetDir = path.posix.join(
+      remoteWorkspaceDir,
+      ".paperclip-runtime",
+      "codex",
+      "paperclip-bridge",
+      "server",
+    );
+    await mkdir(remoteWorkspaceDir, { recursive: true });
+
+    const bridgeAsset = await createSandboxCallbackBridgeAsset();
+    cleanupFns.push(bridgeAsset.cleanup);
+    const originalSource = await readFile(bridgeAsset.entrypoint, "utf8");
+    const expandedSource = `${originalSource}\n// bridge payload padding\n`;
+    await writeFile(bridgeAsset.entrypoint, expandedSource, "utf8");
+
+    const runner = createExecRunner();
+
+    const first = await syncSandboxCallbackBridgeEntrypoint({
+      runner,
+      remoteCwd: remoteWorkspaceDir,
+      assetRemoteDir: remoteAssetDir,
+      bridgeAsset,
+      timeoutMs: 30_000,
+    });
+    const second = await syncSandboxCallbackBridgeEntrypoint({
+      runner,
+      remoteCwd: remoteWorkspaceDir,
+      assetRemoteDir: remoteAssetDir,
+      bridgeAsset,
+      timeoutMs: 30_000,
+    });
+
+    expect(first.uploaded).toBe(true);
+    expect(second.uploaded).toBe(false);
+    await expect(readFile(path.posix.join(remoteAssetDir, "paperclip-bridge-server.mjs"), "utf8")).resolves.toBe(expandedSource);
+    await expect(
+      readdir(remoteAssetDir).then((entries) =>
+        entries.filter(
+          (entry) =>
+            entry.endsWith(".paperclip-upload.b64") ||
+            entry.endsWith(".partial") ||
+            entry === ".paperclip-bridge-upload.lock",
+        ),
+      ),
+    ).resolves.toEqual([]);
+  });
+
+  it("rejects a corrupted bridge entrypoint upload without committing a torn remote file", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-bridge-sync-corrupt-"));
+    cleanupDirs.push(rootDir);
+
+    const remoteWorkspaceDir = path.join(rootDir, "remote-workspace");
+    const remoteAssetDir = path.posix.join(
+      remoteWorkspaceDir,
+      ".paperclip-runtime",
+      "codex",
+      "paperclip-bridge",
+      "server",
+    );
+    await mkdir(remoteWorkspaceDir, { recursive: true });
+
+    const bridgeAsset = await createSandboxCallbackBridgeAsset();
+    cleanupFns.push(bridgeAsset.cleanup);
+    const runner = {
+      execute: async (input: {
+        command: string;
+        args?: string[];
+        cwd?: string;
+        env?: Record<string, string>;
+        stdin?: string;
+        timeoutMs?: number;
+      }) =>
+        await createExecRunner().execute({
+          ...input,
+          stdin: input.stdin != null ? "" : input.stdin,
+        }),
+    };
+
+    await expect(
+      syncSandboxCallbackBridgeEntrypoint({
+        runner,
+        remoteCwd: remoteWorkspaceDir,
+        assetRemoteDir: remoteAssetDir,
+        bridgeAsset,
+        timeoutMs: 30_000,
+      }),
+    ).rejects.toThrow(/sha mismatch/i);
+
+    await expect(readFile(path.posix.join(remoteAssetDir, "paperclip-bridge-server.mjs"), "utf8")).rejects.toThrow();
+    await expect(
+      readdir(remoteAssetDir).then((entries) =>
+        entries.filter(
+          (entry) =>
+            entry.endsWith(".paperclip-upload.b64") ||
+            entry.endsWith(".partial") ||
+            entry === ".paperclip-bridge-upload.lock",
+        ),
+      ),
+    ).resolves.toEqual([]);
+  });
+
+  it("permits the documented heartbeat surface and denies unrelated routes", () => {
+    const allowed: Array<{ method: string; path: string }> = [
+      { method: "GET", path: "/api/agents/me" },
+      { method: "GET", path: "/api/agents/me/inbox-lite" },
+      { method: "GET", path: "/api/agents/me/inbox/mine" },
+      { method: "GET", path: "/api/agents/agent-1" },
+      { method: "GET", path: "/api/agents/agent-1/skills" },
+      { method: "POST", path: "/api/agents/agent-1/skills/sync" },
+      { method: "PATCH", path: "/api/agents/agent-1/instructions-path" },
+      { method: "GET", path: "/api/companies/co-1" },
+      { method: "GET", path: "/api/companies/co-1/dashboard" },
+      { method: "GET", path: "/api/companies/co-1/agents" },
+      { method: "GET", path: "/api/companies/co-1/issues" },
+      { method: "GET", path: "/api/companies/co-1/projects" },
+      { method: "GET", path: "/api/companies/co-1/goals" },
+      { method: "GET", path: "/api/companies/co-1/org" },
+      { method: "GET", path: "/api/companies/co-1/approvals" },
+      { method: "GET", path: "/api/companies/co-1/routines" },
+      { method: "GET", path: "/api/companies/co-1/skills" },
+      { method: "GET", path: "/api/projects/proj-1" },
+      { method: "GET", path: "/api/goals/goal-1" },
+      { method: "GET", path: "/api/issues/issue-1" },
+      { method: "GET", path: "/api/issues/issue-1/heartbeat-context" },
+      { method: "GET", path: "/api/issues/issue-1/comments" },
+      { method: "GET", path: "/api/issues/issue-1/comments/c-1" },
+      { method: "POST", path: "/api/issues/issue-1/comments" },
+      { method: "GET", path: "/api/issues/issue-1/documents" },
+      { method: "GET", path: "/api/issues/issue-1/documents/plan" },
+      { method: "GET", path: "/api/issues/issue-1/documents/plan/revisions" },
+      { method: "PUT", path: "/api/issues/issue-1/documents/plan" },
+      { method: "POST", path: "/api/issues/issue-1/checkout" },
+      { method: "POST", path: "/api/issues/issue-1/release" },
+      { method: "PATCH", path: "/api/issues/issue-1" },
+      { method: "GET", path: "/api/issues/issue-1/approvals" },
+      { method: "GET", path: "/api/issues/issue-1/interactions" },
+      { method: "GET", path: "/api/issues/issue-1/interactions/inter-1" },
+      { method: "POST", path: "/api/issues/issue-1/interactions" },
+      { method: "POST", path: "/api/issues/issue-1/interactions/inter-1/accept" },
+      { method: "POST", path: "/api/issues/issue-1/interactions/inter-1/reject" },
+      { method: "POST", path: "/api/issues/issue-1/interactions/inter-1/respond" },
+      { method: "POST", path: "/api/companies/co-1/issues" },
+      { method: "GET", path: "/api/approvals/ap-1" },
+      { method: "GET", path: "/api/approvals/ap-1/issues" },
+      { method: "GET", path: "/api/approvals/ap-1/comments" },
+      { method: "POST", path: "/api/approvals/ap-1/comments" },
+      { method: "POST", path: "/api/companies/co-1/approvals" },
+      { method: "GET", path: "/api/execution-workspaces/ws-1" },
+      { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/start" },
+      { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/stop" },
+      { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/restart" },
+      { method: "GET", path: "/api/routines/r-1" },
+      { method: "GET", path: "/api/routines/r-1/runs" },
+      { method: "POST", path: "/api/companies/co-1/routines" },
+      { method: "PATCH", path: "/api/routines/r-1" },
+      { method: "POST", path: "/api/routines/r-1/run" },
+      { method: "POST", path: "/api/routines/r-1/triggers" },
+      { method: "PATCH", path: "/api/routine-triggers/t-1" },
+      { method: "DELETE", path: "/api/routine-triggers/t-1" },
+    ];
+    for (const request of allowed) {
+      expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request)).toBeNull();
+    }
+
+    const denied: Array<{ method: string; path: string }> = [
+      { method: "DELETE", path: "/api/secrets" },
+      // Pin the runtime-services regex to start/stop/restart only — anything
+      // else (delete, reset, wipe, etc.) must stay denied even if the API
+      // grows new actions later.
+      { method: "POST", path: "/api/execution-workspaces/ws-1/runtime-services/delete" },
+      { method: "POST", path: "/api/companies/co-1/agents" },
+      { method: "POST", path: "/api/agents/agent-1/pause" },
+      { method: "POST", path: "/api/agents/agent-1/terminate" },
+      { method: "POST", path: "/api/agents/agent-1/keys" },
+      { method: "POST", path: "/api/companies/co-1/exports" },
+      { method: "POST", path: "/api/companies/co-1/imports/apply" },
+      { method: "POST", path: "/api/companies/co-1/archive" },
+      { method: "DELETE", path: "/api/issues/issue-1/documents/plan" },
+      { method: "DELETE", path: "/api/issues/issue-1/approvals/ap-1" },
+      { method: "POST", path: "/api/approvals/ap-1/approve" },
+      { method: "POST", path: "/api/approvals/ap-1/reject" },
+      { method: "POST", path: "/api/companies/co-1/logo" },
+      { method: "GET", path: "/api/companies/co-1/secrets" },
+      { method: "PATCH", path: "/api/secrets/secret-1" },
+    ];
+    for (const request of denied) {
+      expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request)).toBe(
+        `Route not allowed: ${request.method} ${request.path}`,
+      );
+    }
+  });
+
+  it("marks command-managed bridge operations with the bridge execution channel", async () => {
+    const runner = {
+      execute: vi.fn(async () => ({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: "",
+        stderr: "",
+        pid: null,
+        startedAt: new Date().toISOString(),
+      })),
+    };
+
+    const client = createCommandManagedSandboxCallbackBridgeQueueClient({
+      runner,
+      remoteCwd: "/workspace",
+      timeoutMs: 30_000,
+    });
+
+    await client.makeDir("/workspace/.paperclip-runtime/codex/paperclip-bridge/queue");
+
+    expect(runner.execute).toHaveBeenCalledWith(expect.objectContaining({
+      env: {
+        PAPERCLIP_SANDBOX_EXEC_CHANNEL: "bridge",
+      },
+    }));
+  });
 });

packages/adapter-utils/src/sandbox-callback-bridge.ts

@@ -1,9 +1,10 @@
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import type { CommandManagedRuntimeRunner } from "./command-managed-runtime.js";
+import { preferredShellForSandbox, shellCommandArgs } from "./sandbox-shell.js";
 import type { RunProcessResult } from "./server-utils.js";
 
 const DEFAULT_BRIDGE_TOKEN_BYTES = 24;
@@ -14,6 +15,8 @@ const DEFAULT_BRIDGE_MAX_QUEUE_DEPTH = 64;
 const DEFAULT_BRIDGE_MAX_BODY_BYTES = 256 * 1024;
 const REMOTE_WRITE_BASE64_CHUNK_SIZE = 32 * 1024;
 const SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT = "paperclip-bridge-server.mjs";
+const SANDBOX_EXEC_CHANNEL_ENV = "PAPERCLIP_SANDBOX_EXEC_CHANNEL";
+const SANDBOX_EXEC_CHANNEL_BRIDGE = "bridge";
 
 export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES = DEFAULT_BRIDGE_MAX_BODY_BYTES;
 
@@ -22,15 +25,76 @@ export interface SandboxCallbackBridgeRouteRule {
   path: RegExp;
 }
 
+// Routes the in-sandbox heartbeat skill is documented to call. The server
+// still enforces actor-level permissions on top of this allowlist; the list
+// exists to bound the surface area a compromised CLI could reach via the
+// reverse bridge. Keep this in sync with the Paperclip skill in
+// `skills/paperclip/SKILL.md` and `references/api-reference.md`.
 export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCallbackBridgeRouteRule[] = [
+  // Identity, inbox, agent self-management
   { method: "GET", path: /^\/api\/agents\/me$/ },
+  { method: "GET", path: /^\/api\/agents\/me\/inbox-lite$/ },
+  { method: "GET", path: /^\/api\/agents\/me\/inbox\/mine$/ },
+  { method: "GET", path: /^\/api\/agents\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/agents\/[^/]+\/skills$/ },
+  { method: "POST", path: /^\/api\/agents\/[^/]+\/skills\/sync$/ },
+  { method: "PATCH", path: /^\/api\/agents\/[^/]+\/instructions-path$/ },
+
+  // Company-level reads used to discover work and context
+  { method: "GET", path: /^\/api\/companies\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/dashboard$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/agents$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/issues$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/projects$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/goals$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/org$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/approvals$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/routines$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/skills$/ },
+  { method: "GET", path: /^\/api\/projects\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/goals\/[^/]+$/ },
+
+  // Issue lifecycle: read context, checkout, update, comment, document, release
+  { method: "GET", path: /^\/api\/issues\/[^/]+$/ },
   { method: "GET", path: /^\/api\/issues\/[^/]+\/heartbeat-context$/ },
   { method: "GET", path: /^\/api\/issues\/[^/]+\/comments(?:\/[^/]+)?$/ },
-  { method: "GET", path: /^\/api\/issues\/[^/]+\/documents(?:\/[^/]+)?$/ },
-  { method: "POST", path: /^\/api\/issues\/[^/]+\/checkout$/ },
   { method: "POST", path: /^\/api\/issues\/[^/]+\/comments$/ },
-  { method: "POST", path: /^\/api\/issues\/[^/]+\/interactions(?:\/[^/]+)?$/ },
+  { method: "GET", path: /^\/api\/issues\/[^/]+\/documents(?:\/[^/]+)?$/ },
+  { method: "GET", path: /^\/api\/issues\/[^/]+\/documents\/[^/]+\/revisions$/ },
+  { method: "PUT", path: /^\/api\/issues\/[^/]+\/documents\/[^/]+$/ },
+  { method: "POST", path: /^\/api\/issues\/[^/]+\/checkout$/ },
+  { method: "POST", path: /^\/api\/issues\/[^/]+\/release$/ },
   { method: "PATCH", path: /^\/api\/issues\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/issues\/[^/]+\/approvals$/ },
+
+  // Issue-thread interactions (suggest tasks, ask questions, request confirmation)
+  { method: "GET", path: /^\/api\/issues\/[^/]+\/interactions(?:\/[^/]+)?$/ },
+  { method: "POST", path: /^\/api\/issues\/[^/]+\/interactions$/ },
+  { method: "POST", path: /^\/api\/issues\/[^/]+\/interactions\/[^/]+\/(?:accept|reject|respond)$/ },
+
+  // Subtasks / delegation
+  { method: "POST", path: /^\/api\/companies\/[^/]+\/issues$/ },
+
+  // Approvals (request, read, comment)
+  { method: "GET", path: /^\/api\/approvals\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/approvals\/[^/]+\/issues$/ },
+  { method: "GET", path: /^\/api\/approvals\/[^/]+\/comments$/ },
+  { method: "POST", path: /^\/api\/approvals\/[^/]+\/comments$/ },
+  { method: "POST", path: /^\/api\/companies\/[^/]+\/approvals$/ },
+
+  // Execution workspaces and runtime services (start/stop/restart dev servers)
+  { method: "GET", path: /^\/api\/execution-workspaces\/[^/]+$/ },
+  { method: "POST", path: /^\/api\/execution-workspaces\/[^/]+\/runtime-services\/(?:start|stop|restart)$/ },
+
+  // Routines (agents manage their own routines and triggers)
+  { method: "GET", path: /^\/api\/routines\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/routines\/[^/]+\/runs$/ },
+  { method: "POST", path: /^\/api\/companies\/[^/]+\/routines$/ },
+  { method: "PATCH", path: /^\/api\/routines\/[^/]+$/ },
+  { method: "POST", path: /^\/api\/routines\/[^/]+\/run$/ },
+  { method: "POST", path: /^\/api\/routines\/[^/]+\/triggers$/ },
+  { method: "PATCH", path: /^\/api\/routine-triggers\/[^/]+$/ },
+  { method: "DELETE", path: /^\/api\/routine-triggers\/[^/]+$/ },
 ] as const;
 
 export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_HEADER_ALLOWLIST = [
@@ -83,6 +147,13 @@ export interface SandboxCallbackBridgeQueueClient {
   listJsonFiles(remotePath: string): Promise<string[]>;
   readTextFile(remotePath: string): Promise<string>;
   writeTextFile(remotePath: string, body: string): Promise<void>;
+  writeResponseFile?(
+    responsePath: string,
+    body: string,
+    options?: {
+      requestPath?: string | null;
+    },
+  ): Promise<{ wrote: boolean }>;
   rename(fromPath: string, toPath: string): Promise<void>;
   remove(remotePath: string): Promise<void>;
 }
@@ -133,12 +204,18 @@ async function runShell(
   cwd: string,
   script: string,
   timeoutMs: number,
+  shellCommand: "bash" | "sh" = "sh",
+  stdin?: string,
 ): Promise<RunProcessResult> {
   return await runner.execute({
-    command: "sh",
-    args: ["-lc", script],
+    command: shellCommand,
+    args: shellCommandArgs(script),
     cwd,
+    env: {
+      [SANDBOX_EXEC_CHANNEL_ENV]: SANDBOX_EXEC_CHANNEL_BRIDGE,
+    },
     timeoutMs,
+    stdin,
   });
 }
 
@@ -155,6 +232,43 @@ function base64Chunks(body: string): string[] {
   return out;
 }
 
+async function pathExists(filePath: string): Promise<boolean> {
+  return await fs.stat(filePath).then(() => true).catch(() => false);
+}
+
+function buildRemotePidLockAcquireScript(lockDirExpr: string, timeoutMessage: string): string[] {
+  return [
+    "attempts=0",
+    `while ! mkdir ${lockDirExpr} 2>/dev/null; do`,
+    "  holder_pid=\"\"",
+    `  if [ -s ${lockDirExpr}/pid ]; then`,
+    `    holder_pid="$(cat ${lockDirExpr}/pid 2>/dev/null || true)"`,
+    "  fi",
+    "  if [ -n \"$holder_pid\" ] && ! kill -0 \"$holder_pid\" 2>/dev/null; then",
+    `    rm -rf ${lockDirExpr}`,
+    "    continue",
+    "  fi",
+    "  attempts=$((attempts + 1))",
+    "  if [ \"$attempts\" -ge 600 ]; then",
+    `    echo ${shellQuote(timeoutMessage)} >&2`,
+    "    exit 1",
+    "  fi",
+    "  sleep 0.05",
+    "done",
+    `printf '%s\\n' "$$" > ${lockDirExpr}/pid`,
+  ];
+}
+
+function buildRemotePidLockCleanupScript(lockDirExpr: string, cleanupLines: string[]): string[] {
+  return [
+    "cleanup() {",
+    ...cleanupLines.map((line) => `  ${line}`),
+    `  rm -rf ${lockDirExpr}`,
+    "}",
+    "trap cleanup EXIT INT TERM",
+  ];
+}
+
 export function createSandboxCallbackBridgeToken(bytes = DEFAULT_BRIDGE_TOKEN_BYTES): string {
   return randomBytes(bytes).toString("base64url");
 }
@@ -252,6 +366,80 @@ export function createFileSystemSandboxCallbackBridgeQueueClient(): SandboxCallb
       await fs.mkdir(path.posix.dirname(remotePath), { recursive: true });
       await fs.writeFile(remotePath, body, "utf8");
     },
+    writeResponseFile: async (responsePath, body, options = {}) => {
+      const responseDir = path.posix.dirname(responsePath);
+      const tempPath = `${responsePath}.tmp`;
+      const lockDir = `${responsePath}.paperclip-write.lock`;
+      const lockPidFile = `${lockDir}/pid`;
+      if (options.requestPath) {
+        const requestExists = await pathExists(options.requestPath);
+        if (!requestExists) {
+          return { wrote: false };
+        }
+      }
+      await fs.mkdir(responseDir, { recursive: true });
+      // PID-liveness mkdir-mutex: mirrors the shell-based bridge mutex so a
+      // crashed holder (SIGKILL / OOM) doesn't deadlock subsequent writers
+      // for the full timeout window.
+      let attempts = 0;
+      while (true) {
+        try {
+          await fs.mkdir(lockDir);
+          await fs.writeFile(lockPidFile, `${process.pid}\n`, "utf8");
+          break;
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException)?.code;
+          if (code !== "EEXIST") {
+            throw error;
+          }
+          let holderPid: number | null = null;
+          try {
+            const raw = await fs.readFile(lockPidFile, "utf8");
+            const parsed = Number.parseInt(raw.trim(), 10);
+            if (Number.isFinite(parsed) && parsed > 0) holderPid = parsed;
+          } catch {
+            // pid file missing or unreadable — treat as stale lock
+          }
+          let holderAlive = false;
+          if (holderPid !== null) {
+            try {
+              process.kill(holderPid, 0);
+              holderAlive = true;
+            } catch {
+              holderAlive = false;
+            }
+          }
+          if (!holderAlive) {
+            await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+            continue;
+          }
+          attempts += 1;
+          if (attempts >= 600) {
+            throw new Error("Timed out acquiring sandbox callback bridge response lock.");
+          }
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+      }
+
+      try {
+        if (options.requestPath) {
+          const requestExists = await pathExists(options.requestPath);
+          if (!requestExists) {
+            return { wrote: false };
+          }
+        }
+        const responseExists = await pathExists(responsePath);
+        if (responseExists) {
+          return { wrote: false };
+        }
+        await fs.writeFile(tempPath, body, "utf8");
+        await fs.rename(tempPath, responsePath);
+        return { wrote: true };
+      } finally {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+      }
+    },
     rename: async (fromPath, toPath) => {
       await fs.mkdir(path.posix.dirname(toPath), { recursive: true });
       await fs.rename(fromPath, toPath);
@@ -266,10 +454,12 @@ export function createCommandManagedSandboxCallbackBridgeQueueClient(input: {
   runner: CommandManagedRuntimeRunner;
   remoteCwd: string;
   timeoutMs?: number | null;
+  shellCommand?: "bash" | "sh" | null;
 }): SandboxCallbackBridgeQueueClient {
   const timeoutMs = normalizeTimeoutMs(input.timeoutMs, DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS);
+  const shellCommand = preferredShellForSandbox(input.shellCommand);
   const runChecked = async (action: string, script: string) =>
-    requireSuccessfulResult(action, await runShell(input.runner, input.remoteCwd, script, timeoutMs));
+    requireSuccessfulResult(action, await runShell(input.runner, input.remoteCwd, script, timeoutMs, shellCommand));
 
   return {
     makeDir: async (remotePath) => {
@@ -288,6 +478,7 @@ export function createCommandManagedSandboxCallbackBridgeQueueClient(input: {
           "fi",
         ].join("\n"),
         timeoutMs,
+        shellCommand,
       );
       requireSuccessfulResult(`list ${remotePath}`, result);
       return result.stdout
@@ -319,6 +510,53 @@ export function createCommandManagedSandboxCallbackBridgeQueueClient(input: {
         `base64 -d < ${shellQuote(tempPath)} > ${shellQuote(remotePath)} && rm -f ${shellQuote(tempPath)}`,
       );
     },
+    writeResponseFile: async (responsePath, body, options = {}) => {
+      const responseDir = path.posix.dirname(responsePath);
+      const tempPath = `${responsePath}.tmp`;
+      const lockDir = `${responsePath}.paperclip-write.lock`;
+      const requestPath = options.requestPath?.trim() || "";
+      const result = await runShell(
+        input.runner,
+        input.remoteCwd,
+        [
+          "set -eu",
+          `response_dir=${shellQuote(responseDir)}`,
+          `response_path=${shellQuote(responsePath)}`,
+          `temp_path=${shellQuote(tempPath)}`,
+          `lock_dir=${shellQuote(lockDir)}`,
+          `request_path=${shellQuote(requestPath)}`,
+          "mkdir -p \"$response_dir\"",
+          ...buildRemotePidLockAcquireScript("\"$lock_dir\"", "Timed out acquiring sandbox callback bridge response lock."),
+          ...buildRemotePidLockCleanupScript("\"$lock_dir\"", [
+            "rm -f \"$temp_path\"",
+          ]),
+          "if [ -n \"$request_path\" ] && [ ! -f \"$request_path\" ]; then",
+          "  printf '{\"wrote\":false}\\n'",
+          "  exit 0",
+          "fi",
+          "if [ -f \"$response_path\" ]; then",
+          "  printf '{\"wrote\":false}\\n'",
+          "  exit 0",
+          "fi",
+          "cat > \"$temp_path\"",
+          "mv \"$temp_path\" \"$response_path\"",
+          "printf '{\"wrote\":true}\\n'",
+        ].join("\n"),
+        timeoutMs,
+        shellCommand,
+        body,
+      );
+      requireSuccessfulResult(`write bridge response ${responsePath}`, result);
+      try {
+        return {
+          wrote: JSON.parse(result.stdout.trim())?.wrote === true,
+        };
+      } catch (error) {
+        throw new Error(
+          `Sandbox callback bridge response write wrote invalid result JSON: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    },
     rename: async (fromPath, toPath) => {
       await runChecked(
         `rename ${fromPath}`,
@@ -333,11 +571,18 @@ export function createCommandManagedSandboxCallbackBridgeQueueClient(input: {
 
 async function writeBridgeResponse(
   client: SandboxCallbackBridgeQueueClient,
+  requestPath: string,
   responsePath: string,
   response: SandboxCallbackBridgeResponse,
+  options: { requireRequestPath?: boolean } = {},
 ) {
+  const body = `${JSON.stringify(response)}\n`;
+  if (client.writeResponseFile) {
+    await client.writeResponseFile(responsePath, body, options.requireRequestPath === false ? {} : { requestPath });
+    return;
+  }
   const tempPath = `${responsePath}.tmp`;
-  await client.writeTextFile(tempPath, `${JSON.stringify(response)}\n`);
+  await client.writeTextFile(tempPath, body);
   await client.rename(tempPath, responsePath);
 }
 
@@ -371,6 +616,8 @@ export async function startSandboxCallbackBridgeWorker(input: {
   });
   const authorizeRequest = input.authorizeRequest ??
     ((request: SandboxCallbackBridgeRequest) => authorizeSandboxCallbackBridgeRequestWithRoutes(request));
+  const buildWorkerFailureMessage = (error: unknown) =>
+    `Sandbox callback bridge worker failed: ${error instanceof Error ? error.message : String(error)}`;
 
   const processRequestFile = async (fileName: string) => {
     const requestPath = path.posix.join(directories.requestsDir, fileName);
@@ -381,7 +628,7 @@ export async function startSandboxCallbackBridgeWorker(input: {
       request = JSON.parse(raw) as SandboxCallbackBridgeRequest;
     } catch {
       const requestId = fileName.replace(/\.json$/i, "") || randomUUID();
-      await writeBridgeResponse(input.client, responsePath, {
+      await writeBridgeResponse(input.client, requestPath, responsePath, {
         id: requestId,
         status: 400,
         headers: { "content-type": "application/json" },
@@ -394,7 +641,7 @@ export async function startSandboxCallbackBridgeWorker(input: {
 
     const denialReason = await authorizeRequest(request);
     if (denialReason) {
-      await writeBridgeResponse(input.client, responsePath, {
+      await writeBridgeResponse(input.client, requestPath, responsePath, {
         id: request.id,
         status: 403,
         headers: { "content-type": "application/json" },
@@ -411,7 +658,7 @@ export async function startSandboxCallbackBridgeWorker(input: {
       if (Buffer.byteLength(responseBody, "utf8") > maxBodyBytes) {
         throw new Error(`Bridge response body exceeded the configured size limit of ${maxBodyBytes} bytes.`);
       }
-      await writeBridgeResponse(input.client, responsePath, {
+      await writeBridgeResponse(input.client, requestPath, responsePath, {
         id: request.id,
         status: result.status,
         headers: result.headers ?? {},
@@ -422,7 +669,7 @@ export async function startSandboxCallbackBridgeWorker(input: {
       console.warn(
         `[paperclip] sandbox callback bridge handler failed for ${request.id}: ${error instanceof Error ? error.message : String(error)}`,
       );
-      await writeBridgeResponse(input.client, responsePath, {
+      await writeBridgeResponse(input.client, requestPath, responsePath, {
         id: request.id,
         status: 502,
         headers: { "content-type": "application/json" },
@@ -445,12 +692,15 @@ export async function startSandboxCallbackBridgeWorker(input: {
       try {
         const raw = await input.client.readTextFile(requestPath);
         const parsed = JSON.parse(raw) as Partial<SandboxCallbackBridgeRequest>;
-        await writeBridgeResponse(input.client, responsePath, {
+        await input.client.remove(requestPath).catch(() => undefined);
+        await writeBridgeResponse(input.client, requestPath, responsePath, {
           id: typeof parsed.id === "string" && parsed.id.length > 0 ? parsed.id : requestId,
           status: 503,
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ error: message }),
           completedAt: new Date().toISOString(),
+        }, {
+          requireRequestPath: false,
         });
       } catch (error) {
         console.warn(
@@ -486,6 +736,16 @@ export async function startSandboxCallbackBridgeWorker(input: {
           break;
         }
       }
+    } catch (error) {
+      const message = buildWorkerFailureMessage(error);
+      console.warn(`[paperclip] ${message}`);
+      try {
+        await failPendingRequests(message);
+      } catch (failPendingError) {
+        console.warn(
+          `[paperclip] sandbox callback bridge failed to abort queued requests after worker failure: ${failPendingError instanceof Error ? failPendingError.message : String(failPendingError)}`,
+        );
+      }
     } finally {
       settled = true;
       if (settleResolve) {
@@ -512,6 +772,99 @@ export async function startSandboxCallbackBridgeWorker(input: {
   };
 }
 
+export async function syncSandboxCallbackBridgeEntrypoint(input: {
+  runner: CommandManagedRuntimeRunner;
+  remoteCwd: string;
+  assetRemoteDir: string;
+  bridgeAsset: SandboxCallbackBridgeAsset;
+  timeoutMs?: number | null;
+  shellCommand?: "bash" | "sh" | null;
+}): Promise<{ remoteEntrypoint: string; sha256: string; uploaded: boolean }> {
+  const timeoutMs = normalizeTimeoutMs(input.timeoutMs, DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS);
+  const shellCommand = preferredShellForSandbox(input.shellCommand);
+  const remoteEntrypoint = path.posix.join(input.assetRemoteDir, SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT);
+  const remoteEntrypointPartial = `${remoteEntrypoint}.partial`;
+  const remoteUploadPath = `${remoteEntrypoint}.paperclip-upload.b64`;
+  const remoteLockDir = path.posix.join(input.assetRemoteDir, ".paperclip-bridge-upload.lock");
+  const entrypointSource = await fs.readFile(input.bridgeAsset.entrypoint, "utf8");
+  const entrypointBase64 = toBuffer(Buffer.from(entrypointSource, "utf8")).toString("base64");
+  const sha256 = createHash("sha256").update(entrypointSource, "utf8").digest("hex");
+
+  const syncResult = await runShell(
+    input.runner,
+    input.remoteCwd,
+    [
+      "set -eu",
+      `remote_dir=${shellQuote(input.assetRemoteDir)}`,
+      `remote_path=${shellQuote(remoteEntrypoint)}`,
+      `remote_partial=${shellQuote(remoteEntrypointPartial)}`,
+      `remote_upload=${shellQuote(remoteUploadPath)}`,
+      `lock_dir=${shellQuote(remoteLockDir)}`,
+      `expected_sha=${shellQuote(sha256)}`,
+      "hash_file() {",
+      "  if command -v sha256sum >/dev/null 2>&1; then",
+      "    sha256sum \"$1\" | awk '{print $1}'",
+      "    return 0",
+      "  fi",
+      "  if command -v shasum >/dev/null 2>&1; then",
+      "    shasum -a 256 \"$1\" | awk '{print $1}'",
+      "    return 0",
+      "  fi",
+      "  return 127",
+      "}",
+      "mkdir -p \"$remote_dir\"",
+      ...buildRemotePidLockAcquireScript("\"$lock_dir\"", "Timed out acquiring sandbox callback bridge upload lock."),
+      ...buildRemotePidLockCleanupScript("\"$lock_dir\"", [
+        "rm -f \"$remote_upload\" \"$remote_partial\"",
+      ]),
+      "current_sha=\"\"",
+      "if [ -f \"$remote_path\" ]; then",
+      "  current_sha=\"$(hash_file \"$remote_path\" 2>/dev/null)\" || current_sha=\"\"",
+      "fi",
+      "if [ -n \"$current_sha\" ] && [ \"$current_sha\" = \"$expected_sha\" ]; then",
+      "  printf '{\"uploaded\":false}\\n'",
+      "  exit 0",
+      "fi",
+      "rm -f \"$remote_upload\" \"$remote_partial\"",
+      "cat > \"$remote_upload\"",
+      "base64 -d < \"$remote_upload\" > \"$remote_partial\"",
+      // Verify upload integrity. If neither sha256sum nor shasum is on PATH
+      // (minimal Alpine/scratch images), surface the missing-tool error
+      // instead of a misleading "sha mismatch" — the verify step is then
+      // best-effort and we trust base64-decode + atomic rename below.
+      "if partial_sha=\"$(hash_file \"$remote_partial\" 2>/dev/null)\"; then",
+      "  if [ \"$partial_sha\" != \"$expected_sha\" ]; then",
+      "    echo \"Sandbox callback bridge entrypoint upload sha mismatch.\" >&2",
+      "    exit 1",
+      "  fi",
+      "else",
+      "  echo \"Sandbox callback bridge entrypoint sha verify skipped: no sha256sum/shasum on remote.\" >&2",
+      "fi",
+      "mv \"$remote_partial\" \"$remote_path\"",
+      "printf '{\"uploaded\":true}\\n'",
+    ].join("\n"),
+    timeoutMs,
+    shellCommand,
+    entrypointBase64,
+  );
+  requireSuccessfulResult("sync sandbox callback bridge entrypoint", syncResult);
+
+  let uploaded = false;
+  try {
+    uploaded = JSON.parse(syncResult.stdout.trim())?.uploaded === true;
+  } catch (error) {
+    throw new Error(
+      `Sandbox callback bridge sync wrote invalid result JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return {
+    remoteEntrypoint,
+    sha256,
+    uploaded,
+  };
+}
+
 export async function startSandboxCallbackBridgeServer(input: {
   runner: CommandManagedRuntimeRunner;
   remoteCwd: string;
@@ -525,21 +878,24 @@ export async function startSandboxCallbackBridgeServer(input: {
   responseTimeoutMs?: number | null;
   timeoutMs?: number | null;
   nodeCommand?: string;
+  shellCommand?: "bash" | "sh" | null;
   maxQueueDepth?: number | null;
   maxBodyBytes?: number | null;
 }): Promise<StartedSandboxCallbackBridgeServer> {
   const timeoutMs = normalizeTimeoutMs(input.timeoutMs, DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS);
+  const shellCommand = preferredShellForSandbox(input.shellCommand);
   const directories = sandboxCallbackBridgeDirectories(input.queueDir);
-  const remoteEntrypoint = path.posix.join(input.assetRemoteDir, SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT);
+  let remoteEntrypoint = path.posix.join(input.assetRemoteDir, SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT);
   if (input.bridgeAsset) {
-    const assetClient = createCommandManagedSandboxCallbackBridgeQueueClient({
+    const assetSync = await syncSandboxCallbackBridgeEntrypoint({
       runner: input.runner,
       remoteCwd: input.remoteCwd,
+      assetRemoteDir: input.assetRemoteDir,
+      bridgeAsset: input.bridgeAsset,
       timeoutMs,
+      shellCommand,
     });
-    await assetClient.makeDir(input.assetRemoteDir);
-    const entrypointSource = await fs.readFile(input.bridgeAsset.entrypoint, "utf8");
-    await assetClient.writeTextFile(remoteEntrypoint, entrypointSource);
+    remoteEntrypoint = assetSync.remoteEntrypoint;
   }
   const env = buildSandboxCallbackBridgeEnv({
     queueDir: input.queueDir,
@@ -553,9 +909,8 @@ export async function startSandboxCallbackBridgeServer(input: {
   });
   const nodeCommand = input.nodeCommand?.trim() || "node";
   const startResult = await input.runner.execute({
-    command: "sh",
-    args: [
-      "-lc",
+    command: shellCommand,
+    args: shellCommandArgs(
       [
         `mkdir -p ${shellQuote(directories.requestsDir)} ${shellQuote(directories.responsesDir)} ${shellQuote(directories.logsDir)}`,
         `rm -f ${shellQuote(directories.readyFile)} ${shellQuote(directories.pidFile)}`,
@@ -566,8 +921,11 @@ export async function startSandboxCallbackBridgeServer(input: {
         `printf '%s\\n' \"$pid\" > ${shellQuote(directories.pidFile)}`,
         "printf '{\"pid\":%s}\\n' \"$pid\"",
       ].join("\n"),
-    ],
+    ),
     cwd: input.remoteCwd,
+    env: {
+      [SANDBOX_EXEC_CHANNEL_ENV]: SANDBOX_EXEC_CHANNEL_BRIDGE,
+    },
     timeoutMs,
   });
   requireSuccessfulResult("start sandbox callback bridge", startResult);
@@ -594,6 +952,7 @@ export async function startSandboxCallbackBridgeServer(input: {
       "exit 1",
     ].join("\n"),
     timeoutMs,
+    shellCommand,
   );
   requireSuccessfulResult("wait for sandbox callback bridge readiness", readyResult);
 
@@ -626,9 +985,8 @@ export async function startSandboxCallbackBridgeServer(input: {
     directories,
     stop: async () => {
       const stopResult = await input.runner.execute({
-        command: "sh",
-        args: [
-          "-lc",
+        command: shellCommand,
+        args: shellCommandArgs(
           [
             `if [ -s ${shellQuote(directories.pidFile)} ]; then`,
             `  pid="$(cat ${shellQuote(directories.pidFile)})"`,
@@ -641,8 +999,11 @@ export async function startSandboxCallbackBridgeServer(input: {
             "fi",
             `rm -f ${shellQuote(directories.pidFile)} ${shellQuote(directories.readyFile)}`,
           ].join("\n"),
-        ],
+        ),
         cwd: input.remoteCwd,
+        env: {
+          [SANDBOX_EXEC_CHANNEL_ENV]: SANDBOX_EXEC_CHANNEL_BRIDGE,
+        },
         timeoutMs,
       });
       if (stopResult.timedOut) {

packages/adapter-utils/src/sandbox-install-command.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import { buildSandboxNpmInstallCommand } from "./sandbox-install-command.js";
+
+describe("buildSandboxNpmInstallCommand", () => {
+  it("installs globally as root, via sudo when available, and under ~/.local otherwise", () => {
+    expect(buildSandboxNpmInstallCommand("@google/gemini-cli")).toBe(
+      'if [ "$(id -u)" -eq 0 ]; then npm install -g \'@google/gemini-cli\'; elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then sudo -E npm install -g \'@google/gemini-cli\'; else mkdir -p "$HOME/.local" && npm install -g --prefix "$HOME/.local" \'@google/gemini-cli\'; fi',
+    );
+  });
+
+  it("shell-quotes package names", () => {
+    expect(buildSandboxNpmInstallCommand("odd'pkg")).toContain("'odd'\"'\"'pkg'");
+  });
+});

packages/adapter-utils/src/sandbox-install-command.ts

@@ -0,0 +1,16 @@
+function shellSingleQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\"'\"'`)}'`;
+}
+
+export function buildSandboxNpmInstallCommand(packageName: string): string {
+  const quotedPackageName = shellSingleQuote(packageName);
+  return [
+    'if [ "$(id -u)" -eq 0 ]; then',
+    `npm install -g ${quotedPackageName};`,
+    'elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then',
+    `sudo -E npm install -g ${quotedPackageName};`,
+    "else",
+    `mkdir -p "$HOME/.local" && npm install -g --prefix "$HOME/.local" ${quotedPackageName};`,
+    "fi",
+  ].join(" ");
+}

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

@@ -84,7 +84,7 @@ describe("sandbox managed runtime", () => {
         await rm(remotePath, { recursive: true, force: true });
       },
       run: async (command) => {
-        await execFile("sh", ["-lc", command], {
+        await execFile("sh", ["-c", command], {
           maxBuffer: 32 * 1024 * 1024,
         });
       },
@@ -126,7 +126,7 @@ describe("sandbox managed runtime", () => {
 
     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, "local-stale.txt"), "utf8")).resolves.toBe("remove\n");
     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

@@ -3,6 +3,7 @@ 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";
+import { captureDirectorySnapshot, mergeDirectoryWithBaseline } from "./workspace-restore-merge.js";
 
 const execFile = promisify(execFileCallback);
 
@@ -13,7 +14,6 @@ export interface SandboxRemoteExecutionSpec {
   remoteCwd: string;
   timeoutMs: number;
   apiKey: string | null;
-  paperclipApiUrl?: string | null;
 }
 
 export interface SandboxManagedRuntimeAsset {
@@ -85,7 +85,6 @@ export function parseSandboxRemoteExecutionSpec(value: unknown): SandboxRemoteEx
     remoteCwd,
     timeoutMs,
     apiKey: asString(parsed.apiKey).trim() || null,
-    paperclipApiUrl: asString(parsed.paperclipApiUrl).trim() || null,
   };
 }
 
@@ -96,7 +95,6 @@ export function buildSandboxExecutionSessionIdentity(spec: SandboxRemoteExecutio
     provider: spec.provider,
     sandboxId: spec.sandboxId,
     remoteCwd: spec.remoteCwd,
-    ...(spec.paperclipApiUrl ? { paperclipApiUrl: spec.paperclipApiUrl } : {}),
   } as const;
 }
 
@@ -108,8 +106,7 @@ export function sandboxExecutionSessionMatches(saved: unknown, current: SandboxR
     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)
+    asString(parsedSaved.remoteCwd) === currentIdentity.remoteCwd
   );
 }
 
@@ -252,6 +249,9 @@ export async function prepareSandboxManagedRuntime(input: {
 }): Promise<PreparedSandboxManagedRuntime> {
   const workspaceRemoteDir = input.workspaceRemoteDir ?? input.spec.remoteCwd;
   const runtimeRootDir = path.posix.join(workspaceRemoteDir, ".paperclip-runtime", input.adapterKey);
+  const baselineSnapshot = await captureDirectorySnapshot(input.workspaceLocalDir, {
+    exclude: [...new Set([".paperclip-runtime", ...(input.preserveAbsentOnRestore ?? []), ...(input.workspaceExclude ?? [])])],
+  });
 
   await withTempDir("paperclip-sandbox-sync-", async (tempDir) => {
     const workspaceTarPath = path.join(tempDir, "workspace.tar");
@@ -267,7 +267,7 @@ export async function prepareSandboxManagedRuntime(input: {
     const preservedNames = new Set([".paperclip-runtime", ...(input.preserveAbsentOnRestore ?? [])]);
     const findPreserveArgs = [...preservedNames].map((entry) => `! -name ${shellQuote(entry)}`).join(" ");
     await input.client.run(
-      `sh -lc ${shellQuote(
+      `sh -c ${shellQuote(
         `mkdir -p ${shellQuote(workspaceRemoteDir)} && ` +
           `find ${shellQuote(workspaceRemoteDir)} -mindepth 1 -maxdepth 1 ${findPreserveArgs} -exec rm -rf -- {} + && ` +
           `tar -xf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} && ` +
@@ -289,7 +289,7 @@ export async function prepareSandboxManagedRuntime(input: {
       const remoteAssetTar = path.posix.join(runtimeRootDir, `${asset.key}-upload.tar`);
       await input.client.writeFile(remoteAssetTar, toArrayBuffer(assetTarBytes));
       await input.client.run(
-        `sh -lc ${shellQuote(
+        `sh -c ${shellQuote(
           `rm -rf ${shellQuote(remoteAssetDir)} && ` +
             `mkdir -p ${shellQuote(remoteAssetDir)} && ` +
             `tar -xf ${shellQuote(remoteAssetTar)} -C ${shellQuote(remoteAssetDir)} && ` +
@@ -314,7 +314,7 @@ export async function prepareSandboxManagedRuntime(input: {
       await withTempDir("paperclip-sandbox-restore-", async (tempDir) => {
         const remoteWorkspaceTar = path.posix.join(runtimeRootDir, "workspace-download.tar");
         await input.client.run(
-          `sh -lc ${shellQuote(
+          `sh -c ${shellQuote(
             `mkdir -p ${shellQuote(runtimeRootDir)} && ` +
               `tar -cf ${shellQuote(remoteWorkspaceTar)} -C ${shellQuote(workspaceRemoteDir)} ` +
               `${tarExcludeFlags(input.workspaceExclude)} .`,
@@ -330,8 +330,10 @@ export async function prepareSandboxManagedRuntime(input: {
           archivePath: localArchivePath,
           localDir: extractedDir,
         });
-        await mirrorDirectory(extractedDir, input.workspaceLocalDir, {
-          preserveAbsent: [".paperclip-runtime", ...(input.preserveAbsentOnRestore ?? [])],
+        await mergeDirectoryWithBaseline({
+          baseline: baselineSnapshot,
+          sourceDir: extractedDir,
+          targetDir: input.workspaceLocalDir,
         });
       });
     },

packages/adapter-utils/src/sandbox-shell.ts

@@ -0,0 +1,7 @@
+export function preferredShellForSandbox(shellCommand: string | null | undefined): "bash" | "sh" {
+  return shellCommand === "bash" ? "bash" : "sh";
+}
+
+export function shellCommandArgs(script: string): string[] {
+  return ["-c", script];
+}

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

@@ -9,9 +9,13 @@ import {
   buildInvocationEnvForLogs,
   DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
   materializePaperclipSkillCopy,
+  refreshPaperclipWorkspaceEnvForExecution,
   renderPaperclipWakePrompt,
   runningProcesses,
   runChildProcess,
+  sanitizeSshRemoteEnv,
+  shapePaperclipWorkspaceEnvForExecution,
+  rewriteWorkspaceCwdEnvVarsForExecution,
   stringifyPaperclipWakePayload,
 } from "./server-utils.js";
 
@@ -60,6 +64,86 @@ describe("buildInvocationEnvForLogs", () => {
   });
 });
 
+describe("sanitizeSshRemoteEnv", () => {
+  it("drops inherited host shell identity variables for SSH remote execution", () => {
+    expect(
+      sanitizeSshRemoteEnv(
+        {
+          PATH: "/host/bin:/usr/bin",
+          HOME: "/Users/local",
+          NVM_DIR: "/Users/local/.nvm",
+          TMPDIR: "/var/folders/local/T",
+          XDG_CONFIG_HOME: "/Users/local/.config",
+          SAFE_VALUE: "visible",
+        },
+        {
+          PATH: "/host/bin:/usr/bin",
+          HOME: "/Users/local",
+          NVM_DIR: "/Users/local/.nvm",
+          TMPDIR: "/var/folders/local/T",
+          XDG_CONFIG_HOME: "/Users/local/.config",
+        },
+      ),
+    ).toEqual({
+      SAFE_VALUE: "visible",
+    });
+  });
+
+  it("preserves explicit remote overrides even for filtered key names", () => {
+    expect(
+      sanitizeSshRemoteEnv(
+        {
+          PATH: "/custom/remote/bin:/usr/bin",
+          HOME: "/home/agent",
+          TMPDIR: "/tmp",
+          SAFE_VALUE: "visible",
+        },
+        {
+          PATH: "/host/bin:/usr/bin",
+          HOME: "/Users/local",
+          TMPDIR: "/var/folders/local/T",
+        },
+      ),
+    ).toEqual({
+      PATH: "/custom/remote/bin:/usr/bin",
+      HOME: "/home/agent",
+      TMPDIR: "/tmp",
+      SAFE_VALUE: "visible",
+    });
+  });
+
+  it("filters identity keys via case-insensitive match against the inherited env", () => {
+    expect(
+      sanitizeSshRemoteEnv(
+        {
+          // Caller passed PATH in upper case while the inherited (Windows-style)
+          // host env exposes it as Path. The lookup must still treat them as
+          // equal so the leaked host PATH gets stripped.
+          PATH: "/host/bin:/usr/bin",
+          HOME: "/host/home",
+        },
+        {
+          Path: "/host/bin:/usr/bin",
+          home: "/host/home",
+        },
+      ),
+    ).toEqual({});
+  });
+
+  it("preserves explicitly-set identity keys when the inherited env disagrees in case but not in value", () => {
+    expect(
+      sanitizeSshRemoteEnv(
+        {
+          PATH: "/explicit/remote/bin",
+        },
+        {
+          Path: "/host/bin:/usr/bin",
+        },
+      ),
+    ).toEqual({ PATH: "/explicit/remote/bin" });
+  });
+});
+
 describe("materializePaperclipSkillCopy", () => {
   it("refuses to materialize into an ancestor of the source", async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skill-copy-"));
@@ -336,6 +420,9 @@ describe("renderPaperclipWakePrompt", () => {
   it("keeps the default local-agent prompt action-oriented", () => {
     expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("Start actionable work in this heartbeat");
     expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("do not stop at a plan");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("clear final disposition");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("evidence, not valid liveness paths by themselves");
+    expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("keep `in_progress` only when a live continuation path exists");
     expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("Prefer the smallest verification that proves the change");
     expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("Use child issues");
     expect(DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE).toContain("instead of polling agents, sessions, or processes");
@@ -369,8 +456,118 @@ describe("renderPaperclipWakePrompt", () => {
 
     expect(prompt).toContain("## Paperclip Wake Payload");
     expect(prompt).toContain("Execution contract: take concrete action in this heartbeat");
-    expect(prompt).toContain("use child issues instead of polling");
-    expect(prompt).toContain("mark blocked work with the unblock owner/action");
+    expect(prompt).toContain("clear final disposition");
+    expect(prompt).toContain("evidence, not valid liveness paths by themselves");
+    expect(prompt).toContain("Use child issues for long or parallel delegated work instead of polling");
+    expect(prompt).toContain("named unblock owner/action");
+  });
+
+  it("renders planning-mode directives for assignment and comment wakes", () => {
+    const assignmentPrompt = renderPaperclipWakePrompt({
+      reason: "issue_assigned",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-3404",
+        title: "Plan first",
+        status: "in_progress",
+        workMode: "planning",
+      },
+      commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },
+      comments: [],
+      fallbackFetchNeeded: false,
+    });
+
+    expect(assignmentPrompt).toContain("- issue work mode: planning");
+    expect(assignmentPrompt).toContain("Make the plan only. Do not write code or perform implementation work.");
+
+    const commentPrompt = renderPaperclipWakePrompt({
+      reason: "issue_commented",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-3404",
+        title: "Plan first",
+        status: "in_progress",
+        workMode: "planning",
+      },
+      commentIds: ["comment-1"],
+      latestCommentId: "comment-1",
+      commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
+      comments: [{ id: "comment-1", body: "Revise the plan" }],
+      fallbackFetchNeeded: false,
+    });
+
+    expect(commentPrompt).toContain("Update the plan only. Do not write code or perform implementation work.");
+  });
+
+  it("does not render stale accepted-plan continuation guidance for later planning comment wakes", () => {
+    const prompt = renderPaperclipWakePrompt({
+      reason: "issue_commented",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-3404",
+        title: "Plan first",
+        status: "in_progress",
+        workMode: "planning",
+      },
+      interactionKind: "request_confirmation",
+      interactionStatus: "accepted",
+      commentIds: ["comment-1"],
+      latestCommentId: "comment-1",
+      commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
+      comments: [{ id: "comment-1", body: "Revise the plan" }],
+      fallbackFetchNeeded: false,
+    });
+
+    expect(prompt).toContain("Update the plan only. Do not write code or perform implementation work.");
+    expect(prompt).not.toContain("accepted-plan continuation");
+    expect(prompt).not.toContain("Create child issues from the approved plan only");
+  });
+
+  it("renders accepted-plan continuation guidance for planning issues", () => {
+    const prompt = renderPaperclipWakePrompt({
+      reason: "issue_commented",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-3404",
+        title: "Plan first",
+        status: "in_progress",
+        workMode: "planning",
+      },
+      interactionKind: "request_confirmation",
+      interactionStatus: "accepted",
+      commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },
+      comments: [],
+      fallbackFetchNeeded: false,
+    });
+
+    expect(prompt).toContain("accepted-plan continuation");
+    expect(prompt).toContain("Create child issues from the approved plan only");
+    expect(prompt).toContain("may create child implementation issues");
+    expect(prompt).toContain("must not start implementation work on the planning issue itself");
+  });
+
+  it("keeps accepted-plan guidance when stale comment ids have no loaded comments", () => {
+    const prompt = renderPaperclipWakePrompt({
+      reason: "issue_commented",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-3404",
+        title: "Plan first",
+        status: "in_progress",
+        workMode: "planning",
+      },
+      interactionKind: "request_confirmation",
+      interactionStatus: "accepted",
+      commentIds: ["stale-comment-1"],
+      latestCommentId: "stale-comment-1",
+      commentWindow: { requestedCount: 1, includedCount: 0, missingCount: 1 },
+      comments: [],
+      fallbackFetchNeeded: true,
+    });
+
+    expect(prompt).toContain("accepted-plan continuation");
+    expect(prompt).toContain("Create child issues from the approved plan only");
+    expect(prompt).not.toContain("Update the plan only");
   });
 
   it("renders dependency-blocked interaction guidance", () => {
@@ -551,6 +748,183 @@ describe("applyPaperclipWorkspaceEnv", () => {
   });
 });
 
+describe("shapePaperclipWorkspaceEnvForExecution", () => {
+  it("rewrites workspace env paths for remote execution", () => {
+    const shaped = shapePaperclipWorkspaceEnvForExecution({
+      workspaceCwd: "/tmp/workspace",
+      workspaceWorktreePath: "/tmp/worktree",
+      workspaceHints: [
+        {
+          workspaceId: "workspace-1",
+          cwd: "/tmp/workspace",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+        },
+        {
+          workspaceId: "workspace-2",
+          cwd: "/tmp/other-workspace",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+        },
+        {
+          workspaceId: "workspace-3",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+        },
+      ],
+      executionTargetIsRemote: true,
+      executionCwd: "/remote/workspace",
+    });
+
+    expect(shaped).toEqual({
+      workspaceCwd: "/remote/workspace",
+      workspaceWorktreePath: null,
+      workspaceHints: [
+        {
+          workspaceId: "workspace-1",
+          cwd: "/remote/workspace",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+        },
+        {
+          workspaceId: "workspace-2",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+        },
+        {
+          workspaceId: "workspace-3",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+        },
+      ],
+    });
+  });
+
+  it("leaves local execution workspace paths unchanged", () => {
+    const workspaceHints = [{ workspaceId: "workspace-1", cwd: "/tmp/workspace" }];
+    const shaped = shapePaperclipWorkspaceEnvForExecution({
+      workspaceCwd: "/tmp/workspace",
+      workspaceWorktreePath: "/tmp/worktree",
+      workspaceHints,
+      executionTargetIsRemote: false,
+      executionCwd: "/remote/workspace",
+    });
+
+    expect(shaped).toEqual({
+      workspaceCwd: "/tmp/workspace",
+      workspaceWorktreePath: "/tmp/worktree",
+      workspaceHints,
+    });
+  });
+});
+
+describe("rewriteWorkspaceCwdEnvVarsForExecution", () => {
+  it("rewrites custom *_WORKSPACE_CWD env vars for remote execution", () => {
+    const env = rewriteWorkspaceCwdEnvVarsForExecution({
+      workspaceCwd: "/host/workspace",
+      executionCwd: "/remote/workspace",
+      executionTargetIsRemote: true,
+      env: {
+        QA_PROJECT_WORKSPACE_CWD: "/host/workspace",
+        RANDOM_WORKSPACE_CWD: "/host/workspace",
+        OTHER_ENV: "/host/workspace",
+      },
+    });
+
+    expect(env).toEqual({
+      QA_PROJECT_WORKSPACE_CWD: "/remote/workspace",
+      RANDOM_WORKSPACE_CWD: "/remote/workspace",
+      OTHER_ENV: "/host/workspace",
+    });
+  });
+
+  it("does not rewrite matching values for local execution", () => {
+    const env = rewriteWorkspaceCwdEnvVarsForExecution({
+      workspaceCwd: "/host/workspace",
+      executionCwd: "/remote/workspace",
+      executionTargetIsRemote: false,
+      env: {
+        QA_PROJECT_WORKSPACE_CWD: "/host/workspace",
+        RANDOM_WORKSPACE_CWD_TOKEN: "/host/workspace",
+      },
+    });
+
+    expect(env).toEqual({
+      QA_PROJECT_WORKSPACE_CWD: "/host/workspace",
+      RANDOM_WORKSPACE_CWD_TOKEN: "/host/workspace",
+    });
+  });
+
+  it("only rewrites matching *_WORKSPACE_CWD string values", () => {
+    const env = rewriteWorkspaceCwdEnvVarsForExecution({
+      workspaceCwd: "/host/workspace",
+      executionCwd: "/remote/workspace",
+      executionTargetIsRemote: true,
+      env: {
+        MATCHING_WORKSPACE_CWD: "/host/workspace/.",
+        DIFFERENT_WORKSPACE_CWD: "/host/other-workspace",
+        BLANK_WORKSPACE_CWD: "   ",
+        NON_STRING_WORKSPACE_CWD: 42,
+      },
+    });
+
+    expect(env).toEqual({
+      MATCHING_WORKSPACE_CWD: "/remote/workspace",
+      DIFFERENT_WORKSPACE_CWD: "/host/other-workspace",
+      BLANK_WORKSPACE_CWD: "   ",
+    });
+  });
+});
+
+describe("refreshPaperclipWorkspaceEnvForExecution", () => {
+  it("rewrites Paperclip workspace env to the prepared remote runtime cwd", () => {
+    const env: Record<string, string> = {
+      PAPERCLIP_WORKSPACE_CWD: "/remote/workspace",
+      PAPERCLIP_WORKSPACE_WORKTREE_PATH: "/host/worktree",
+      PAPERCLIP_WORKSPACES_JSON: JSON.stringify([
+        { workspaceId: "workspace-1", cwd: "/remote/workspace" },
+        { workspaceId: "workspace-2", cwd: "/tmp/other" },
+      ]),
+      QA_PROJECT_WORKSPACE_CWD: "/remote/workspace",
+    };
+
+    const shaped = refreshPaperclipWorkspaceEnvForExecution({
+      env,
+      envConfig: {
+        QA_PROJECT_WORKSPACE_CWD: "/host/workspace",
+      },
+      workspaceCwd: "/host/workspace",
+      workspaceWorktreePath: "/host/worktree",
+      workspaceHints: [
+        { workspaceId: "workspace-1", cwd: "/host/workspace" },
+        { workspaceId: "workspace-2", cwd: "/tmp/other" },
+      ],
+      executionTargetIsRemote: true,
+      executionCwd: "/remote/workspace/.paperclip-runtime/runs/run-1/workspace",
+    });
+
+    expect(shaped).toEqual({
+      workspaceCwd: "/remote/workspace/.paperclip-runtime/runs/run-1/workspace",
+      workspaceWorktreePath: null,
+      workspaceHints: [
+        {
+          workspaceId: "workspace-1",
+          cwd: "/remote/workspace/.paperclip-runtime/runs/run-1/workspace",
+        },
+        {
+          workspaceId: "workspace-2",
+        },
+      ],
+    });
+    expect(env.PAPERCLIP_WORKSPACE_CWD).toBe("/remote/workspace/.paperclip-runtime/runs/run-1/workspace");
+    expect(env.PAPERCLIP_WORKSPACE_WORKTREE_PATH).toBeUndefined();
+    expect(env.QA_PROJECT_WORKSPACE_CWD).toBe("/remote/workspace/.paperclip-runtime/runs/run-1/workspace");
+    expect(JSON.parse(env.PAPERCLIP_WORKSPACES_JSON ?? "[]")).toEqual([
+      {
+        workspaceId: "workspace-1",
+        cwd: "/remote/workspace/.paperclip-runtime/runs/run-1/workspace",
+      },
+      {
+        workspaceId: "workspace-2",
+      },
+    ]);
+  });
+});
+
 describe("appendWithByteCap", () => {
   it("keeps valid UTF-8 when trimming through multibyte text", () => {
     const output = appendWithByteCap("prefix ", "hello — world", 7);

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

@@ -1,7 +1,9 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
 import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";
 import { redactCommandText } from "./command-redaction.js";
 import type {
@@ -77,6 +79,8 @@ export const runningProcesses = new Map<string, RunningProcess>();
 export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 export const MAX_EXCERPT_BYTES = 32 * 1024;
 const TERMINAL_RESULT_SCAN_OVERLAP_CHARS = 64 * 1024;
+const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
 const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
 const REDACTED_LOG_VALUE = "***REDACTED***";
 const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
@@ -87,12 +91,33 @@ const MATERIALIZED_SKILL_SENTINEL = ".paperclip-materialized-skill.json";
 const MATERIALIZED_SKILL_LOCK_OWNER = "owner.json";
 const MATERIALIZED_SKILL_LOCK_STALE_MS = 30_000;
 
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+export function resolvePaperclipInstanceRootForAdapter(input: {
+  homeDir?: string;
+  instanceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): string {
+  const env = input.env ?? process.env;
+  const homeRaw = input.homeDir?.trim() || env.PAPERCLIP_HOME?.trim();
+  const homeDir = path.resolve(homeRaw ? expandHomePrefix(homeRaw) : path.resolve(os.homedir(), ".paperclip"));
+  const instanceId = input.instanceId?.trim() || env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_PAPERCLIP_INSTANCE_ID;
+  if (!PATH_SEGMENT_RE.test(instanceId)) throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${instanceId}'.`);
+  return path.resolve(homeDir, "instances", instanceId);
+}
+
 export const DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE = [
   "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
   "",
   "Execution contract:",
   "- Start actionable work in this heartbeat; do not stop at a plan unless the issue asks for planning.",
-  "- Leave durable progress in comments, documents, or work products with a clear next action.",
+  "- Leave durable progress in comments, documents, or work products, then update the issue to a clear final disposition before ending the heartbeat.",
+  "- Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",
+  "- Final disposition checklist: mark `done` when complete; use `in_review` only with a real reviewer, approval, interaction, or monitor path; use `blocked` only with first-class blockers or a named unblock owner/action; create delegated follow-up issues with blockers when another agent owns the next step; keep `in_progress` only when a live continuation path exists.",
   "- Prefer the smallest verification that proves the change; do not default to full workspace typecheck/build/test on every heartbeat unless the task scope warrants it.",
   "- Use child issues for parallel or long delegated work instead of polling agents, sessions, or processes.",
   "- If woken by a human comment on a dependency-blocked issue, respond or triage the comment without treating the blocked deliverable work as unblocked.",
@@ -280,6 +305,7 @@ type PaperclipWakeIssue = {
   identifier: string | null;
   title: string | null;
   status: string | null;
+  workMode: string | null;
   priority: string | null;
 };
 
@@ -365,6 +391,8 @@ type PaperclipWakePayload = {
   executionStage: PaperclipWakeExecutionStage | null;
   continuationSummary: PaperclipWakeContinuationSummary | null;
   livenessContinuation: PaperclipWakeLivenessContinuation | null;
+  interactionKind: string | null;
+  interactionStatus: string | null;
   childIssueSummaries: PaperclipWakeChildIssueSummary[];
   childIssueSummaryTruncated: boolean;
   commentIds: string[];
@@ -383,6 +411,7 @@ function normalizePaperclipWakeIssue(value: unknown): PaperclipWakeIssue | null
   const identifier = asString(issue.identifier, "").trim() || null;
   const title = asString(issue.title, "").trim() || null;
   const status = asString(issue.status, "").trim() || null;
+  const workMode = asString(issue.workMode, "").trim() || null;
   const priority = asString(issue.priority, "").trim() || null;
   if (!id && !identifier && !title) return null;
   return {
@@ -390,6 +419,7 @@ function normalizePaperclipWakeIssue(value: unknown): PaperclipWakeIssue | null
     identifier,
     title,
     status,
+    workMode,
     priority,
   };
 }
@@ -572,6 +602,8 @@ export function normalizePaperclipWakePayload(value: unknown): PaperclipWakePayl
     executionStage,
     continuationSummary,
     livenessContinuation,
+    interactionKind: asString(payload.interactionKind, "").trim() || null,
+    interactionStatus: asString(payload.interactionStatus, "").trim() || null,
     childIssueSummaries,
     childIssueSummaryTruncated: asBoolean(payload.childIssueSummaryTruncated, false),
     commentIds,
@@ -591,6 +623,15 @@ export function stringifyPaperclipWakePayload(value: unknown): string | null {
   return JSON.stringify(normalized);
 }
 
+export function readPaperclipIssueWorkModeFromContext(value: unknown): string | null {
+  const context = parseObject(value);
+  const issue = parseObject(context.paperclipIssue);
+  const direct = asString(issue.workMode, "").trim();
+  if (direct) return direct;
+  const wake = normalizePaperclipWakePayload(context.paperclipWake);
+  return wake?.issue?.workMode ?? null;
+}
+
 export function renderPaperclipWakePrompt(
   value: unknown,
   options: { resumedSession?: boolean } = {},
@@ -614,7 +655,7 @@ export function renderPaperclipWakePrompt(
         "Focus on the new wake delta below and continue the current task without restating the full heartbeat boilerplate.",
         "Fetch the API thread only when `fallbackFetchNeeded` is true or you need broader history than this batch.",
         "",
-        "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action, use child issues instead of polling for long or parallel work, and mark blocked work with the unblock owner/action.",
+        "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",
         "",
         `- reason: ${normalized.reason ?? "unknown"}`,
         `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
@@ -631,7 +672,7 @@ export function renderPaperclipWakePrompt(
         "Use this inline wake data first before refetching the issue thread.",
         "Only fetch the API thread when `fallbackFetchNeeded` is true or you need broader history than this batch.",
         "",
-        "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress with a clear next action, use child issues instead of polling for long or parallel work, and mark blocked work with the unblock owner/action.",
+        "Execution contract: take concrete action in this heartbeat when the issue is actionable; do not stop at a plan unless planning was requested. Leave durable progress and then give the issue a clear final disposition before ending the heartbeat: `done`, `in_review` with a real reviewer/approval/interaction path, `blocked` with first-class blockers or a named unblock owner/action, delegated follow-up issues with blockers, or `in_progress` only when a live continuation path exists. Use child issues for long or parallel delegated work instead of polling. Comments, documents, screenshots, work products, and `Remaining` bullets are evidence, not valid liveness paths by themselves.",
         "",
         `- reason: ${normalized.reason ?? "unknown"}`,
         `- issue: ${normalized.issue?.identifier ?? normalized.issue?.id ?? "unknown"}${normalized.issue?.title ? ` ${normalized.issue.title}` : ""}`,
@@ -643,9 +684,31 @@ export function renderPaperclipWakePrompt(
   if (normalized.issue?.status) {
     lines.push(`- issue status: ${normalized.issue.status}`);
   }
+  if (normalized.issue?.workMode) {
+    lines.push(`- issue work mode: ${normalized.issue.workMode}`);
+  }
   if (normalized.issue?.priority) {
     lines.push(`- issue priority: ${normalized.issue.priority}`);
   }
+  if (normalized.issue?.workMode === "planning") {
+    const hasWakeComments = normalized.comments.length > 0;
+    const acceptedPlanContinuation =
+      !hasWakeComments &&
+      normalized.interactionKind === "request_confirmation" && normalized.interactionStatus === "accepted";
+    let directive = "Make the plan only. Do not write code or perform implementation work.";
+    if (hasWakeComments) {
+      directive = "Update the plan only. Do not write code or perform implementation work.";
+    }
+    if (acceptedPlanContinuation) {
+      directive = "Create child issues from the approved plan only. Do not write code or perform implementation work on the planning issue.";
+    }
+    lines.push(`- planning directive: ${directive}`);
+    if (acceptedPlanContinuation) {
+      lines.push(
+        "- accepted-plan continuation: you may create child implementation issues from the approved plan, but must not start implementation work on the planning issue itself",
+      );
+    }
+  }
   if (normalized.checkedOutByHarness) {
     lines.push("- checkout: already claimed by the harness for this run");
   }
@@ -885,6 +948,177 @@ export function applyPaperclipWorkspaceEnv(
   return env;
 }
 
+export function shapePaperclipWorkspaceEnvForExecution(input: {
+  workspaceCwd?: string | null;
+  workspaceWorktreePath?: string | null;
+  workspaceHints?: Array<Record<string, unknown>>;
+  executionTargetIsRemote?: boolean;
+  executionCwd?: string | null;
+}): {
+  workspaceCwd: string | null;
+  workspaceWorktreePath: string | null;
+  workspaceHints: Array<Record<string, unknown>>;
+} {
+  const workspaceCwd =
+    typeof input.workspaceCwd === "string" && input.workspaceCwd.trim().length > 0
+      ? input.workspaceCwd.trim()
+      : null;
+  const workspaceWorktreePath =
+    typeof input.workspaceWorktreePath === "string" && input.workspaceWorktreePath.trim().length > 0
+      ? input.workspaceWorktreePath.trim()
+      : null;
+  const workspaceHints = Array.isArray(input.workspaceHints) ? input.workspaceHints : [];
+
+  if (!input.executionTargetIsRemote) {
+    return {
+      workspaceCwd,
+      workspaceWorktreePath,
+      workspaceHints,
+    };
+  }
+
+  const executionCwd =
+    typeof input.executionCwd === "string" && input.executionCwd.trim().length > 0
+      ? input.executionCwd.trim()
+      : null;
+  // On a remote target we must never fall back to the local workspaceCwd —
+  // doing so leaks host paths into the remote env (the exact failure mode
+  // this helper exists to prevent). Callers are expected to resolve
+  // executionCwd via adapterExecutionTargetRemoteCwd before calling this
+  // helper, which always returns a non-empty string. Surface a warning so
+  // future callers don't silently regress to the leak.
+  if (executionCwd === null) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "[paperclip] shapePaperclipWorkspaceEnvForExecution called with executionCwd=null on a remote target; " +
+        "stripping workspaceCwd to avoid leaking local paths into the remote environment.",
+    );
+  }
+  const realizedWorkspaceCwd = executionCwd;
+  const localWorkspaceCwd = workspaceCwd ? path.resolve(workspaceCwd) : null;
+  const shapedWorkspaceHints = workspaceHints.map((hint) => {
+    const nextHint = { ...hint };
+    const hintCwd = typeof nextHint.cwd === "string" ? nextHint.cwd.trim() : "";
+    if (!hintCwd) return nextHint;
+
+    if (localWorkspaceCwd && path.resolve(hintCwd) === localWorkspaceCwd) {
+      if (realizedWorkspaceCwd) {
+        nextHint.cwd = realizedWorkspaceCwd;
+      } else {
+        delete nextHint.cwd;
+      }
+      return nextHint;
+    }
+
+    delete nextHint.cwd;
+    return nextHint;
+  });
+
+  return {
+    workspaceCwd: realizedWorkspaceCwd,
+    workspaceWorktreePath: null,
+    workspaceHints: shapedWorkspaceHints,
+  };
+}
+
+export function rewriteWorkspaceCwdEnvVarsForExecution(input: {
+  env: Record<string, unknown>;
+  workspaceCwd?: string | null;
+  executionCwd?: string | null;
+  executionTargetIsRemote?: boolean;
+}): Record<string, string> {
+  const nextEnv = Object.fromEntries(
+    Object.entries(input.env)
+      .filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+  ) as Record<string, string>;
+  const localWorkspaceCwd = typeof input.workspaceCwd === "string" && input.workspaceCwd.trim().length > 0
+    ? path.resolve(input.workspaceCwd)
+    : null;
+  // executionCwd is a remote path on the target host; we deliberately do not
+  // run `path.resolve` against it because that applies host-Node semantics
+  // (current working directory, host path separator) to a path that lives on
+  // the remote shell. Callers always pass absolute remote paths, so we
+  // forward the trimmed value verbatim.
+  const remoteWorkspaceCwd = typeof input.executionCwd === "string" && input.executionCwd.trim().length > 0
+    ? input.executionCwd.trim()
+    : null;
+
+  if (!input.executionTargetIsRemote || !localWorkspaceCwd || !remoteWorkspaceCwd) {
+    return nextEnv;
+  }
+
+  for (const [key, value] of Object.entries(nextEnv)) {
+    if (!key.endsWith("_WORKSPACE_CWD")) continue;
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    if (path.resolve(trimmed) !== localWorkspaceCwd) continue;
+    nextEnv[key] = remoteWorkspaceCwd;
+  }
+
+  return nextEnv;
+}
+
+export function refreshPaperclipWorkspaceEnvForExecution(input: {
+  env: Record<string, string>;
+  envConfig?: Record<string, unknown>;
+  workspaceCwd?: string | null;
+  workspaceSource?: string | null;
+  workspaceStrategy?: string | null;
+  workspaceId?: string | null;
+  workspaceRepoUrl?: string | null;
+  workspaceRepoRef?: string | null;
+  workspaceBranch?: string | null;
+  workspaceWorktreePath?: string | null;
+  workspaceHints?: Array<Record<string, unknown>>;
+  agentHome?: string | null;
+  executionTargetIsRemote?: boolean;
+  executionCwd?: string | null;
+}): {
+  workspaceCwd: string | null;
+  workspaceWorktreePath: string | null;
+  workspaceHints: Array<Record<string, unknown>>;
+} {
+  const shapedWorkspaceEnv = shapePaperclipWorkspaceEnvForExecution({
+    workspaceCwd: input.workspaceCwd,
+    workspaceWorktreePath: input.workspaceWorktreePath,
+    workspaceHints: input.workspaceHints,
+    executionTargetIsRemote: input.executionTargetIsRemote,
+    executionCwd: input.executionCwd,
+  });
+
+  delete input.env.PAPERCLIP_WORKSPACE_CWD;
+  delete input.env.PAPERCLIP_WORKSPACE_WORKTREE_PATH;
+  delete input.env.PAPERCLIP_WORKSPACES_JSON;
+
+  applyPaperclipWorkspaceEnv(input.env, {
+    workspaceCwd: shapedWorkspaceEnv.workspaceCwd,
+    workspaceSource: input.workspaceSource,
+    workspaceStrategy: input.workspaceStrategy,
+    workspaceId: input.workspaceId,
+    workspaceRepoUrl: input.workspaceRepoUrl,
+    workspaceRepoRef: input.workspaceRepoRef,
+    workspaceBranch: input.workspaceBranch,
+    workspaceWorktreePath: shapedWorkspaceEnv.workspaceWorktreePath,
+    agentHome: input.agentHome,
+  });
+
+  if (shapedWorkspaceEnv.workspaceHints.length > 0) {
+    input.env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(shapedWorkspaceEnv.workspaceHints);
+  }
+
+  const shapedEnvConfig = rewriteWorkspaceCwdEnvVarsForExecution({
+    env: input.envConfig ?? {},
+    workspaceCwd: input.workspaceCwd,
+    executionCwd: shapedWorkspaceEnv.workspaceCwd,
+    executionTargetIsRemote: input.executionTargetIsRemote,
+  });
+  for (const [key, value] of Object.entries(shapedEnvConfig)) {
+    input.env[key] = value;
+  }
+
+  return shapedWorkspaceEnv;
+}
+
 export function sanitizeInheritedPaperclipEnv(baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...baseEnv };
   for (const key of Object.keys(env)) {
@@ -966,6 +1200,13 @@ function quoteForCmd(arg: string) {
   return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
 }
 
+export function sanitizeSshRemoteEnv(
+  env: Record<string, string>,
+  inheritedEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  return sanitizeRemoteExecutionEnv(env, inheritedEnv);
+}
+
 function resolveWindowsCmdShell(env: NodeJS.ProcessEnv): string {
   const fallbackRoot = env.SystemRoot || process.env.SystemRoot || "C:\\Windows";
   return path.join(fallbackRoot, "System32", "cmd.exe");

packages/adapter-utils/src/session-compaction.ts

@@ -40,6 +40,7 @@ export const LEGACY_SESSIONED_ADAPTER_TYPES = new Set([
   "acpx_local",
   "claude_local",
   "codex_local",
+  "cursor_cloud",
   "cursor",
   "gemini_local",
   "hermes_local",
@@ -63,6 +64,11 @@ export const ADAPTER_SESSION_MANAGEMENT: Record<string, AdapterSessionManagement
     nativeContextManagement: "confirmed",
     defaultSessionCompaction: ADAPTER_MANAGED_SESSION_POLICY,
   },
+  cursor_cloud: {
+    supportsSessionResume: true,
+    nativeContextManagement: "unknown",
+    defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
+  },
   cursor: {
     supportsSessionResume: true,
     nativeContextManagement: "unknown",

packages/adapter-utils/src/ssh-fixture.test.ts

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -15,6 +15,10 @@ import {
   startSshEnvLabFixture,
   stopSshEnvLabFixture,
 } from "./ssh.js";
+import { prepareRemoteManagedRuntime } from "./remote-managed-runtime.js";
+
+const SSH_FIXTURE_TEST_TIMEOUT_MS = 30_000;
+let sshEnvLabUnsupportedReason: string | null = null;
 
 async function git(cwd: string, args: string[]): Promise<string> {
   return await new Promise((resolve, reject) => {
@@ -28,6 +32,28 @@ async function git(cwd: string, args: string[]): Promise<string> {
   });
 }
 
+async function startSshEnvLabFixtureOrSkip(statePath: string, label: string) {
+  if (sshEnvLabUnsupportedReason) {
+    console.warn(`Skipping ${label}: ${sshEnvLabUnsupportedReason}`);
+    return null;
+  }
+
+  const support = await getSshEnvLabSupport();
+  if (!support.supported) {
+    sshEnvLabUnsupportedReason = support.reason ?? "unsupported environment";
+    console.warn(`Skipping ${label}: ${sshEnvLabUnsupportedReason}`);
+    return null;
+  }
+
+  try {
+    return await startSshEnvLabFixture({ statePath });
+  } catch (error) {
+    sshEnvLabUnsupportedReason = error instanceof Error ? error.message : String(error);
+    console.warn(`Skipping ${label}: ${sshEnvLabUnsupportedReason}`);
+    return null;
+  }
+}
+
 describe("ssh env-lab fixture", () => {
   const cleanupDirs: string[] = [];
 
@@ -40,24 +66,17 @@ describe("ssh env-lab fixture", () => {
   });
 
   it("starts an isolated sshd fixture and executes commands through it", async () => {
-    const support = await getSshEnvLabSupport();
-    if (!support.supported) {
-      console.warn(
-        `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,
-      );
-      return;
-    }
-
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);
     const statePath = path.join(rootDir, "state.json");
 
-    const started = await startSshEnvLabFixture({ statePath });
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "SSH env-lab fixture test");
+    if (!started) return;
     const config = await buildSshEnvLabFixtureConfig(started);
     const quotedWorkspace = JSON.stringify(started.workspaceDir);
     const result = await runSshCommand(
       config,
-      `sh -lc 'cd ${quotedWorkspace} && pwd'`,
+      `cd ${quotedWorkspace} && pwd`,
     );
 
     expect(result.stdout.trim()).toBe(started.workspaceDir);
@@ -68,22 +87,44 @@ describe("ssh env-lab fixture", () => {
 
     const stopped = await readSshEnvLabFixtureStatus(statePath);
     expect(stopped.running).toBe(false);
-  });
-
-  it("does not treat an unrelated reused pid as the running fixture", async () => {
-    const support = await getSshEnvLabSupport();
-    if (!support.supported) {
-      console.warn(
-        `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,
-      );
-      return;
-    }
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 
+  it("forwards stdin to remote SSH commands", async () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);
     const statePath = path.join(rootDir, "state.json");
 
-    const started = await startSshEnvLabFixture({ statePath });
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "SSH stdin forwarding test");
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const remotePath = path.posix.join(started.workspaceDir, "stdin-forwarded.txt");
+
+    await runSshCommand(
+      config,
+      `cat > ${JSON.stringify(remotePath)}`,
+      {
+        stdin: "hello over ssh stdin\n",
+        timeoutMs: 30_000,
+        maxBuffer: 256 * 1024,
+      },
+    );
+
+    const result = await runSshCommand(
+      config,
+      `cat ${JSON.stringify(remotePath)}`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    expect(result.stdout).toBe("hello over ssh stdin\n");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
+  it("does not treat an unrelated reused pid as the running fixture", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "SSH env-lab fixture test");
+    if (!started) return;
     await stopSshEnvLabFixture(statePath);
     await mkdir(path.dirname(statePath), { recursive: true });
 
@@ -96,11 +137,12 @@ describe("ssh env-lab fixture", () => {
     const staleStatus = await readSshEnvLabFixtureStatus(statePath);
     expect(staleStatus.running).toBe(false);
 
-    const restarted = await startSshEnvLabFixture({ statePath });
+    const restarted = await startSshEnvLabFixtureOrSkip(statePath, "SSH env-lab fixture restart test");
+    if (!restarted) return;
     expect(restarted.pid).not.toBe(process.pid);
 
     await stopSshEnvLabFixture(statePath);
-  });
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 
   it("rejects invalid environment variable keys when constructing SSH spawn targets", async () => {
     await expect(
@@ -125,14 +167,6 @@ describe("ssh env-lab fixture", () => {
   });
 
   it("syncs a local directory into the remote fixture workspace", async () => {
-    const support = await getSshEnvLabSupport();
-    if (!support.supported) {
-      console.warn(
-        `Skipping SSH env-lab fixture test: ${support.reason ?? "unsupported environment"}`,
-      );
-      return;
-    }
-
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);
     const statePath = path.join(rootDir, "state.json");
@@ -142,7 +176,8 @@ describe("ssh env-lab fixture", () => {
     await writeFile(path.join(localDir, "message.txt"), "hello from paperclip\n", "utf8");
     await writeFile(path.join(localDir, "._message.txt"), "should never sync\n", "utf8");
 
-    const started = await startSshEnvLabFixture({ statePath });
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "SSH env-lab fixture test");
+    if (!started) return;
     const config = await buildSshEnvLabFixtureConfig(started);
     const remoteDir = path.posix.join(started.workspaceDir, "overlay");
 
@@ -157,22 +192,14 @@ describe("ssh env-lab fixture", () => {
 
     const result = await runSshCommand(
       config,
-      `sh -lc 'cat ${JSON.stringify(path.posix.join(remoteDir, "message.txt"))} && if [ -e ${JSON.stringify(path.posix.join(remoteDir, "._message.txt"))} ]; then echo appledouble-present; fi'`,
+      `cat ${JSON.stringify(path.posix.join(remoteDir, "message.txt"))} && if [ -e ${JSON.stringify(path.posix.join(remoteDir, "._message.txt"))} ]; then echo appledouble-present; fi`,
     );
 
     expect(result.stdout).toContain("hello from paperclip");
     expect(result.stdout).not.toContain("appledouble-present");
-  });
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 
   it("can dereference local symlinks while syncing to the remote fixture", async () => {
-    const support = await getSshEnvLabSupport();
-    if (!support.supported) {
-      console.warn(
-        `Skipping SSH symlink sync test: ${support.reason ?? "unsupported environment"}`,
-      );
-      return;
-    }
-
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);
     const statePath = path.join(rootDir, "state.json");
@@ -184,7 +211,8 @@ describe("ssh env-lab fixture", () => {
     await writeFile(path.join(sourceDir, "auth.json"), "{\"token\":\"secret\"}\n", "utf8");
     await symlink(path.join(sourceDir, "auth.json"), path.join(localDir, "auth.json"));
 
-    const started = await startSshEnvLabFixture({ statePath });
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "SSH symlink sync test");
+    if (!started) return;
     const config = await buildSshEnvLabFixtureConfig(started);
     const remoteDir = path.posix.join(started.workspaceDir, "overlay-follow-links");
 
@@ -200,29 +228,22 @@ describe("ssh env-lab fixture", () => {
 
     const result = await runSshCommand(
       config,
-      `sh -lc 'if [ -L ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))} ]; then echo symlink; else echo regular; fi && cat ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))}'`,
+      `if [ -L ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))} ]; then echo symlink; else echo regular; fi && cat ${JSON.stringify(path.posix.join(remoteDir, "auth.json"))}`,
     );
 
     expect(result.stdout).toContain("regular");
     expect(result.stdout).toContain("{\"token\":\"secret\"}");
-  });
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 
   it("round-trips a git workspace through the SSH fixture", async () => {
-    const support = await getSshEnvLabSupport();
-    if (!support.supported) {
-      console.warn(
-        `Skipping SSH workspace round-trip test: ${support.reason ?? "unsupported environment"}`,
-      );
-      return;
-    }
-
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);
     const statePath = path.join(rootDir, "state.json");
     const localRepo = path.join(rootDir, "local-workspace");
 
     await mkdir(localRepo, { recursive: true });
-    await git(localRepo, ["init", "-b", "main"]);
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
     await git(localRepo, ["config", "user.name", "Paperclip Test"]);
     await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
     await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
@@ -233,7 +254,8 @@ describe("ssh env-lab fixture", () => {
     await writeFile(path.join(localRepo, "tracked.txt"), "dirty local\n", "utf8");
     await writeFile(path.join(localRepo, "untracked.txt"), "from local\n", "utf8");
 
-    const started = await startSshEnvLabFixture({ statePath });
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "SSH workspace round-trip test");
+    if (!started) return;
     const config = await buildSshEnvLabFixtureConfig(started);
     const spec = {
       ...config,
@@ -248,7 +270,7 @@ describe("ssh env-lab fixture", () => {
 
     const remoteStatus = await runSshCommand(
       config,
-      `sh -lc 'cd ${JSON.stringify(started.workspaceDir)} && git status --short'`,
+      `cd ${JSON.stringify(started.workspaceDir)} && git status --short`,
     );
     expect(remoteStatus.stdout).toContain("M tracked.txt");
     expect(remoteStatus.stdout).toContain("?? untracked.txt");
@@ -256,7 +278,7 @@ describe("ssh env-lab fixture", () => {
 
     await runSshCommand(
       config,
-      `sh -lc 'cd ${JSON.stringify(started.workspaceDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && git add tracked.txt untracked.txt && git commit -m "remote update" >/dev/null && printf "remote dirty\\n" > tracked.txt && printf "remote extra\\n" > remote-only.txt'`,
+      `cd ${JSON.stringify(started.workspaceDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && git add tracked.txt untracked.txt && git commit -m "remote update" >/dev/null && printf "remote dirty\\n" > tracked.txt && printf "remote extra\\n" > remote-only.txt`,
       { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
     );
 
@@ -271,5 +293,222 @@ describe("ssh env-lab fixture", () => {
     expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toBe("remote update");
     expect(await git(localRepo, ["status", "--short"])).toContain("M tracked.txt");
     expect(await git(localRepo, ["status", "--short"])).not.toContain("._tracked.txt");
-  });
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
+  it("preserves both concurrent SSH restores in a shared git workspace", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "concurrent SSH restore test");
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    const preparedA = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-a",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+    const preparedB = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-b",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+
+    expect(preparedA.workspaceRemoteDir).not.toBe(preparedB.workspaceRemoteDir);
+
+    await runSshCommand(
+      config,
+      `printf "from run a\\n" > ${JSON.stringify(path.posix.join(preparedA.workspaceRemoteDir, "run-a.txt"))}`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+    await runSshCommand(
+      config,
+      `printf "from run b\\n" > ${JSON.stringify(path.posix.join(preparedB.workspaceRemoteDir, "run-b.txt"))}`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await Promise.all([
+      preparedA.restoreWorkspace(),
+      preparedB.restoreWorkspace(),
+    ]);
+
+    await expect(readFile(path.join(localRepo, "run-a.txt"), "utf8")).resolves.toBe("from run a\n");
+    await expect(readFile(path.join(localRepo, "run-b.txt"), "utf8")).resolves.toBe("from run b\n");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
+  it("preserves nested per-run files across sequential SSH restores with stale baselines", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "sequential nested SSH restore test");
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    const preparedA = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-a",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+    const preparedB = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-b",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+
+    await runSshCommand(
+      config,
+      `mkdir -p ${JSON.stringify(path.posix.join(preparedA.workspaceRemoteDir, "manual-qa/environment-matrix/ssh"))} && printf "from run a\\n" > ${JSON.stringify(path.posix.join(preparedA.workspaceRemoteDir, "manual-qa/environment-matrix/ssh/claude_local.md"))}`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+    await runSshCommand(
+      config,
+      `mkdir -p ${JSON.stringify(path.posix.join(preparedB.workspaceRemoteDir, "manual-qa/environment-matrix/ssh"))} && printf "from run b\\n" > ${JSON.stringify(path.posix.join(preparedB.workspaceRemoteDir, "manual-qa/environment-matrix/ssh/codex_local.md"))}`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await preparedA.restoreWorkspace();
+    await preparedB.restoreWorkspace();
+
+    await expect(readFile(path.join(localRepo, "manual-qa/environment-matrix/ssh/claude_local.md"), "utf8")).resolves
+      .toBe("from run a\n");
+    await expect(readFile(path.join(localRepo, "manual-qa/environment-matrix/ssh/codex_local.md"), "utf8")).resolves
+      .toBe("from run b\n");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
+  it("round-trips remote git commits through the managed runtime restore path", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "managed-runtime SSH git round-trip test");
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    const prepared = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-commit",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+
+    await runSshCommand(
+      config,
+      `cd ${JSON.stringify(prepared.workspaceRemoteDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && printf "committed\\n" > tracked.txt && git add tracked.txt && git commit -m "remote update" >/dev/null && printf "dirty remote\\n" > tracked.txt`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await prepared.restoreWorkspace();
+
+    expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toBe("remote update");
+    await expect(readFile(path.join(localRepo, "tracked.txt"), "utf8")).resolves.toBe("dirty remote\n");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
+  it("merges concurrent remote commits through the managed runtime restore path", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+
+    const started = await startSshEnvLabFixtureOrSkip(statePath, "concurrent managed-runtime SSH git merge test");
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    const preparedA = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-commit-a",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+    const preparedB = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-commit-b",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+
+    await runSshCommand(
+      config,
+      `cd ${JSON.stringify(preparedA.workspaceRemoteDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && printf "from run a\\n" > run-a.txt && git add run-a.txt && git commit -m "remote update a" >/dev/null`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+    await runSshCommand(
+      config,
+      `cd ${JSON.stringify(preparedB.workspaceRemoteDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && printf "from run b\\n" > run-b.txt && git add run-b.txt && git commit -m "remote update b" >/dev/null`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await Promise.all([
+      preparedA.restoreWorkspace(),
+      preparedB.restoreWorkspace(),
+    ]);
+
+    await expect(readFile(path.join(localRepo, "run-a.txt"), "utf8")).resolves.toBe("from run a\n");
+    await expect(readFile(path.join(localRepo, "run-b.txt"), "utf8")).resolves.toBe("from run b\n");
+    expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toContain("Paperclip SSH sync merge");
+
+    const recentSubjects = await git(localRepo, ["log", "--pretty=%s", "-3"]);
+    expect(recentSubjects).toContain("remote update a");
+    expect(recentSubjects).toContain("remote update b");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 });

packages/adapter-utils/src/ssh.ts

@@ -1,8 +1,13 @@
+import { randomUUID } from "node:crypto";
 import { execFile, spawn } from "node:child_process";
 import { constants as fsConstants, createReadStream, createWriteStream, promises as fs } from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import type { CommandManagedRuntimeRunner } from "./command-managed-runtime.js";
+import type { RunProcessResult } from "./server-utils.js";
+import type { DirectorySnapshot } from "./workspace-restore-merge.js";
+import { mergeDirectoryWithBaseline } from "./workspace-restore-merge.js";
 
 export interface SshConnectionConfig {
   host: string;
@@ -21,7 +26,85 @@ export interface SshCommandResult {
 
 export interface SshRemoteExecutionSpec extends SshConnectionConfig {
   remoteCwd: string;
-  paperclipApiUrl?: string | null;
+}
+
+export function createSshCommandManagedRuntimeRunner(input: {
+  spec: SshRemoteExecutionSpec;
+  defaultCwd?: string | null;
+  maxBufferBytes?: number | null;
+}): CommandManagedRuntimeRunner {
+  const defaultCwd = input.defaultCwd?.trim() || input.spec.remoteCwd;
+  const maxBufferBytes =
+    typeof input.maxBufferBytes === "number" && Number.isFinite(input.maxBufferBytes) && input.maxBufferBytes > 0
+      ? Math.trunc(input.maxBufferBytes)
+      : 1024 * 1024;
+
+  return {
+    execute: async (commandInput): Promise<RunProcessResult> => {
+      const startedAt = new Date().toISOString();
+      const command = commandInput.command.trim();
+      const args = commandInput.args ?? [];
+      const cwd = commandInput.cwd?.trim() || defaultCwd;
+      const envEntries = Object.entries(commandInput.env ?? {})
+        .filter((entry): entry is [string, string] => typeof entry[1] === "string");
+      const envPrefix = envEntries.length > 0
+        ? `env ${envEntries.map(([key, value]) => `${key}=${shellQuote(value)}`).join(" ")} `
+        : "";
+      const exportPrefix = envEntries.length > 0
+        ? envEntries.map(([key, value]) => `export ${key}=${shellQuote(value)};`).join(" ") + " "
+        : "";
+      const commandScript = command === "sh" || command === "bash"
+        ? (args[0] === "-c" || args[0] === "-lc") && typeof args[1] === "string"
+          ? `${exportPrefix}${args[1]}`
+          : `${envPrefix}exec ${[shellQuote(command), ...args.map((arg) => shellQuote(arg))].join(" ")}`
+        : `${envPrefix}exec ${[shellQuote(command), ...args.map((arg) => shellQuote(arg))].join(" ")}`;
+      const remoteCommand = `cd ${shellQuote(cwd)} && ${commandScript}`;
+
+      try {
+        const result = await runSshCommand(input.spec, remoteCommand, {
+          stdin: commandInput.stdin,
+          timeoutMs: commandInput.timeoutMs,
+          maxBuffer: maxBufferBytes,
+        });
+        if (result.stdout) await commandInput.onLog?.("stdout", result.stdout);
+        if (result.stderr) await commandInput.onLog?.("stderr", result.stderr);
+        return {
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          stdout: result.stdout,
+          stderr: result.stderr,
+          pid: null,
+          startedAt,
+        };
+      } catch (error) {
+        const failure = error as {
+          stdout?: unknown;
+          stderr?: unknown;
+          code?: unknown;
+          signal?: unknown;
+          killed?: unknown;
+        };
+        const stdout = typeof failure.stdout === "string" ? failure.stdout : "";
+        const stderr = typeof failure.stderr === "string"
+          ? failure.stderr
+          : error instanceof Error
+            ? error.message
+            : String(error);
+        if (stdout) await commandInput.onLog?.("stdout", stdout);
+        if (stderr) await commandInput.onLog?.("stderr", stderr);
+        return {
+          exitCode: typeof failure.code === "number" ? failure.code : null,
+          signal: typeof failure.signal === "string" ? failure.signal : null,
+          timedOut: failure.killed === true,
+          stdout,
+          stderr,
+          pid: null,
+          startedAt,
+        };
+      }
+    },
+  };
 }
 
 export interface SshEnvLabSupport {
@@ -83,10 +166,6 @@ export function parseSshRemoteExecutionSpec(value: unknown): SshRemoteExecutionS
     port: portValue,
     username,
     remoteCwd,
-    paperclipApiUrl:
-      typeof parsed.paperclipApiUrl === "string" && parsed.paperclipApiUrl.trim().length > 0
-        ? parsed.paperclipApiUrl.trim()
-        : null,
     remoteWorkspacePath:
       typeof parsed.remoteWorkspacePath === "string" && parsed.remoteWorkspacePath.trim().length > 0
         ? parsed.remoteWorkspacePath.trim()
@@ -98,50 +177,6 @@ export function parseSshRemoteExecutionSpec(value: unknown): SshRemoteExecutionS
   };
 }
 
-function normalizeHttpUrlCandidate(value: string): string | null {
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-  try {
-    const parsed = new URL(trimmed);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-      return null;
-    }
-    return parsed.origin;
-  } catch {
-    return null;
-  }
-}
-
-export async function findReachablePaperclipApiUrlOverSsh(input: {
-  config: SshConnectionConfig;
-  candidates: string[];
-  timeoutMs?: number;
-}): Promise<string | null> {
-  const uniqueCandidates = Array.from(
-    new Set(
-      input.candidates
-        .map((candidate) => normalizeHttpUrlCandidate(candidate))
-        .filter((candidate): candidate is string => candidate !== null),
-    ),
-  );
-
-  for (const candidate of uniqueCandidates) {
-    const healthUrl = new URL("/api/health", candidate).toString();
-    try {
-      await runSshCommand(
-        input.config,
-        `sh -lc ${shellQuote(`curl -fsS -m ${Math.max(1, Math.ceil((input.timeoutMs ?? 5_000) / 1000))} ${shellQuote(healthUrl)} >/dev/null`)}`,
-        { timeoutMs: input.timeoutMs ?? 5_000 },
-      );
-      return candidate;
-    } catch {
-      continue;
-    }
-  }
-
-  return null;
-}
-
 async function execFileText(
   file: string,
   args: string[],
@@ -172,6 +207,113 @@ async function execFileText(
   });
 }
 
+async function spawnText(
+  file: string,
+  args: string[],
+  options: {
+    stdin?: string;
+    timeout?: number;
+    maxBuffer?: number;
+  } = {},
+): Promise<SshCommandResult> {
+  return await new Promise<SshCommandResult>((resolve, reject) => {
+    const child = spawn(file, args, {
+      stdio: [options.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+    });
+
+    const maxBuffer = options.maxBuffer ?? 1024 * 128;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+
+    const finishReject = (error: Error & { stdout?: string; stderr?: string; code?: number | null; killed?: boolean }) => {
+      if (settled) return;
+      settled = true;
+      error.stdout = stdout;
+      error.stderr = stderr;
+      error.killed = timedOut;
+      reject(error);
+    };
+
+    const append = (
+      streamName: "stdout" | "stderr",
+      chunk: unknown,
+    ) => {
+      const text = String(chunk);
+      if (streamName === "stdout") {
+        stdout += text;
+      } else {
+        stderr += text;
+      }
+      if (Buffer.byteLength(stdout, "utf8") > maxBuffer || Buffer.byteLength(stderr, "utf8") > maxBuffer) {
+        child.kill("SIGTERM");
+        finishReject(Object.assign(new Error(`Process output exceeded maxBuffer of ${maxBuffer} bytes.`), {
+          code: null,
+        }));
+      }
+    };
+
+    let killEscalation: NodeJS.Timeout | null = null;
+    const timeout = options.timeout && options.timeout > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          child.kill("SIGTERM");
+          // Escalate to SIGKILL after a 5s grace window so a hung remote
+          // command that ignores SIGTERM cannot keep the child alive
+          // indefinitely.
+          killEscalation = setTimeout(() => {
+            try {
+              child.kill("SIGKILL");
+            } catch {
+              // child may have already exited between the SIGTERM and the
+              // escalation — that's fine.
+            }
+          }, 5_000);
+          killEscalation.unref?.();
+        }, options.timeout)
+      : null;
+
+    const clearTimers = () => {
+      if (timeout) clearTimeout(timeout);
+      if (killEscalation) clearTimeout(killEscalation);
+    };
+
+    child.stdout?.on("data", (chunk) => {
+      append("stdout", chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      append("stderr", chunk);
+    });
+
+    child.on("error", (error) => {
+      clearTimers();
+      finishReject(Object.assign(error, { code: null }));
+    });
+
+    child.on("close", (code, signal) => {
+      clearTimers();
+      if (settled) return;
+      settled = true;
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(Object.assign(new Error(stderr.trim() || stdout.trim() || `Process exited with code ${code ?? -1}`), {
+        stdout,
+        stderr,
+        code,
+        signal,
+        killed: timedOut,
+      }));
+    });
+
+    if (options.stdin != null && child.stdin) {
+      child.stdin.end(options.stdin);
+    }
+  });
+}
+
 async function runLocalGit(
   localDir: string,
   args: string[],
@@ -189,7 +331,7 @@ async function commandExists(command: string): Promise<boolean> {
 
 async function resolveCommandPath(command: string): Promise<string | null> {
   try {
-    const result = await execFileText("sh", ["-lc", `command -v ${shellQuote(command)}`], {
+    const result = await execFileText("sh", ["-c", `command -v ${shellQuote(command)}`], {
       timeout: 5_000,
       maxBuffer: 8 * 1024,
     });
@@ -277,7 +419,7 @@ async function runSshScript(
 ): Promise<SshCommandResult> {
   return await runSshCommand(
     config,
-    `sh -lc ${shellQuote(script)}`,
+    script,
     options,
   );
 }
@@ -358,7 +500,7 @@ async function streamLocalFileToSsh(input: {
     "-p",
     String(input.spec.port),
     `${input.spec.username}@${input.spec.host}`,
-    `sh -lc ${shellQuote(input.remoteScript)}`,
+    `sh -c ${shellQuote(input.remoteScript)}`,
   ];
 
   await new Promise<void>((resolve, reject) => {
@@ -407,7 +549,7 @@ async function streamSshToLocalFile(input: {
     "-p",
     String(input.spec.port),
     `${input.spec.username}@${input.spec.host}`,
-    `sh -lc ${shellQuote(input.remoteScript)}`,
+    `sh -c ${shellQuote(input.remoteScript)}`,
   ];
 
   await new Promise<void>((resolve, reject) => {
@@ -455,7 +597,9 @@ async function importGitWorkspaceToSsh(input: {
 }): Promise<void> {
   const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-bundle-"));
   const bundlePath = path.join(bundleDir, "workspace.bundle");
-  const tempRef = "refs/paperclip/ssh-sync/import";
+  // Per-import unique ref so concurrent imports against the same local repo
+  // can't race on `update-ref` between this run's update and bundle create.
+  const tempRef = `refs/paperclip/ssh-sync/import/${randomUUID()}`;
 
   try {
     await runLocalGit(input.localDir, ["update-ref", tempRef, input.snapshot.headCommit], {
@@ -480,6 +624,8 @@ async function importGitWorkspaceToSsh(input: {
         : `git -C ${shellQuote(input.remoteDir)} -c advice.detachedHead=false checkout --force --detach ${shellQuote(input.snapshot.headCommit)} >/dev/null`,
       `git -C ${shellQuote(input.remoteDir)} reset --hard ${shellQuote(input.snapshot.headCommit)} >/dev/null`,
       `git -C ${shellQuote(input.remoteDir)} clean -fdx -e .paperclip-runtime >/dev/null`,
+      // Drop the per-import ref on the remote side too so it can't accumulate.
+      `git -C ${shellQuote(input.remoteDir)} update-ref -d ${shellQuote(tempRef)} >/dev/null 2>&1 || true`,
     ].join("\n");
 
     await streamLocalFileToSsh({
@@ -500,10 +646,12 @@ async function exportGitWorkspaceFromSsh(input: {
   spec: SshRemoteExecutionSpec;
   remoteDir: string;
   localDir: string;
-}): Promise<void> {
+  importedRef?: string;
+  resetLocalWorkspace?: boolean;
+}): Promise<string> {
   const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-bundle-"));
   const bundlePath = path.join(bundleDir, "workspace.bundle");
-  const importedRef = "refs/paperclip/ssh-sync/imported";
+  const importedRef = input.importedRef ?? `refs/paperclip/ssh-sync/imported/${randomUUID()}`;
 
   try {
     const exportScript = [
@@ -527,19 +675,97 @@ async function exportGitWorkspaceFromSsh(input: {
       timeout: 60_000,
       maxBuffer: 1024 * 1024,
     });
-    await runLocalGit(input.localDir, ["reset", "--hard", importedRef], {
-      timeout: 60_000,
-      maxBuffer: 1024 * 1024,
-    });
-  } finally {
-    await runLocalGit(input.localDir, ["update-ref", "-d", importedRef], {
+    if (input.resetLocalWorkspace !== false) {
+      await runLocalGit(input.localDir, ["reset", "--hard", importedRef], {
+        timeout: 60_000,
+        maxBuffer: 1024 * 1024,
+      });
+    }
+    const importedHead = await runLocalGit(input.localDir, ["rev-parse", importedRef], {
       timeout: 10_000,
       maxBuffer: 16 * 1024,
-    }).catch(() => undefined);
+    });
+    return importedHead.stdout.trim();
+  } finally {
+    if (input.resetLocalWorkspace !== false) {
+      await runLocalGit(input.localDir, ["update-ref", "-d", importedRef], {
+        timeout: 10_000,
+        maxBuffer: 16 * 1024,
+      }).catch(() => undefined);
+    }
     await fs.rm(bundleDir, { recursive: true, force: true }).catch(() => undefined);
   }
 }
 
+async function integrateImportedGitHead(input: {
+  localDir: string;
+  importedHead: string;
+}): Promise<void> {
+  const snapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
+  if (!snapshot) return;
+
+  const currentHead = snapshot.headCommit;
+  if (!currentHead || currentHead === input.importedHead) return;
+
+  const headRef = snapshot.branchName ? `refs/heads/${snapshot.branchName}` : "HEAD";
+  const mergeBase = await runLocalGit(input.localDir, ["merge-base", currentHead, input.importedHead], {
+    timeout: 10_000,
+    maxBuffer: 16 * 1024,
+  }).catch(() => null);
+  const mergeBaseHead = mergeBase?.stdout.trim() ?? "";
+
+  if (mergeBaseHead === input.importedHead) {
+    return;
+  }
+
+  if (mergeBaseHead === currentHead) {
+    await runLocalGit(input.localDir, ["update-ref", headRef, input.importedHead, currentHead], {
+      timeout: 10_000,
+      maxBuffer: 16 * 1024,
+    });
+    return;
+  }
+
+  let mergedTree;
+  try {
+    mergedTree = await runLocalGit(input.localDir, ["merge-tree", "--write-tree", currentHead, input.importedHead], {
+      timeout: 60_000,
+      maxBuffer: 256 * 1024,
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to merge concurrent SSH git histories for ${currentHead.slice(0, 12)} and ${input.importedHead.slice(0, 12)}: ${reason}`,
+    );
+  }
+  const mergedTreeId = mergedTree.stdout.trim().split("\n")[0]?.trim() ?? "";
+  if (!mergedTreeId) {
+    throw new Error("Failed to compute a merged git tree for SSH workspace restore.");
+  }
+
+  const mergeCommit = await runLocalGit(
+    input.localDir,
+    [
+      "commit-tree",
+      mergedTreeId,
+      "-p",
+      currentHead,
+      "-p",
+      input.importedHead,
+      "-m",
+      `Paperclip SSH sync merge ${input.importedHead.slice(0, 12)}`,
+    ],
+    {
+      timeout: 60_000,
+      maxBuffer: 64 * 1024,
+    },
+  );
+  await runLocalGit(input.localDir, ["update-ref", headRef, mergeCommit.stdout.trim(), currentHead], {
+    timeout: 10_000,
+    maxBuffer: 16 * 1024,
+  });
+}
+
 async function clearRemoteDirectory(input: {
   spec: SshConnectionConfig;
   remoteDir: string;
@@ -661,6 +887,13 @@ async function isSshEnvLabFixtureProcess(state: Pick<SshEnvLabFixtureState, "pid
 }
 
 export async function getSshEnvLabSupport(): Promise<SshEnvLabSupport> {
+  if (process.platform === "darwin" && process.env.PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB !== "1") {
+    return {
+      supported: false,
+      reason: "SSH env-lab fixture is disabled on macOS; set PAPERCLIP_ENABLE_DARWIN_SSH_ENV_LAB=1 to opt in.",
+    };
+  }
+
   for (const command of ["ssh", "sshd", "ssh-keygen"]) {
     if (!(await commandExists(command))) {
       return {
@@ -688,6 +921,8 @@ export async function runSshCommand(
   config: SshConnectionConfig,
   remoteCommand: string,
   options: {
+    env?: Record<string, string>;
+    stdin?: string;
     timeoutMs?: number;
     maxBuffer?: number;
   } = {},
@@ -697,18 +932,45 @@ export async function runSshCommand(
     const auth = await createSshAuthArgs(config);
     cleanup = auth.cleanup;
     const sshArgs = [...auth.args];
+    const envEntries = Object.entries(options.env ?? {})
+      .filter((entry): entry is [string, string] => typeof entry[1] === "string");
+    for (const [key] of envEntries) {
+      if (!isValidShellEnvKey(key)) {
+        throw new Error(`Invalid SSH environment variable key: ${key}`);
+      }
+    }
+
+    // Mirror buildSshSpawnTarget: source login profiles first, then run
+    // `env KEY=VAL cmd` so user-supplied identity overrides win over anything
+    // a profile re-exports. Without this, a remote profile that resets HOME
+    // / NVM_DIR / etc. would silently undo the explicit env passed in here.
+    const envArgs = envEntries.map(([key, value]) => `${key}=${shellQuote(value)}`);
+    const remoteScript = [
+      'if [ -f "$HOME/.profile" ]; then . "$HOME/.profile" >/dev/null 2>&1 || true; fi',
+      'if [ -f "$HOME/.bash_profile" ]; then . "$HOME/.bash_profile" >/dev/null 2>&1 || true; fi',
+      'if [ -f "$HOME/.zprofile" ]; then . "$HOME/.zprofile" >/dev/null 2>&1 || true; fi',
+      envArgs.length > 0
+        ? `exec env ${envArgs.join(" ")} sh -c ${shellQuote(remoteCommand)}`
+        : `exec sh -c ${shellQuote(remoteCommand)}`,
+    ].join(" && ");
 
     sshArgs.push(
       "-p",
       String(config.port),
       `${config.username}@${config.host}`,
-      remoteCommand,
+      `sh -c ${shellQuote(remoteScript)}`,
     );
 
-    return await execFileText("ssh", sshArgs, {
-      timeout: options.timeoutMs ?? 15_000,
-      maxBuffer: options.maxBuffer ?? 1024 * 128,
-    });
+    return options.stdin != null
+      ? await spawnText("ssh", sshArgs, {
+          stdin: options.stdin,
+          timeout: options.timeoutMs ?? 15_000,
+          maxBuffer: options.maxBuffer ?? 1024 * 128,
+        })
+      : await execFileText("ssh", sshArgs, {
+          timeout: options.timeoutMs ?? 15_000,
+          maxBuffer: options.maxBuffer ?? 1024 * 128,
+        });
   } finally {
     await cleanup();
   }
@@ -751,7 +1013,7 @@ export async function buildSshSpawnTarget(input: {
     "-p",
     String(input.spec.port),
     `${input.spec.username}@${input.spec.host}`,
-    `sh -lc ${shellQuote(remoteScript)}`,
+    `sh -c ${shellQuote(remoteScript)}`,
   );
 
   return {
@@ -774,7 +1036,7 @@ export async function syncDirectoryToSsh(input: {
     "-p",
     String(input.spec.port),
     `${input.spec.username}@${input.spec.host}`,
-    `sh -lc ${shellQuote(`mkdir -p ${shellQuote(input.remoteDir)} && tar -xf - -C ${shellQuote(input.remoteDir)}`)}`,
+    `sh -c ${shellQuote(`mkdir -p ${shellQuote(input.remoteDir)} && tar -xf - -C ${shellQuote(input.remoteDir)}`)}`,
   ];
 
   await new Promise<void>((resolve, reject) => {
@@ -870,7 +1132,7 @@ export async function syncDirectoryFromSsh(input: {
     "-p",
     String(input.spec.port),
     `${input.spec.username}@${input.spec.host}`,
-    `sh -lc ${shellQuote(remoteTarScript)}`,
+    `sh -c ${shellQuote(remoteTarScript)}`,
   ];
 
   try {
@@ -947,7 +1209,7 @@ export async function prepareWorkspaceForSshExecution(input: {
   spec: SshRemoteExecutionSpec;
   localDir: string;
   remoteDir?: string;
-}): Promise<void> {
+}): Promise<{ gitBacked: boolean }> {
   const remoteDir = input.remoteDir ?? input.spec.remoteCwd;
   const gitSnapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
 
@@ -969,7 +1231,7 @@ export async function prepareWorkspaceForSshExecution(input: {
       remoteDir,
       deletedPaths: gitSnapshot.deletedPaths,
     });
-    return;
+    return { gitBacked: true };
   }
 
   await clearRemoteDirectory({
@@ -983,14 +1245,64 @@ export async function prepareWorkspaceForSshExecution(input: {
     remoteDir,
     exclude: [".paperclip-runtime"],
   });
+  return { gitBacked: false };
 }
 
 export async function restoreWorkspaceFromSshExecution(input: {
   spec: SshRemoteExecutionSpec;
   localDir: string;
   remoteDir?: string;
+  baselineSnapshot?: DirectorySnapshot;
+  restoreGitHistory?: boolean;
 }): Promise<void> {
   const remoteDir = input.remoteDir ?? input.spec.remoteCwd;
+  if (input.baselineSnapshot) {
+    const stagingDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-sync-back-"));
+    const importedRef = input.restoreGitHistory
+      ? `refs/paperclip/ssh-sync/imported/${randomUUID()}`
+      : null;
+    try {
+      const importedHead = input.restoreGitHistory
+        ? await exportGitWorkspaceFromSsh({
+          spec: input.spec,
+          remoteDir,
+          localDir: input.localDir,
+          importedRef: importedRef ?? undefined,
+          resetLocalWorkspace: false,
+        })
+        : null;
+      await syncDirectoryFromSsh({
+        spec: input.spec,
+        remoteDir,
+        localDir: stagingDir,
+        exclude: input.baselineSnapshot.exclude,
+      });
+      await mergeDirectoryWithBaseline({
+        baseline: input.baselineSnapshot,
+        sourceDir: stagingDir,
+        targetDir: input.localDir,
+        // Git history advances via integrateImportedGitHead; the working tree
+        // still comes from the remote file snapshot so dirty remote edits win.
+        beforeApply: importedHead
+          ? async () => {
+            await integrateImportedGitHead({
+              localDir: input.localDir,
+              importedHead,
+            });
+          }
+          : undefined,
+      });
+    } finally {
+      if (importedRef) {
+        await runLocalGit(input.localDir, ["update-ref", "-d", importedRef], {
+          timeout: 10_000,
+          maxBuffer: 16 * 1024,
+        }).catch(() => undefined);
+      }
+      await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+    return;
+  }
   const gitSnapshot = await readLocalGitWorkspaceSnapshot(input.localDir);
 
   if (gitSnapshot) {
@@ -1022,7 +1334,7 @@ export async function ensureSshWorkspaceReady(
 ): Promise<{ remoteCwd: string }> {
   const result = await runSshCommand(
     config,
-    `sh -lc ${shellQuote(`mkdir -p ${shellQuote(config.remoteWorkspacePath)} && cd ${shellQuote(config.remoteWorkspacePath)} && pwd`)}`,
+    `mkdir -p ${shellQuote(config.remoteWorkspacePath)} && cd ${shellQuote(config.remoteWorkspacePath)} && pwd`,
   );
   return {
     remoteCwd: result.stdout.trim(),

packages/adapter-utils/src/types.ts

@@ -125,6 +125,7 @@ export interface AdapterExecutionContext {
   runtime: AdapterRuntime;
   config: Record<string, unknown>;
   context: Record<string, unknown>;
+  runtimeCommandSpec?: AdapterRuntimeCommandSpec | null;
   executionTarget?: AdapterExecutionTarget | null;
   /**
    * Legacy remote transport view. Prefer `executionTarget`, which is the
@@ -328,6 +329,23 @@ export interface AdapterConfigSchema {
   fields: ConfigFieldSchema[];
 }
 
+export interface AdapterRuntimeCommandSpec {
+  /**
+   * The command Paperclip should execute for this adapter in the current config.
+   */
+  command: string;
+  /**
+   * Optional command name/path to probe for availability before launch.
+   * Defaults to `command` when omitted by the consumer.
+   */
+  detectCommand?: string | null;
+  /**
+   * Optional shell snippet that can install or expose the adapter command in a
+   * fresh remote runtime. It should be idempotent.
+   */
+  installCommand?: string | null;
+}
+
 export interface ServerAdapterModule {
   type: string;
   execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
@@ -406,6 +424,11 @@ export interface ServerAdapterModule {
    * rather than reading config.paperclipRuntimeSkills.
    */
   requiresMaterializedRuntimeSkills?: boolean;
+  /**
+   * Optional: describe how this adapter's runtime command should be launched
+   * and provisioned in fresh remote environments such as sandboxes.
+   */
+  getRuntimeCommandSpec?: (config: Record<string, unknown>) => AdapterRuntimeCommandSpec | null;
 }
 
 // ---------------------------------------------------------------------------

packages/adapter-utils/src/workspace-restore-merge.test.ts

@@ -0,0 +1,61 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { captureDirectorySnapshot, mergeDirectoryWithBaseline } from "./workspace-restore-merge.js";
+
+describe("workspace restore merge", () => {
+  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 sibling files when sequential stale-baseline restores create the same nested directory tree", async () => {
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-restore-merge-"));
+    cleanupDirs.push(rootDir);
+
+    const targetDir = path.join(rootDir, "target");
+    const sourceADir = path.join(rootDir, "source-a");
+    const sourceBDir = path.join(rootDir, "source-b");
+    await mkdir(targetDir, { recursive: true });
+    await mkdir(path.join(sourceADir, "manual-qa", "environment-matrix", "ssh"), { recursive: true });
+    await mkdir(path.join(sourceBDir, "manual-qa", "environment-matrix", "ssh"), { recursive: true });
+
+    const baseline = await captureDirectorySnapshot(targetDir, { exclude: [] });
+
+    await writeFile(
+      path.join(sourceADir, "manual-qa", "environment-matrix", "ssh", "claude_local.md"),
+      "ssh claude\n",
+      "utf8",
+    );
+    await writeFile(
+      path.join(sourceBDir, "manual-qa", "environment-matrix", "ssh", "codex_local.md"),
+      "ssh codex\n",
+      "utf8",
+    );
+
+    await mergeDirectoryWithBaseline({
+      baseline,
+      sourceDir: sourceADir,
+      targetDir,
+    });
+    await mergeDirectoryWithBaseline({
+      baseline,
+      sourceDir: sourceBDir,
+      targetDir,
+    });
+
+    await expect(
+      readFile(path.join(targetDir, "manual-qa", "environment-matrix", "ssh", "claude_local.md"), "utf8"),
+    ).resolves.toBe("ssh claude\n");
+    await expect(
+      readFile(path.join(targetDir, "manual-qa", "environment-matrix", "ssh", "codex_local.md"), "utf8"),
+    ).resolves.toBe("ssh codex\n");
+  });
+});

packages/adapter-utils/src/workspace-restore-merge.ts

@@ -0,0 +1,257 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+
+type SnapshotEntry =
+  | { kind: "dir" }
+  | { kind: "file"; mode: number; hash: string }
+  | { kind: "symlink"; target: string };
+
+export interface DirectorySnapshot {
+  exclude: string[];
+  entries: Map<string, SnapshotEntry>;
+}
+
+function isRelativePathOrDescendant(relative: string, candidate: string): boolean {
+  return relative === candidate || relative.startsWith(`${candidate}/`);
+}
+
+function shouldExclude(relative: string, exclude: readonly string[]): boolean {
+  return exclude.some((candidate) => isRelativePathOrDescendant(relative, candidate));
+}
+
+async function hashFile(filePath: string): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+async function walkDirectory(
+  root: string,
+  exclude: readonly string[],
+  relative = "",
+  out: Map<string, SnapshotEntry> = new Map(),
+): Promise<Map<string, SnapshotEntry>> {
+  const current = relative ? path.join(root, relative) : root;
+  const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    const nextRelative = relative ? path.posix.join(relative, entry.name) : entry.name;
+    if (shouldExclude(nextRelative, exclude)) continue;
+
+    const fullPath = path.join(root, nextRelative);
+    const stats = await fs.lstat(fullPath);
+    if (stats.isDirectory()) {
+      out.set(nextRelative, { kind: "dir" });
+      await walkDirectory(root, exclude, nextRelative, out);
+      continue;
+    }
+
+    if (stats.isSymbolicLink()) {
+      out.set(nextRelative, {
+        kind: "symlink",
+        target: await fs.readlink(fullPath),
+      });
+      continue;
+    }
+
+    out.set(nextRelative, {
+      kind: "file",
+      mode: stats.mode,
+      hash: await hashFile(fullPath),
+    });
+  }
+
+  return out;
+}
+
+async function readSnapshotEntry(root: string, relative: string): Promise<SnapshotEntry | null> {
+  const fullPath = path.join(root, relative);
+  let stats;
+  try {
+    stats = await fs.lstat(fullPath);
+  } catch {
+    return null;
+  }
+
+  if (stats.isDirectory()) return { kind: "dir" };
+  if (stats.isSymbolicLink()) {
+    return {
+      kind: "symlink",
+      target: await fs.readlink(fullPath),
+    };
+  }
+  return {
+    kind: "file",
+    mode: stats.mode,
+    hash: await hashFile(fullPath),
+  };
+}
+
+function entriesMatch(left: SnapshotEntry | null | undefined, right: SnapshotEntry | null | undefined): boolean {
+  if (!left || !right) return false;
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "dir") return true;
+  if (left.kind === "symlink" && right.kind === "symlink") {
+    return left.target === right.target;
+  }
+  if (left.kind === "file" && right.kind === "file") {
+    return left.mode === right.mode && left.hash === right.hash;
+  }
+  return false;
+}
+
+async function isHolderAlive(lockDir: string): Promise<boolean> {
+  try {
+    const raw = await fs.readFile(path.join(lockDir, "owner.json"), "utf8");
+    const owner = JSON.parse(raw) as { pid?: unknown };
+    const pid = typeof owner.pid === "number" && Number.isFinite(owner.pid) && owner.pid > 0 ? owner.pid : null;
+    if (pid === null) {
+      // Owner record is unparseable / missing pid — treat as stale.
+      return false;
+    }
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  } catch {
+    // owner.json missing or unreadable — treat as stale.
+    return false;
+  }
+}
+
+async function acquireDirectoryMergeLock(lockDir: string): Promise<() => Promise<void>> {
+  const deadline = Date.now() + 30_000;
+  while (true) {
+    try {
+      await fs.mkdir(lockDir);
+      await fs.writeFile(
+        path.join(lockDir, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+        "utf8",
+      );
+      return async () => {
+        await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+      };
+    } catch (error) {
+      const code = error && typeof error === "object" ? (error as { code?: unknown }).code : null;
+      if (code !== "EEXIST") throw error;
+      // Stale-lock detection: if the owner PID is dead (SIGKILL / OOM / crash),
+      // the lockDir would otherwise persist forever and stall restores. Mirror
+      // the materializePaperclipSkillCopy lock pattern — remove and retry.
+      if (!(await isHolderAlive(lockDir))) {
+        await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(`Timed out waiting for workspace restore lock at ${lockDir}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+}
+
+export async function withDirectoryMergeLock<T>(
+  targetDir: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const releaseLock = await acquireDirectoryMergeLock(`${targetDir}.paperclip-restore.lock`);
+  try {
+    return await fn();
+  } finally {
+    await releaseLock();
+  }
+}
+
+async function copySnapshotEntry(sourceDir: string, targetDir: string, relative: string, entry: SnapshotEntry): Promise<void> {
+  const sourcePath = path.join(sourceDir, relative);
+  const targetPath = path.join(targetDir, relative);
+
+  if (entry.kind === "dir") {
+    const existing = await fs.lstat(targetPath).catch(() => null);
+    if (existing?.isDirectory()) {
+      return;
+    }
+    if (existing) {
+      await fs.rm(targetPath, { recursive: true, force: true }).catch(() => undefined);
+    }
+    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 (entry.kind === "symlink") {
+    await fs.symlink(entry.target, targetPath);
+    return;
+  }
+
+  await fs.copyFile(sourcePath, targetPath, fsConstants.COPYFILE_FICLONE).catch(async () => {
+    await fs.copyFile(sourcePath, targetPath);
+  });
+  await fs.chmod(targetPath, entry.mode);
+}
+
+export async function captureDirectorySnapshot(
+  rootDir: string,
+  options: { exclude?: string[] } = {},
+): Promise<DirectorySnapshot> {
+  const exclude = [...new Set(options.exclude ?? [])];
+  return {
+    exclude,
+    entries: await walkDirectory(rootDir, exclude),
+  };
+}
+
+export async function mergeDirectoryWithBaseline(input: {
+  baseline: DirectorySnapshot;
+  sourceDir: string;
+  targetDir: string;
+  beforeApply?: () => Promise<void>;
+}): Promise<void> {
+  const source = await captureDirectorySnapshot(input.sourceDir, { exclude: input.baseline.exclude });
+  await withDirectoryMergeLock(input.targetDir, async () => {
+    await input.beforeApply?.();
+    const current = await captureDirectorySnapshot(input.targetDir, { exclude: input.baseline.exclude });
+    const deletedLeafEntries = [...input.baseline.entries.entries()]
+      .filter(([relative, entry]) => entry.kind !== "dir" && !source.entries.has(relative))
+      .sort(([left], [right]) => right.length - left.length);
+
+    for (const [relative, baselineEntry] of deletedLeafEntries) {
+      if (!entriesMatch(current.entries.get(relative), baselineEntry)) continue;
+      await fs.rm(path.join(input.targetDir, relative), { recursive: true, force: true }).catch(() => undefined);
+    }
+
+    const deletedDirs = [...input.baseline.entries.entries()]
+      .filter(([relative, entry]) => entry.kind === "dir" && !source.entries.has(relative))
+      .sort(([left], [right]) => right.length - left.length);
+
+    for (const [relative] of deletedDirs) {
+      await fs.rmdir(path.join(input.targetDir, relative)).catch(() => undefined);
+    }
+
+    const changedSourceEntries = [...source.entries.entries()]
+      .filter(([relative, entry]) => !entriesMatch(input.baseline.entries.get(relative), entry))
+      .sort(([left], [right]) => left.localeCompare(right));
+
+    for (const [relative, entry] of changedSourceEntries) {
+      await copySnapshotEntry(input.sourceDir, input.targetDir, relative, entry);
+    }
+  });
+}
+
+export async function directoryEntryMatchesBaseline(
+  rootDir: string,
+  relative: string,
+  baselineEntry: SnapshotEntry,
+): Promise<boolean> {
+  return entriesMatch(await readSnapshotEntry(rootDir, relative), baselineEntry);
+}

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

@@ -1,3 +1,5 @@
+import type { AdapterModel } from "@paperclipai/adapter-utils";
+
 export const type = "acpx_local";
 export const label = "ACPX (local)";
 
@@ -6,6 +8,7 @@ export const DEFAULT_ACPX_LOCAL_MODE = "persistent";
 export const DEFAULT_ACPX_LOCAL_PERMISSION_MODE = "approve-all";
 export const DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS = "deny";
 export const DEFAULT_ACPX_LOCAL_TIMEOUT_SEC = 0;
+export const DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS = 0;
 
 export const acpxAgentOptions = [
   { id: "claude", label: "Claude via ACPX" },
@@ -13,6 +16,8 @@ export const acpxAgentOptions = [
   { id: "custom", label: "Custom ACP command" },
 ] as const;
 
+export const models: AdapterModel[] = [];
+
 export const agentConfigurationDoc = `# acpx_local agent configuration
 
 Adapter: acpx_local
@@ -30,7 +35,7 @@ Don't use when:
 Core fields:
 - agent (string, optional): claude, codex, or custom. Defaults to claude.
 - agentCommand (string, optional): custom ACP command when agent=custom, or an override for a built-in ACP agent command.
-- mode (string, optional): persistent or oneshot. Defaults to persistent.
+- mode (string, optional): persistent or oneshot. Defaults to persistent. Paperclip keeps session state persistent and may close the live process between runs.
 - cwd (string, optional): default absolute working directory fallback for the agent process.
 - permissionMode (string, optional): defaults to approve-all, meaning ACPX permission requests are auto-approved.
 - nonInteractivePermissions (string, optional): fallback behavior when ACPX cannot ask interactively. Supported values are deny and fail.
@@ -38,7 +43,11 @@ Core fields:
 - instructionsFilePath (string, optional): absolute path to a markdown instructions file used by Paperclip prompt construction.
 - promptTemplate (string, optional): run prompt template.
 - bootstrapPromptTemplate (string, optional): first-run bootstrap prompt template.
+- model (string, optional): requested ACP model. Claude and Codex ACP agents both receive this through ACP session config.
+- effort/modelReasoningEffort (string, optional): requested thinking effort. Claude uses effort; Codex uses modelReasoningEffort/reasoning_effort.
+- fastMode (boolean, optional): for ACPX Codex, request Codex fast mode through ACP session config.
 - timeoutSec (number, optional): run timeout in seconds. Defaults to 0, meaning no adapter timeout.
+- warmHandleIdleMs (number, optional): live ACPX process idle window after a successful persistent run. Defaults to 0, meaning Paperclip shuts the process down after each run while retaining ACPX session state.
 - env (object, optional): KEY=VALUE environment variables or secret bindings.
 
 Dependency decision:

packages/adapters/acpx-local/src/server/config-schema.ts

@@ -1,10 +1,9 @@
 import type { AdapterConfigSchema } from "@paperclipai/adapter-utils";
 import {
   DEFAULT_ACPX_LOCAL_AGENT,
-  DEFAULT_ACPX_LOCAL_MODE,
   DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
-  DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
   DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+  DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS,
   acpxAgentOptions,
 } from "../index.js";
 
@@ -26,27 +25,6 @@ export function getConfigSchema(): AdapterConfigSchema {
         type: "text",
         hint: "Required for custom agents; optional override for built-in Claude or Codex ACP commands.",
       },
-      {
-        key: "mode",
-        label: "Session mode",
-        type: "select",
-        default: DEFAULT_ACPX_LOCAL_MODE,
-        options: [
-          { value: "persistent", label: "Persistent" },
-          { value: "oneshot", label: "One shot" },
-        ],
-      },
-      {
-        key: "permissionMode",
-        label: "Permission mode",
-        type: "select",
-        default: DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
-        options: [
-          { value: "approve-all", label: "Approve all" },
-          { value: "default", label: "Approve reads" },
-        ],
-        hint: "Defaults to maximum permissions. Approve reads grants read-only requests and asks for approval on writes.",
-      },
       {
         key: "nonInteractivePermissions",
         label: "Non-interactive permissions",
@@ -56,6 +34,7 @@ export function getConfigSchema(): AdapterConfigSchema {
           { value: "deny", label: "Deny" },
           { value: "fail", label: "Fail" },
         ],
+        hint: "Fallback if the ACP agent asks for input outside an interactive session. Paperclip still auto-approves permissions by default.",
       },
       {
         key: "cwd",
@@ -70,20 +49,12 @@ export function getConfigSchema(): AdapterConfigSchema {
         hint: "Optional ACPX session state directory. Defaults to Paperclip-managed company/agent scoped storage.",
       },
       {
-        key: "instructionsFilePath",
-        label: "Instructions file",
-        type: "text",
-        hint: "Optional absolute path to markdown instructions injected into the run prompt.",
-      },
-      {
-        key: "promptTemplate",
-        label: "Prompt template",
-        type: "textarea",
-      },
-      {
-        key: "bootstrapPromptTemplate",
-        label: "Bootstrap prompt template",
-        type: "textarea",
+        key: "fastMode",
+        label: "Codex fast mode",
+        type: "toggle",
+        default: false,
+        hint: "Only applies when ACP agent is Codex. Requests Codex Fast mode through ACP session config.",
+        meta: { visibleWhen: { key: "agent", values: ["codex"] } },
       },
       {
         key: "timeoutSec",
@@ -91,6 +62,13 @@ export function getConfigSchema(): AdapterConfigSchema {
         type: "number",
         default: DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
       },
+      {
+        key: "warmHandleIdleMs",
+        label: "Warm process idle ms",
+        type: "number",
+        default: DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS,
+        hint: "Defaults to 0, which closes the ACPX process after each run while retaining persistent session state.",
+      },
       {
         key: "env",
         label: "Environment JSON",

packages/adapters/acpx-local/src/server/execute.test.ts

@@ -56,7 +56,13 @@ function buildRuntime() {
   };
 }
 
-async function runExecutor(config: Record<string, unknown>) {
+async function runExecutor(
+  config: Record<string, unknown>,
+  options: {
+    context?: Record<string, unknown>;
+    executionTransport?: Record<string, unknown>;
+  } = {},
+) {
   const runtimeOptions: Record<string, unknown>[] = [];
   const meta: Record<string, unknown>[] = [];
   const logs: Array<{ stream: string; text: string }> = [];
@@ -73,12 +79,13 @@ async function runExecutor(config: Record<string, unknown>) {
       id: "agent-1",
       companyId: "company-1",
     },
-    runtime: {},
-    config,
-    context: {},
-    onLog: async (stream: "stdout" | "stderr", text: string) => {
-      logs.push({ stream, text });
-    },
+      runtime: {},
+      config,
+      context: options.context ?? {},
+      executionTransport: options.executionTransport,
+      onLog: async (stream: "stdout" | "stderr", text: string) => {
+        logs.push({ stream, text });
+      },
     onMeta: async (payload: unknown) => {
       meta.push(payload as Record<string, unknown>);
     },
@@ -257,6 +264,57 @@ describe("acpx_local runtime skill isolation", () => {
     expect(env).not.toContain("old-key");
   });
 
+  it("shapes ACPX wrapper workspace env for remote execution identities", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+    const workspaceDir = path.join(root, "workspace");
+    await fs.mkdir(workspaceDir, { recursive: true });
+
+    await runExecutor(
+      {
+        agentCommand: "node ./fake-acp.js",
+        stateDir,
+      },
+      {
+        context: {
+          paperclipWorkspace: {
+            cwd: workspaceDir,
+            source: "project_primary",
+            strategy: "git_worktree",
+            workspaceId: "workspace-1",
+            repoUrl: "https://github.com/paperclipai/paperclip.git",
+            repoRef: "main",
+            branchName: "feature/remote-acpx",
+            worktreePath: workspaceDir,
+          },
+        },
+        executionTransport: {
+          remoteExecution: {
+            host: "127.0.0.1",
+            port: 2222,
+            username: "fixture",
+            remoteWorkspacePath: "/remote/workspace",
+            remoteCwd: "/remote/workspace",
+            privateKey: "PRIVATE KEY",
+            knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
+            strictHostKeyChecking: true,
+          },
+        },
+      },
+    );
+
+    const wrappers = await fs.readdir(path.join(stateDir, "wrappers"));
+    const envPath = path.join(
+      stateDir,
+      "wrappers",
+      wrappers.find((name) => name.endsWith(".env"))!,
+    );
+    const env = await fs.readFile(envPath, "utf8");
+
+    expect(env).toContain("PAPERCLIP_WORKSPACE_CWD='/remote/workspace'");
+    expect(env).not.toContain("PAPERCLIP_WORKSPACE_WORKTREE_PATH=");
+  });
+
   it("cleans aged credential wrapper scripts across ACPX agent changes", async () => {
     const root = await makeTempRoot();
     const stateDir = path.join(root, "state");

packages/adapters/acpx-local/src/server/execute.ts

@@ -18,9 +18,13 @@ import {
   materializePaperclipSkillCopy,
   parseObject,
   readPaperclipRuntimeSkillEntries,
+  readPaperclipIssueWorkModeFromContext,
   renderPaperclipWakePrompt,
   renderTemplate,
+  resolvePaperclipInstanceRootForAdapter,
   resolvePaperclipDesiredSkillNames,
+  rewriteWorkspaceCwdEnvVarsForExecution,
+  shapePaperclipWorkspaceEnvForExecution,
   stringifyPaperclipWakePayload,
   type PaperclipSkillEntry,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -44,10 +48,10 @@ import {
   DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
   DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
   DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+  DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS,
 } from "../index.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const DEFAULT_WARM_HANDLE_IDLE_MS = 15 * 60 * 1000;
 const WRAPPER_CLEANUP_RETENTION_MS = 15 * 60 * 1000;
 const PAPERCLIP_MANAGED_CODEX_SKILLS_MANIFEST = ".paperclip-managed-skills.json";
 
@@ -58,6 +62,7 @@ interface RuntimeCacheEntry {
   handle: AcpRuntimeHandle;
   fingerprint: string;
   lastUsedAt: number;
+  cleanupTimer?: NodeJS.Timeout;
 }
 
 interface ExecuteDeps {
@@ -78,6 +83,9 @@ interface AcpxPreparedRuntime {
   stateDir: string;
   permissionMode: "approve-all" | "approve-reads" | "deny-all";
   nonInteractivePermissions: "deny" | "fail";
+  requestedModel: string;
+  requestedThinkingEffort: string;
+  fastMode: boolean;
   timeoutSec: number;
   sessionKey: string;
   fingerprint: string;
@@ -108,7 +116,10 @@ function shortHash(value: unknown): string {
 function defaultPaperclipInstanceDir(): string {
   const home = process.env.PAPERCLIP_HOME?.trim() || path.join(os.homedir(), ".paperclip");
   const instanceId = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
-  return path.join(home, "instances", instanceId);
+  return resolvePaperclipInstanceRootForAdapter({
+    homeDir: home,
+    instanceId,
+  });
 }
 
 function defaultStateDir(companyId: string, agentId: string): string {
@@ -503,6 +514,15 @@ function normalizeNonInteractivePermissions(config: Record<string, unknown>): "d
     : "deny";
 }
 
+function normalizeRequestedThinkingEffort(config: Record<string, unknown>): string {
+  return (
+    asString(config.modelReasoningEffort, "") ||
+    asString(config.reasoningEffort, "") ||
+    asString(config.thinkingEffort, "") ||
+    asString(config.effort, "")
+  ).trim();
+}
+
 function isCompatibleSession(
   params: Record<string, unknown>,
   runtime: Pick<AcpxPreparedRuntime, "fingerprint" | "sessionKey" | "cwd" | "mode" | "acpxAgent" | "remoteExecutionIdentity">,
@@ -533,6 +553,9 @@ function buildSessionParams(input: {
     mode: prepared.mode,
     stateDir: prepared.stateDir,
     configFingerprint: prepared.fingerprint,
+    ...(prepared.requestedModel ? { model: prepared.requestedModel } : {}),
+    ...(prepared.requestedThinkingEffort ? { thinkingEffort: prepared.requestedThinkingEffort } : {}),
+    ...(prepared.fastMode ? { fastMode: true } : {}),
     skills: prepared.skillsIdentity,
     ...(prepared.workspaceId ? { workspaceId: prepared.workspaceId } : {}),
     ...(prepared.workspaceRepoUrl ? { repoUrl: prepared.workspaceRepoUrl } : {}),
@@ -622,12 +645,31 @@ async function buildRuntime(input: {
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+  const executionTarget = readAdapterExecutionTarget({
+    executionTarget: input.ctx.executionTarget,
+    legacyRemoteExecution: input.ctx.executionTransport?.remoteExecution,
+  });
+  const remoteExecutionIdentity = adapterExecutionTargetSessionIdentity(executionTarget);
+  const effectiveExecutionCwd =
+    remoteExecutionIdentity && typeof remoteExecutionIdentity.remoteCwd === "string"
+      ? remoteExecutionIdentity.remoteCwd
+      : cwd;
+  const executionTargetIsRemote = remoteExecutionIdentity !== null;
+  const shapedWorkspaceEnv = shapePaperclipWorkspaceEnvForExecution({
+    workspaceCwd: effectiveWorkspaceCwd,
+    workspaceWorktreePath,
+    executionTargetIsRemote,
+    executionCwd: effectiveExecutionCwd,
+  });
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
 
   const acpxAgent = normalizeAgent(config);
   const mode = normalizeMode(config);
   const permissionMode = normalizePermissionMode(config);
   const nonInteractivePermissions = normalizeNonInteractivePermissions(config);
+  const requestedModel = asString(config.model, "").trim();
+  const requestedThinkingEffort = normalizeRequestedThinkingEffort(config);
+  const fastMode = acpxAgent === "codex" && config.fastMode === true;
   const timeoutSec = asNumber(config.timeoutSec, DEFAULT_ACPX_LOCAL_TIMEOUT_SEC);
   const stateDir = path.resolve(asString(config.stateDir, "") || defaultStateDir(agent.companyId, agent.id));
   await fs.mkdir(stateDir, { recursive: true });
@@ -651,7 +693,9 @@ async function buildRuntime(input: {
     ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
     : [];
   const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);
+  const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
   if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
+  if (issueWorkMode) env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
   if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
   if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
   if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
@@ -659,17 +703,23 @@ async function buildRuntime(input: {
   if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
   if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
   applyPaperclipWorkspaceEnv(env, {
-    workspaceCwd: effectiveWorkspaceCwd,
+    workspaceCwd: shapedWorkspaceEnv.workspaceCwd,
     workspaceSource,
     workspaceStrategy,
     workspaceId,
     workspaceRepoUrl,
     workspaceRepoRef,
     workspaceBranch,
-    workspaceWorktreePath,
+    workspaceWorktreePath: shapedWorkspaceEnv.workspaceWorktreePath,
     agentHome,
   });
-  for (const [key, value] of Object.entries(envConfig)) {
+  const shapedEnvConfig = rewriteWorkspaceCwdEnvVarsForExecution({
+    env: envConfig,
+    workspaceCwd: effectiveWorkspaceCwd,
+    executionCwd: shapedWorkspaceEnv.workspaceCwd,
+    executionTargetIsRemote,
+  });
+  for (const [key, value] of Object.entries(shapedEnvConfig)) {
     if (typeof value === "string") env[key] = value;
   }
   if (!hasExplicitApiKey && authToken) env.PAPERCLIP_API_KEY = authToken;
@@ -718,11 +768,6 @@ async function buildRuntime(input: {
   const wrapperPath = wrapper?.wrapperPath ?? null;
   const overrides = wrapperPath ? { [acpxAgent]: wrapperPath } : undefined;
   const agentRegistry = createAgentRegistry({ overrides });
-  const executionTarget = readAdapterExecutionTarget({
-    executionTarget: input.ctx.executionTarget,
-    legacyRemoteExecution: input.ctx.executionTransport?.remoteExecution,
-  });
-  const remoteExecutionIdentity = adapterExecutionTargetSessionIdentity(executionTarget);
   const fingerprint = shortHash({
     acpxAgent,
     agentCommand: agentCommand ?? acpxAgent,
@@ -730,6 +775,9 @@ async function buildRuntime(input: {
     mode,
     permissionMode,
     nonInteractivePermissions,
+    requestedModel,
+    requestedThinkingEffort,
+    fastMode,
     remoteExecutionIdentity,
     skillsIdentity,
     skillPromptInstructions,
@@ -755,13 +803,16 @@ async function buildRuntime(input: {
     stateDir,
     permissionMode,
     nonInteractivePermissions,
+    requestedModel,
+    requestedThinkingEffort,
+    fastMode,
     timeoutSec,
     sessionKey,
     fingerprint,
     agentCommand,
     agentRegistry,
     remoteExecutionIdentity,
-      skillPromptInstructions,
+    skillPromptInstructions,
     skillsIdentity: {
       ...skillsIdentity,
       commandNotes: skillCommandNotes,
@@ -769,6 +820,51 @@ async function buildRuntime(input: {
   };
 }
 
+function sessionConfigOptions(prepared: AcpxPreparedRuntime): Array<{ key: string; value: string }> {
+  const options: Array<{ key: string; value: string }> = [];
+  if (prepared.requestedModel) options.push({ key: "model", value: prepared.requestedModel });
+  if (prepared.requestedThinkingEffort) {
+    options.push({
+      key: prepared.acpxAgent === "codex" ? "reasoning_effort" : "effort",
+      value: prepared.requestedThinkingEffort,
+    });
+  }
+  if (prepared.fastMode) {
+    options.push(
+      { key: "service_tier", value: "fast" },
+      { key: "features.fast_mode", value: "true" },
+    );
+  }
+  return options;
+}
+
+async function applySessionConfigOptions(input: {
+  runtime: AcpRuntime;
+  handle: AcpRuntimeHandle;
+  prepared: AcpxPreparedRuntime;
+  onLog: AdapterExecutionContext["onLog"];
+}) {
+  const options = sessionConfigOptions(input.prepared);
+  if (options.length === 0) return;
+  if (!input.runtime.setConfigOption) {
+    const message =
+      "ACPX runtime does not expose session config controls; upgrade ACPX or remove configured model, effort, and fast mode overrides.";
+    await input.onLog("stderr", `[paperclip] ${message}\n`);
+    throw new Error(message);
+  }
+  for (const option of options) {
+    await input.runtime.setConfigOption({
+      handle: input.handle,
+      key: option.key,
+      value: option.value,
+    });
+    await input.onLog(
+      "stdout",
+      `[paperclip] Applied ACPX ${input.prepared.acpxAgent} config ${option.key}=${option.value}\n`,
+    );
+  }
+}
+
 async function buildPrompt(ctx: AdapterExecutionContext, resumedSession: boolean): Promise<{
   prompt: string;
   promptMetrics: Record<string, number>;
@@ -940,20 +1036,77 @@ async function cleanupIdleHandles(input: {
   now: number;
   idleMs: number;
 }) {
+  if (input.idleMs <= 0) return;
+
   const stale: Array<[string, RuntimeCacheEntry]> = [];
   for (const entry of input.handles.entries()) {
     if (input.now - entry[1].lastUsedAt >= input.idleMs) stale.push(entry);
   }
   for (const [key, entry] of stale) {
-    input.handles.delete(key);
-    await entry.runtime.close({
-      handle: entry.handle,
+    await closeWarmHandle({
+      handles: input.handles,
+      key,
+      entry,
       reason: "paperclip idle cleanup",
-      discardPersistentState: false,
-    }).catch(() => {});
+    });
   }
 }
 
+function clearWarmHandleTimer(entry: RuntimeCacheEntry) {
+  if (!entry.cleanupTimer) return;
+  clearTimeout(entry.cleanupTimer);
+  entry.cleanupTimer = undefined;
+}
+
+async function closeWarmHandle(input: {
+  handles: Map<string, RuntimeCacheEntry>;
+  key: string;
+  entry: RuntimeCacheEntry;
+  reason: string;
+  discardPersistentState?: boolean;
+}) {
+  if (input.handles.get(input.key) === input.entry) {
+    input.handles.delete(input.key);
+  }
+  clearWarmHandleTimer(input.entry);
+  await input.entry.runtime.close({
+    handle: input.entry.handle,
+    reason: input.reason,
+    discardPersistentState: input.discardPersistentState ?? false,
+  }).catch(() => {});
+}
+
+function scheduleIdleHandleCleanup(input: {
+  handles: Map<string, RuntimeCacheEntry>;
+  key: string;
+  entry: RuntimeCacheEntry;
+  idleMs: number;
+  now: () => number;
+}) {
+  clearWarmHandleTimer(input.entry);
+  if (input.idleMs <= 0) return;
+
+  const delayMs = Math.max(1, input.entry.lastUsedAt + input.idleMs - input.now());
+  input.entry.cleanupTimer = setTimeout(() => {
+    void (async () => {
+      const current = input.handles.get(input.key);
+      if (current !== input.entry) return;
+      const idleForMs = input.now() - input.entry.lastUsedAt;
+      if (idleForMs < input.idleMs) {
+        scheduleIdleHandleCleanup(input);
+        return;
+      }
+      await closeWarmHandle({
+        handles: input.handles,
+        key: input.key,
+        entry: input.entry,
+        reason: "paperclip idle cleanup",
+      });
+    })();
+  }, delayMs);
+  input.entry.cleanupTimer.unref?.();
+}
+
 function warmHandleMatches(
   entry: RuntimeCacheEntry | undefined,
   runtime: AcpRuntime,
@@ -969,7 +1122,7 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
 
   return async function executeAcpxLocal(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
     const prepared = await buildRuntime({ ctx });
-    const warmIdleMs = asNumber(ctx.config.warmHandleIdleMs, DEFAULT_WARM_HANDLE_IDLE_MS);
+    const warmIdleMs = asNumber(ctx.config.warmHandleIdleMs, DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS);
     await cleanupIdleHandles({ handles: warmHandles, now: now(), idleMs: warmIdleMs });
 
     const previousParams = parseObject(ctx.runtime.sessionParams);
@@ -985,6 +1138,7 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
       timeoutMs: prepared.timeoutSec > 0 ? prepared.timeoutSec * 1000 : undefined,
     };
     const runtime = cached?.runtime ?? createRuntime(runtimeOptions);
+    if (cached) clearWarmHandleTimer(cached);
     if (!canResume && asString(previousParams.runtimeSessionName, "")) {
       await ctx.onLog(
         "stdout",
@@ -1033,7 +1187,7 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         errorMessage: message,
         ...classified,
         provider: "acpx",
-        model: null,
+        model: prepared.requestedModel || null,
         clearSession,
         resultJson: { phase: "ensure_session" },
         summary: message,
@@ -1048,12 +1202,52 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         errorMessage: "ACPX did not return a runtime session handle.",
         errorCode: "acpx_runtime_error",
         provider: "acpx",
-        model: null,
+        model: prepared.requestedModel || null,
         resultJson: { phase: "ensure_session" },
         summary: "ACPX did not return a runtime session handle.",
       };
     }
     const sessionHandle = handle;
+    try {
+      await applySessionConfigOptions({
+        runtime,
+        handle: sessionHandle,
+        prepared,
+        onLog: ctx.onLog,
+      });
+    } catch (err) {
+      const classified = classifyError(err);
+      const message = err instanceof Error ? err.message : String(err);
+      await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
+      await runtime.close({
+        handle: sessionHandle,
+        reason: "paperclip config cleanup",
+        discardPersistentState: false,
+      }).catch(() => {});
+      const existing = warmHandles.get(prepared.sessionKey);
+      if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {
+        clearWarmHandleTimer(existing);
+        warmHandles.delete(prepared.sessionKey);
+      }
+      return {
+        exitCode: 1,
+        signal: null,
+        timedOut: false,
+        errorMessage: message,
+        ...classified,
+        provider: "acpx",
+        model: prepared.requestedModel || null,
+        clearSession,
+        resultJson: {
+          phase: "configure_session",
+          agent: prepared.acpxAgent,
+          requestedModel: prepared.requestedModel || null,
+          requestedThinkingEffort: prepared.requestedThinkingEffort || null,
+          fastMode: prepared.fastMode,
+        },
+        summary: message,
+      };
+    }
     const { prompt, promptMetrics, commandNotes } = await buildPrompt(ctx, resumedSession);
     const runPrompt = joinPromptSections([prepared.skillPromptInstructions, prompt]);
     await emitAcpxLog(ctx, {
@@ -1065,6 +1259,9 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
       runtimeSessionName: sessionHandle.runtimeSessionName,
       mode: prepared.mode,
       permissionMode: prepared.permissionMode,
+      model: prepared.requestedModel || null,
+      thinkingEffort: prepared.requestedThinkingEffort || null,
+      fastMode: prepared.fastMode,
     });
     if (ctx.onMeta) {
       await ctx.onMeta({
@@ -1074,6 +1271,9 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         commandNotes: [
           `ACPX runtime embedded in Paperclip with ${prepared.mode} session mode.`,
           `Effective ACPX permission mode: ${prepared.permissionMode}.`,
+          ...(prepared.requestedModel ? [`Requested ACPX model: ${prepared.requestedModel}.`] : []),
+          ...(prepared.requestedThinkingEffort ? [`Requested ACPX thinking effort: ${prepared.requestedThinkingEffort}.`] : []),
+          ...(prepared.fastMode ? ["Requested ACPX Codex fast mode."] : []),
           ...(Array.isArray(prepared.skillsIdentity.commandNotes)
             ? prepared.skillsIdentity.commandNotes.filter((note): note is string => typeof note === "string")
             : []),
@@ -1119,15 +1319,23 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
       const terminal = await turn.result;
       if (timeout) clearTimeout(timeout);
       if (terminal.status === "failed" || terminal.status === "cancelled" || timedOut) {
-        if (warmHandleMatches(warmHandles.get(prepared.sessionKey), runtime, sessionHandle)) {
-          warmHandles.delete(prepared.sessionKey);
+        const existing = warmHandles.get(prepared.sessionKey);
+        if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {
+          await closeWarmHandle({
+            handles: warmHandles,
+            key: prepared.sessionKey,
+            entry: existing,
+            reason: timedOut ? "paperclip timeout cleanup" : `paperclip turn ${terminal.status}`,
+            discardPersistentState: terminal.status === "cancelled" || timedOut,
+          });
+        } else {
+          await runtime.close({
+            handle: sessionHandle,
+            reason: timedOut ? "paperclip timeout cleanup" : `paperclip turn ${terminal.status}`,
+            discardPersistentState: terminal.status === "cancelled" || timedOut,
+          }).catch(() => {});
         }
-        await runtime.close({
-          handle: sessionHandle,
-          reason: timedOut ? "paperclip timeout cleanup" : `paperclip turn ${terminal.status}`,
-          discardPersistentState: terminal.status === "cancelled" || timedOut,
-        }).catch(() => {});
-      } else if (prepared.mode === "persistent") {
+      } else if (prepared.mode === "persistent" && warmIdleMs > 0) {
         const existing = warmHandles.get(prepared.sessionKey);
         if (existing && !warmHandleMatches(existing, runtime, sessionHandle)) {
           await runtime.close({
@@ -1136,13 +1344,37 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
             discardPersistentState: false,
           }).catch(() => {});
         } else {
-          warmHandles.set(prepared.sessionKey, {
+          const entry: RuntimeCacheEntry = {
             runtime,
             handle: sessionHandle,
             fingerprint: prepared.fingerprint,
             lastUsedAt: now(),
+          };
+          warmHandles.set(prepared.sessionKey, entry);
+          scheduleIdleHandleCleanup({
+            handles: warmHandles,
+            key: prepared.sessionKey,
+            entry,
+            idleMs: warmIdleMs,
+            now,
           });
         }
+      } else {
+        const existing = warmHandles.get(prepared.sessionKey);
+        if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {
+          await closeWarmHandle({
+            handles: warmHandles,
+            key: prepared.sessionKey,
+            entry: existing,
+            reason: "paperclip completed turn cleanup",
+          });
+        } else {
+          await runtime.close({
+            handle: sessionHandle,
+            reason: "paperclip completed turn cleanup",
+            discardPersistentState: false,
+          }).catch(() => {});
+        }
       }
 
       const errorMessage = timedOut
@@ -1165,7 +1397,7 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         sessionParams: buildSessionParams({ prepared, handle: sessionHandle }),
         sessionDisplayId: sessionHandle.agentSessionId ?? sessionHandle.backendSessionId ?? sessionHandle.runtimeSessionName,
         provider: "acpx",
-        model: null,
+        model: prepared.requestedModel || null,
         billingType: "unknown",
         costUsd: null,
         resultJson: {
@@ -1173,6 +1405,9 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
           stopReason: terminalStopReason,
           permissionMode: prepared.permissionMode,
           mode: prepared.mode,
+          requestedModel: prepared.requestedModel || null,
+          requestedThinkingEffort: prepared.requestedThinkingEffort || null,
+          fastMode: prepared.fastMode,
         },
         summary: textParts.join("").trim() || terminalStopReason || terminal.status,
         clearSession,
@@ -1188,7 +1423,9 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         reason: timedOut ? "paperclip timeout cleanup" : "paperclip error cleanup",
         discardPersistentState: timedOut,
       }).catch(() => {});
-      if (warmHandleMatches(warmHandles.get(prepared.sessionKey), runtime, sessionHandle)) {
+      const existing = warmHandles.get(prepared.sessionKey);
+      if (warmHandleMatches(existing, runtime, sessionHandle) && existing) {
+        clearWarmHandleTimer(existing);
         warmHandles.delete(prepared.sessionKey);
       }
       await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
@@ -1200,7 +1437,7 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         errorCode: timedOut ? "acpx_timeout" : classified.errorCode,
         errorMeta: classified.errorMeta,
         provider: "acpx",
-        model: null,
+        model: prepared.requestedModel || null,
         clearSession: clearSession || timedOut,
         resultJson: { phase: "turn" },
         summary: message,

packages/adapters/acpx-local/src/ui/build-config.ts

@@ -5,6 +5,7 @@ import {
   DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
   DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
   DEFAULT_ACPX_LOCAL_TIMEOUT_SEC,
+  DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS,
 } from "../index.js";
 
 function parseCommaArgs(value: string): string[] {
@@ -80,13 +81,15 @@ function readNumber(value: unknown, fallback: number): number {
 
 export function buildAcpxLocalConfig(v: CreateConfigValues): Record<string, unknown> {
   const schemaValues = v.adapterSchemaValues ?? {};
+  const agent = String(schemaValues.agent || DEFAULT_ACPX_LOCAL_AGENT);
   const ac: Record<string, unknown> = {
-    agent: schemaValues.agent || DEFAULT_ACPX_LOCAL_AGENT,
+    agent,
     mode: schemaValues.mode || DEFAULT_ACPX_LOCAL_MODE,
     permissionMode: schemaValues.permissionMode || DEFAULT_ACPX_LOCAL_PERMISSION_MODE,
     nonInteractivePermissions:
       schemaValues.nonInteractivePermissions || DEFAULT_ACPX_LOCAL_NON_INTERACTIVE_PERMISSIONS,
     timeoutSec: readNumber(schemaValues.timeoutSec, DEFAULT_ACPX_LOCAL_TIMEOUT_SEC),
+    warmHandleIdleMs: readNumber(schemaValues.warmHandleIdleMs, DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS),
   };
 
   for (const key of [
@@ -105,6 +108,11 @@ export function buildAcpxLocalConfig(v: CreateConfigValues): Record<string, unkn
   if (!ac.instructionsFilePath && v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
   if (!ac.promptTemplate && v.promptTemplate) ac.promptTemplate = v.promptTemplate;
   if (!ac.bootstrapPromptTemplate && v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
+  if (v.model?.trim()) ac.model = v.model.trim();
+  if (v.thinkingEffort) {
+    ac[agent === "codex" ? "modelReasoningEffort" : "effort"] = v.thinkingEffort;
+  }
+  if (schemaValues.fastMode === true) ac.fastMode = true;
 
   const env = parseEnvBindings(v.envBindings);
   const legacy = parseEnvVars(v.envVars);

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

@@ -3,6 +3,8 @@ import type { AdapterModelProfileDefinition } from "@paperclipai/adapter-utils";
 export const type = "claude_local";
 export const label = "Claude Code (local)";
 
+export const SANDBOX_INSTALL_COMMAND = "npm install -g @anthropic-ai/claude-code";
+
 export const models = [
   { id: "claude-opus-4-7", label: "Claude Opus 4.7" },
   { id: "claude-opus-4-6", label: "Claude Opus 4.6" },

packages/adapters/claude-local/src/server/claude-config.ts

@@ -3,8 +3,8 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { resolvePaperclipInstanceRootForAdapter } from "@paperclipai/adapter-utils/server-utils";
 
-const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
 const SEEDED_SHARED_FILES = [
   ".credentials.json",
   "credentials.json",
@@ -92,11 +92,14 @@ export function resolveManagedClaudeConfigSeedDir(
   env: NodeJS.ProcessEnv,
   companyId?: string,
 ): string {
-  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
-  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  const instanceRoot = resolvePaperclipInstanceRootForAdapter({
+    homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
+    instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
+    env,
+  });
   return companyId
-    ? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "claude-config-seed")
-    : path.resolve(paperclipHome, "instances", instanceId, "claude-config-seed");
+    ? path.resolve(instanceRoot, "companies", companyId, "claude-config-seed")
+    : path.resolve(instanceRoot, "claude-config-seed");
 }
 
 export async function prepareClaudeConfigSeed(

packages/adapters/claude-local/src/server/execute.remote.test.ts

@@ -10,6 +10,7 @@ const {
   prepareWorkspaceForSshExecution,
   restoreWorkspaceFromSshExecution,
   syncDirectoryToSsh,
+  startAdapterExecutionTargetPaperclipBridge,
 } = vi.hoisted(() => ({
   runChildProcess: vi.fn(async () => ({
     exitCode: 0,
@@ -26,9 +27,17 @@ const {
   })),
   ensureCommandResolvable: vi.fn(async () => undefined),
   resolveCommandForLogs: vi.fn(async () => "ssh://fixture@127.0.0.1:2222/remote/workspace :: claude"),
-  prepareWorkspaceForSshExecution: vi.fn(async () => undefined),
+  prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
   restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
   syncDirectoryToSsh: vi.fn(async () => undefined),
+  startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
+    env: {
+      PAPERCLIP_API_URL: "http://127.0.0.1:4310",
+      PAPERCLIP_API_KEY: "bridge-token",
+      PAPERCLIP_API_BRIDGE_MODE: "queue_v1",
+    },
+    stop: async () => {},
+  })),
 }));
 
 vi.mock("@paperclipai/adapter-utils/server-utils", async () => {
@@ -55,6 +64,16 @@ vi.mock("@paperclipai/adapter-utils/ssh", async () => {
   };
 });
 
+vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
+  const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>(
+    "@paperclipai/adapter-utils/execution-target",
+  );
+  return {
+    ...actual,
+    startAdapterExecutionTargetPaperclipBridge,
+  };
+});
+
 import { execute } from "./execute.js";
 
 describe("claude remote execution", () => {
@@ -73,8 +92,11 @@ describe("claude remote execution", () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-"));
     cleanupDirs.push(rootDir);
     const workspaceDir = path.join(rootDir, "workspace");
+    const alternateWorkspaceDir = path.join(rootDir, "workspace-other");
     const instructionsPath = path.join(rootDir, "instructions.md");
+    const managedRemoteWorkspace = "/remote/workspace/.paperclip-runtime/runs/run-1/workspace";
     await mkdir(workspaceDir, { recursive: true });
+    await mkdir(alternateWorkspaceDir, { recursive: true });
     await writeFile(instructionsPath, "Use the remote workspace.\n", "utf8");
 
     await execute({
@@ -95,12 +117,37 @@ describe("claude remote execution", () => {
       config: {
         command: "claude",
         instructionsFilePath: instructionsPath,
+        env: {
+          QA_PROJECT_WORKSPACE_CWD: workspaceDir,
+          RANDOM_WORKSPACE_CWD: workspaceDir,
+          OTHER_ENV: workspaceDir,
+        },
       },
       context: {
         paperclipWorkspace: {
           cwd: workspaceDir,
           source: "project_primary",
+          strategy: "git_worktree",
+          workspaceId: "workspace-1",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+          repoRef: "main",
+          branchName: "feature/remote-claude",
+          worktreePath: workspaceDir,
         },
+        paperclipWorkspaces: [
+          {
+            workspaceId: "workspace-1",
+            cwd: workspaceDir,
+            repoUrl: "https://github.com/paperclipai/paperclip.git",
+            repoRef: "main",
+          },
+          {
+            workspaceId: "workspace-2",
+            cwd: alternateWorkspaceDir,
+            repoUrl: "https://github.com/paperclipai/paperclip.git",
+            repoRef: "feature/other",
+          },
+        ],
       },
       executionTransport: {
         remoteExecution: {
@@ -112,7 +159,6 @@ describe("claude remote execution", () => {
           privateKey: "PRIVATE KEY",
           knownHosts: "[127.0.0.1]:2222 ssh-ed25519 AAAA",
           strictHostKeyChecking: true,
-          paperclipApiUrl: "http://198.51.100.10:3102",
         },
       },
       onLog: async () => {},
@@ -121,11 +167,11 @@ describe("claude remote execution", () => {
     expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);
     expect(prepareWorkspaceForSshExecution).toHaveBeenCalledWith(expect.objectContaining({
       localDir: workspaceDir,
-      remoteDir: "/remote/workspace",
+      remoteDir: managedRemoteWorkspace,
     }));
     expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);
     expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({
-      remoteDir: "/remote/workspace/.paperclip-runtime/claude/skills",
+      remoteDir: `${managedRemoteWorkspace}/.paperclip-runtime/claude/skills`,
       followSymlinks: true,
     }));
     expect(runChildProcess).toHaveBeenCalledTimes(1);
@@ -133,15 +179,37 @@ describe("claude remote execution", () => {
       | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]
       | undefined;
     expect(call?.[2]).toContain("--append-system-prompt-file");
-    expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/claude/skills/agent-instructions.md");
+    expect(call?.[2]).toContain(
+      `${managedRemoteWorkspace}/.paperclip-runtime/claude/skills/agent-instructions.md`,
+    );
     expect(call?.[2]).toContain("--add-dir");
-    expect(call?.[2]).toContain("/remote/workspace/.paperclip-runtime/claude/skills");
-    expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://198.51.100.10:3102");
-    expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");
+    expect(call?.[2]).toContain(`${managedRemoteWorkspace}/.paperclip-runtime/claude/skills`);
+    expect(call?.[3].env.PAPERCLIP_WORKSPACE_CWD).toBe(managedRemoteWorkspace);
+    expect(call?.[3].env.PAPERCLIP_WORKSPACE_WORKTREE_PATH).toBeUndefined();
+    expect(JSON.parse(call?.[3].env.PAPERCLIP_WORKSPACES_JSON ?? "[]")).toEqual([
+      {
+        workspaceId: "workspace-1",
+        cwd: managedRemoteWorkspace,
+        repoUrl: "https://github.com/paperclipai/paperclip.git",
+        repoRef: "main",
+      },
+      {
+        workspaceId: "workspace-2",
+        repoUrl: "https://github.com/paperclipai/paperclip.git",
+        repoRef: "feature/other",
+      },
+    ]);
+    expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://127.0.0.1:4310");
+    expect(call?.[3].env.PAPERCLIP_API_BRIDGE_MODE).toBe("queue_v1");
+    expect(call?.[3].env.QA_PROJECT_WORKSPACE_CWD).toBe(managedRemoteWorkspace);
+    expect(call?.[3].env.RANDOM_WORKSPACE_CWD).toBe(managedRemoteWorkspace);
+    expect(call?.[3].env.OTHER_ENV).toBe(workspaceDir);
+    expect(call?.[3].remoteExecution?.remoteCwd).toBe(managedRemoteWorkspace);
+    expect(startAdapterExecutionTargetPaperclipBridge).toHaveBeenCalledTimes(1);
     expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);
     expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledWith(expect.objectContaining({
       localDir: workspaceDir,
-      remoteDir: "/remote/workspace",
+      remoteDir: managedRemoteWorkspace,
     }));
   });
 
@@ -202,6 +270,7 @@ describe("claude remote execution", () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-claude-remote-resume-match-"));
     cleanupDirs.push(rootDir);
     const workspaceDir = path.join(rootDir, "workspace");
+    const managedRemoteWorkspace = "/remote/workspace/.paperclip-runtime/runs/run-ssh-resume/workspace";
     await mkdir(workspaceDir, { recursive: true });
 
     await execute({
@@ -217,13 +286,13 @@ describe("claude remote execution", () => {
         sessionId: "session-123",
         sessionParams: {
           sessionId: "session-123",
-          cwd: "/remote/workspace",
+          cwd: managedRemoteWorkspace,
           remoteExecution: {
             transport: "ssh",
             host: "127.0.0.1",
             port: 2222,
             username: "fixture",
-            remoteCwd: "/remote/workspace",
+            remoteCwd: managedRemoteWorkspace,
           },
         },
         sessionDisplayId: "session-123",

packages/adapters/claude-local/src/server/execute.ts

@@ -5,16 +5,18 @@ import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclip
 import type { RunProcessResult } from "@paperclipai/adapter-utils/server-utils";
 import {
   adapterExecutionTargetIsRemote,
-  adapterExecutionTargetPaperclipApiUrl,
   adapterExecutionTargetRemoteCwd,
+  overrideAdapterExecutionTargetRemoteCwd,
   adapterExecutionTargetSessionIdentity,
   adapterExecutionTargetSessionMatches,
   adapterExecutionTargetUsesManagedHome,
   adapterExecutionTargetUsesPaperclipBridge,
   describeAdapterExecutionTarget,
   ensureAdapterExecutionTargetCommandResolvable,
+  ensureAdapterExecutionTargetRuntimeCommandInstalled,
   prepareAdapterExecutionTargetRuntime,
   readAdapterExecutionTarget,
+  resolveAdapterExecutionTargetTimeoutSec,
   resolveAdapterExecutionTargetCommandForLogs,
   runAdapterExecutionTargetProcess,
   runAdapterExecutionTargetShellCommand,
@@ -30,12 +32,16 @@ import {
   applyPaperclipWorkspaceEnv,
   buildPaperclipEnv,
   readPaperclipRuntimeSkillEntries,
+  readPaperclipIssueWorkModeFromContext,
   joinPromptSections,
   buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensurePathInEnv,
+  refreshPaperclipWorkspaceEnvForExecution,
   renderTemplate,
   renderPaperclipWakePrompt,
+  rewriteWorkspaceCwdEnvVarsForExecution,
+  shapePaperclipWorkspaceEnvForExecution,
   stringifyPaperclipWakePayload,
   DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -53,6 +59,8 @@ import { prepareClaudeConfigSeed } from "./claude-config.js";
 import { resolveClaudeDesiredSkillNames } from "./skills.js";
 import { isBedrockModelId } from "./models.js";
 import { prepareClaudePromptBundle } from "./prompt-cache.js";
+import { buildClaudeExecutionPermissionArgs } from "./permissions.js";
+import { SANDBOX_INSTALL_COMMAND } from "../index.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
@@ -61,8 +69,10 @@ interface ClaudeExecutionInput {
   agent: AdapterExecutionContext["agent"];
   config: Record<string, unknown>;
   context: Record<string, unknown>;
+  runtimeCommandSpec?: AdapterExecutionContext["runtimeCommandSpec"];
   executionTarget?: ReturnType<typeof readAdapterExecutionTarget>;
   authToken?: string;
+  onLog?: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
 }
 
 interface ClaudeRuntimeConfig {
@@ -112,7 +122,8 @@ function resolveClaudeBillingType(env: Record<string, string>): "api" | "subscri
 }
 
 async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<ClaudeRuntimeConfig> {
-  const { runId, agent, config, context, executionTarget, authToken } = input;
+  const { runId, agent, config, context, runtimeCommandSpec, executionTarget, authToken } = input;
+  const onLog = input.onLog ?? (async () => {});
 
   const command = asString(config.command, "claude");
   const workspaceContext = parseObject(context.paperclipWorkspace);
@@ -145,6 +156,15 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
   const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+  const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
+  let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+  const shapedWorkspaceEnv = shapePaperclipWorkspaceEnvForExecution({
+    workspaceCwd: effectiveWorkspaceCwd,
+    workspaceWorktreePath,
+    workspaceHints,
+    executionTargetIsRemote,
+    executionCwd: effectiveExecutionCwd,
+  });
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
 
   const envConfig = parseObject(config.env);
@@ -177,10 +197,14 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
     ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
     : [];
   const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);
+  const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
 
   if (wakeTaskId) {
     env.PAPERCLIP_TASK_ID = wakeTaskId;
   }
+  if (issueWorkMode) {
+    env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
+  }
   if (wakeReason) {
     env.PAPERCLIP_WAKE_REASON = wakeReason;
   }
@@ -200,18 +224,18 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
     env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
   }
   applyPaperclipWorkspaceEnv(env, {
-    workspaceCwd: effectiveWorkspaceCwd,
+    workspaceCwd: shapedWorkspaceEnv.workspaceCwd,
     workspaceSource,
     workspaceStrategy,
     workspaceId,
     workspaceRepoUrl,
     workspaceRepoRef,
     workspaceBranch,
-    workspaceWorktreePath,
+    workspaceWorktreePath: shapedWorkspaceEnv.workspaceWorktreePath,
     agentHome,
   });
-  if (workspaceHints.length > 0) {
-    env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
+  if (shapedWorkspaceEnv.workspaceHints.length > 0) {
+    env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(shapedWorkspaceEnv.workspaceHints);
   }
   if (runtimeServiceIntents.length > 0) {
     env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
@@ -222,12 +246,13 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   if (runtimePrimaryUrl) {
     env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
   }
-  const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);
-  if (targetPaperclipApiUrl) {
-    env.PAPERCLIP_API_URL = targetPaperclipApiUrl;
-  }
-
-  for (const [key, value] of Object.entries(envConfig)) {
+  const shapedEnvConfig = rewriteWorkspaceCwdEnvVarsForExecution({
+    env: envConfig,
+    workspaceCwd: effectiveWorkspaceCwd,
+    executionCwd: shapedWorkspaceEnv.workspaceCwd,
+    executionTargetIsRemote,
+  });
+  for (const [key, value] of Object.entries(shapedEnvConfig)) {
     if (typeof value === "string") env[key] = value;
   }
 
@@ -235,8 +260,31 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
     env.PAPERCLIP_API_KEY = authToken;
   }
 
-  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
-  await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);
+  const runtimeEnv = Object.fromEntries(
+    Object.entries(ensurePathInEnv({ ...process.env, ...env })).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+  const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(
+    executionTarget,
+    asNumber(config.timeoutSec, 0),
+  );
+  const graceSec = asNumber(config.graceSec, 20);
+  await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+    runId,
+    target: executionTarget,
+    installCommand: runtimeCommandSpec?.installCommand,
+    detectCommand: runtimeCommandSpec?.detectCommand,
+    cwd,
+    env: runtimeEnv,
+    timeoutSec,
+    graceSec,
+    onLog,
+  });
+  await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {
+    installCommand: SANDBOX_INSTALL_COMMAND,
+    timeoutSec,
+  });
   const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
   const loggedEnv = buildInvocationEnvForLogs(env, {
     runtimeEnv,
@@ -244,8 +292,6 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
     resolvedCommand,
   });
 
-  const timeoutSec = asNumber(config.timeoutSec, 0);
-  const graceSec = asNumber(config.graceSec, 20);
   const extraArgs = (() => {
     const fromExtraArgs = asStringArray(config.extraArgs);
     if (fromExtraArgs.length > 0) return fromExtraArgs;
@@ -311,6 +357,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
   });
   const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
+  const executionTargetIsSandbox = executionTarget?.kind === "remote" && executionTarget.transport === "sandbox";
 
   const promptTemplate = asString(
     config.promptTemplate,
@@ -322,6 +369,21 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const maxTurns = asNumber(config.maxTurnsPerRun, 0);
   const dangerouslySkipPermissions = asBoolean(config.dangerouslySkipPermissions, true);
   const configEnv = parseObject(config.env);
+  const workspaceContext = parseObject(context.paperclipWorkspace);
+  const workspaceCwd = asString(workspaceContext.cwd, "");
+  const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceStrategy = asString(workspaceContext.strategy, "");
+  const workspaceBranch = asString(workspaceContext.branchName, "") || null;
+  const workspaceWorktreePath = asString(workspaceContext.worktreePath, "") || null;
+  const agentHome = asString(workspaceContext.agentHome, "") || null;
+  const workspaceHints = Array.isArray(context.paperclipWorkspaces)
+    ? context.paperclipWorkspaces.filter(
+        (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const configuredCwd = asString(config.cwd, "");
+  const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+  const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
   const hasExplicitClaudeConfigDir =
     typeof configEnv.CLAUDE_CONFIG_DIR === "string" && configEnv.CLAUDE_CONFIG_DIR.trim().length > 0;
   const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
@@ -331,8 +393,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     agent,
     config,
     context,
+    runtimeCommandSpec: ctx.runtimeCommandSpec,
     executionTarget,
     authToken,
+    onLog,
   });
   const {
     command,
@@ -348,7 +412,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     extraArgs,
   } = runtimeConfig;
   let loggedEnv = initialLoggedEnv;
-  const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+  let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
   const terminalResultCleanupGraceMs = Math.max(
     0,
     asNumber(config.terminalResultCleanupGraceMs, 5_000),
@@ -402,9 +466,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
           `[paperclip] Syncing workspace and Claude runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
         );
         return await prepareAdapterExecutionTargetRuntime({
+          runId,
           target: executionTarget,
           adapterKey: "claude",
+          timeoutSec,
           workspaceLocalDir: cwd,
+          installCommand: SANDBOX_INSTALL_COMMAND,
+          detectCommand: command,
           assets: [
             {
               key: "skills",
@@ -422,6 +490,26 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         });
       })()
     : null;
+  if (preparedExecutionTargetRuntime?.workspaceRemoteDir) {
+    effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir;
+  }
+  const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
+  refreshPaperclipWorkspaceEnvForExecution({
+    env,
+    envConfig: configEnv,
+    workspaceCwd: effectiveWorkspaceCwd,
+    workspaceSource,
+    workspaceStrategy,
+    workspaceId,
+    workspaceRepoUrl,
+    workspaceRepoRef,
+    workspaceBranch,
+    workspaceWorktreePath,
+    workspaceHints,
+    agentHome,
+    executionTargetIsRemote,
+    executionCwd: effectiveExecutionCwd,
+  });
   const restoreRemoteWorkspace = preparedExecutionTargetRuntime
     ? () => preparedExecutionTargetRuntime.restoreWorkspace()
     : null;
@@ -469,12 +557,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     );
   }
   let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
-  if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
+  if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
     paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
       runId,
-      target: executionTarget,
+      target: runtimeExecutionTarget,
       runtimeRootDir: preparedExecutionTargetRuntime?.runtimeRootDir,
       adapterKey: "claude",
+      timeoutSec,
       hostApiToken: env.PAPERCLIP_API_KEY,
       onLog,
     });
@@ -503,7 +592,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     runtimeSessionId.length > 0 &&
     hasMatchingPromptBundle &&
     (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
-    adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);
+    adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
   const sessionId = canResumeSession ? runtimeSessionId : null;
   if (
     executionTargetIsRemote &&
@@ -576,7 +665,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   ) => {
     const args = ["--print", "-", "--output-format", "stream-json", "--verbose"];
     if (resumeSessionId) args.push("--resume", resumeSessionId);
-    if (dangerouslySkipPermissions) args.push("--dangerously-skip-permissions");
+    args.push(...buildClaudeExecutionPermissionArgs({
+      dangerouslySkipPermissions,
+      targetIsSandbox: executionTargetIsSandbox,
+    }));
     if (chrome) args.push("--chrome");
     // For Bedrock: only pass --model when the ID is a Bedrock-native identifier
     // (e.g. "us.anthropic.*" or ARN). Anthropic-style IDs like "claude-opus-4-6" are invalid
@@ -620,6 +712,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     if (!resumeSessionId) {
       commandNotes.push(`Using stable Claude prompt bundle ${promptBundle.bundleKey}.`);
     }
+    if (dangerouslySkipPermissions && executionTargetIsSandbox) {
+      commandNotes.push(
+        "Using a broad --allowedTools whitelist for sandbox execution because Claude rejects --dangerously-skip-permissions under root/sudo.",
+      );
+    }
     if (attemptInstructionsFilePath && !resumeSessionId) {
       commandNotes.push(
         `Injected agent instructions via --append-system-prompt-file ${instructionsFilePath} (with path directive appended)`,
@@ -639,7 +736,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       });
     }
 
-    const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {
+    const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
       cwd,
       env,
       stdin: prompt,
@@ -760,7 +857,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         promptBundleKey: promptBundle.bundleKey,
         ...(executionTargetIsRemote
           ? {
-              remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),
+              remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
             }
           : {}),
         ...(workspaceId ? { workspaceId } : {}),
@@ -777,6 +874,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     const transientUpstream =
       failed &&
       !loginMeta.requiresLogin &&
+      !clearSessionForMaxTurns &&
       isClaudeTransientUpstreamError({
         parsed,
         stdout: proc.stdout,
@@ -793,11 +891,14 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       : null;
     const resolvedErrorCode = loginMeta.requiresLogin
       ? "claude_auth_required"
+      : failed && clearSessionForMaxTurns
+      ? "max_turns_exhausted"
       : transientUpstream
       ? "claude_transient_upstream"
       : null;
     const mergedResultJson: Record<string, unknown> = {
       ...parsed,
+      ...(failed && clearSessionForMaxTurns ? { stopReason: "max_turns_exhausted" } : {}),
       ...(transientUpstream ? { errorFamily: "transient_upstream" } : {}),
       ...(transientRetryNotBefore ? { retryNotBefore: transientRetryNotBefore.toISOString() } : {}),
       ...(transientRetryNotBefore ? { transientRetryNotBefore: transientRetryNotBefore.toISOString() } : {}),

packages/adapters/claude-local/src/server/parse.ts

@@ -170,11 +170,19 @@ export function isClaudeMaxTurnsResult(parsed: Record<string, unknown> | null |
   const subtype = asString(parsed.subtype, "").trim().toLowerCase();
   if (subtype === "error_max_turns") return true;
 
-  const stopReason = asString(parsed.stop_reason, "").trim().toLowerCase();
-  if (stopReason === "max_turns") return true;
+  const structuredStopReasons = [
+    parsed.stop_reason,
+    parsed.stopReason,
+    parsed.error_code,
+    parsed.errorCode,
+  ].map((value) => asString(value, "").trim().toLowerCase());
 
-  const resultText = asString(parsed.result, "").trim();
-  return /max(?:imum)?\s+turns?/i.test(resultText);
+  return structuredStopReasons.some((reason) =>
+    reason === "max_turns" ||
+    reason === "max_turns_exhausted" ||
+    reason === "turn_limit" ||
+    reason === "turn_limit_exhausted",
+  );
 }
 
 export function isClaudeUnknownSessionError(parsed: Record<string, unknown>): boolean {

packages/adapters/claude-local/src/server/permissions.ts

@@ -0,0 +1,43 @@
+// Explicit allowlist of Claude Code tools we permit when running inside a
+// sandbox. We use this instead of `--dangerously-skip-permissions` for sandbox
+// targets because the permission-approval prompts can't be answered by a
+// human inside a non-interactive sandbox, but blanket-allowing every tool
+// would defeat the point of having a separate sandbox code path.
+//
+// Maintenance: this list must be reviewed when Claude Code releases a new
+// tool. The canonical list of built-in tools is documented at
+// https://docs.claude.com/en/docs/claude-code/built-in-tools — when a tool
+// is added there, decide whether it should be allowed in sandbox runs and
+// either add it here or document the deliberate exclusion. Omitting a tool
+// silently disables it inside sandboxes, which can look like the tool is
+// "broken" rather than intentionally gated.
+const SANDBOX_ALLOWED_TOOLS =
+  "Task AskUserQuestion Bash(*) CronCreate CronDelete CronList Edit " +
+  "EnterPlanMode EnterWorktree ExitPlanMode ExitWorktree Glob Grep Monitor " +
+  "NotebookEdit PushNotification Read RemoteTrigger ScheduleWakeup Skill " +
+  "TaskOutput TaskStop TodoWrite ToolSearch WebFetch WebSearch Write";
+
+export function buildClaudeProbePermissionArgs(input: {
+  dangerouslySkipPermissions: boolean;
+  targetIsSandbox: boolean;
+}): string[] {
+  if (!input.dangerouslySkipPermissions) return [];
+  // For sandbox targets, mirror the execution path: pass `--allowedTools`
+  // with the curated allowlist instead of dropping the flag entirely. The
+  // hello probe is a one-shot prompt that should never trigger a tool, but
+  // if a future probe prompt does, we don't want Claude CLI to stall on an
+  // interactive permission prompt that no human can answer.
+  if (input.targetIsSandbox) return ["--allowedTools", SANDBOX_ALLOWED_TOOLS];
+  return ["--dangerously-skip-permissions"];
+}
+
+export function buildClaudeExecutionPermissionArgs(input: {
+  dangerouslySkipPermissions: boolean;
+  targetIsSandbox: boolean;
+}): string[] {
+  if (!input.dangerouslySkipPermissions) return [];
+  if (input.targetIsSandbox) {
+    return ["--allowedTools", SANDBOX_ALLOWED_TOOLS];
+  }
+  return ["--dangerously-skip-permissions"];
+}

packages/adapters/claude-local/src/server/prompt-cache.ts

@@ -1,12 +1,13 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { createHash, type Hash } from "node:crypto";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
-import { ensurePaperclipSkillSymlink, type PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";
-
-const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+import {
+  ensurePaperclipSkillSymlink,
+  resolvePaperclipInstanceRootForAdapter,
+  type PaperclipSkillEntry,
+} from "@paperclipai/adapter-utils/server-utils";
 
 type SkillEntry = PaperclipSkillEntry;
 
@@ -25,12 +26,13 @@ function resolveManagedClaudePromptCacheRoot(
   env: NodeJS.ProcessEnv,
   companyId: string,
 ): string {
-  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
-  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  const instanceRoot = resolvePaperclipInstanceRootForAdapter({
+    homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
+    instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
+    env,
+  });
   return path.resolve(
-    paperclipHome,
-    "instances",
-    instanceId,
+    instanceRoot,
     "companies",
     companyId,
     "claude-prompt-cache",

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

@@ -14,6 +14,7 @@ import {
 import {
   ensureAdapterExecutionTargetCommandResolvable,
   ensureAdapterExecutionTargetDirectory,
+  maybeRunSandboxInstallCommand,
   runAdapterExecutionTargetProcess,
   describeAdapterExecutionTarget,
   resolveAdapterExecutionTargetCwd,
@@ -21,6 +22,8 @@ import {
 import path from "node:path";
 import { detectClaudeLoginRequired, parseClaudeStreamJson } from "./parse.js";
 import { isBedrockModelId } from "./models.js";
+import { buildClaudeProbePermissionArgs } from "./permissions.js";
+import { SANDBOX_INSTALL_COMMAND } from "../index.js";
 
 function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
   if (checks.some((check) => check.level === "error")) return "fail";
@@ -62,6 +65,7 @@ export async function testEnvironment(
   const command = asString(config.command, "claude");
   const target = ctx.executionTarget ?? null;
   const targetIsRemote = target?.kind === "remote";
+  const targetIsSandbox = target?.kind === "remote" && target.transport === "sandbox";
   const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());
   const targetLabel = targetIsRemote
     ? ctx.environmentName ?? describeAdapterExecutionTarget(target)
@@ -102,6 +106,15 @@ export async function testEnvironment(
     if (typeof value === "string") env[key] = value;
   }
   const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  const installCheck = await maybeRunSandboxInstallCommand({
+    runId,
+    target,
+    adapterKey: "claude",
+    installCommand: SANDBOX_INSTALL_COMMAND,
+    detectCommand: command,
+    env,
+  });
+  if (installCheck) checks.push(installCheck);
   try {
     await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);
     checks.push({
@@ -189,7 +202,7 @@ export async function testEnvironment(
       })();
 
       const args = ["--print", "-", "--output-format", "stream-json", "--verbose"];
-      if (dangerouslySkipPermissions) args.push("--dangerously-skip-permissions");
+      args.push(...buildClaudeProbePermissionArgs({ dangerouslySkipPermissions, targetIsSandbox }));
       if (chrome) args.push("--chrome");
       // For Bedrock: only pass --model when the ID is a Bedrock-native identifier.
       if (model && (!hasBedrock || isBedrockModelId(model))) {

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

@@ -3,6 +3,8 @@ import type { AdapterModelProfileDefinition } from "@paperclipai/adapter-utils";
 export const type = "codex_local";
 export const label = "Codex (local)";
 
+export const SANDBOX_INSTALL_COMMAND = "npm install -g @openai/codex";
+
 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;

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

@@ -67,4 +67,22 @@ describe("buildCodexExecArgs", () => {
       "-",
     ]);
   });
+
+  it("adds --skip-git-repo-check when requested", () => {
+    const result = buildCodexExecArgs(
+      {
+        model: "gpt-5.3-codex",
+      },
+      { skipGitRepoCheck: true },
+    );
+
+    expect(result.args).toEqual([
+      "exec",
+      "--json",
+      "--skip-git-repo-check",
+      "--model",
+      "gpt-5.3-codex",
+      "-",
+    ]);
+  });
 });

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

@@ -30,7 +30,10 @@ function formatFastModeSupportedModels(): string {
 
 export function buildCodexExecArgs(
   config: unknown,
-  options: { resumeSessionId?: string | null } = {},
+  options: {
+    resumeSessionId?: string | null;
+    skipGitRepoCheck?: boolean;
+  } = {},
 ): BuildCodexExecArgsResult {
   const record = asRecord(config);
   const model = asString(record.model, "").trim();
@@ -48,6 +51,7 @@ export function buildCodexExecArgs(
   const extraArgs = readExtraArgs(record);
 
   const args = ["exec", "--json"];
+  if (options.skipGitRepoCheck) args.push("--skip-git-repo-check");
   if (search) args.unshift("--search");
   if (bypass) args.push("--dangerously-bypass-approvals-and-sandbox");
   if (model) args.push("--model", model);

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

@@ -2,11 +2,11 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { resolvePaperclipInstanceRootForAdapter } from "@paperclipai/adapter-utils/server-utils";
 
 const TRUTHY_ENV_RE = /^(1|true|yes|on)$/i;
 const COPIED_SHARED_FILES = ["config.json", "config.toml", "instructions.md"] as const;
 const SYMLINKED_SHARED_FILES = ["auth.json"] as const;
-const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
 
 function nonEmpty(value: string | undefined): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
@@ -31,11 +31,14 @@ export function resolveManagedCodexHomeDir(
   env: NodeJS.ProcessEnv,
   companyId?: string,
 ): string {
-  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
-  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  const instanceRoot = resolvePaperclipInstanceRootForAdapter({
+    homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
+    instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
+    env,
+  });
   return companyId
-    ? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "codex-home")
-    : path.resolve(paperclipHome, "instances", instanceId, "codex-home");
+    ? path.resolve(instanceRoot, "companies", companyId, "codex-home")
+    : path.resolve(instanceRoot, "codex-home");
 }
 
 async function ensureParentDir(target: string): Promise<void> {
@@ -71,33 +74,71 @@ async function ensureCopiedFile(target: string, source: string): Promise<void> {
   await fs.copyFile(source, target);
 }
 
+/**
+ * Writes an `auth.json` containing only `OPENAI_API_KEY` so the codex CLI can
+ * authenticate via API key. Overwrites any existing file or symlink at that
+ * path. Required because the codex CLI (>= 0.122) ignores the `OPENAI_API_KEY`
+ * environment variable and only reads credentials from `$CODEX_HOME/auth.json`.
+ */
+export async function writeApiKeyAuthJson(home: string, apiKey: string): Promise<void> {
+  await fs.mkdir(home, { recursive: true });
+  const target = path.join(home, "auth.json");
+  await fs.rm(target, { force: true });
+  await fs.writeFile(target, JSON.stringify({ OPENAI_API_KEY: apiKey }), { mode: 0o600 });
+}
+
 export async function prepareManagedCodexHome(
   env: NodeJS.ProcessEnv,
   onLog: AdapterExecutionContext["onLog"],
   companyId?: string,
+  options: { apiKey?: string | null } = {},
 ): Promise<string> {
   const targetHome = resolveManagedCodexHomeDir(env, companyId);
+  const apiKey = nonEmpty(options.apiKey ?? undefined);
 
   const sourceHome = resolveSharedCodexHomeDir(env);
-  if (path.resolve(sourceHome) === path.resolve(targetHome)) return targetHome;
+  const seedFromShared = path.resolve(sourceHome) !== path.resolve(targetHome);
 
   await fs.mkdir(targetHome, { recursive: true });
 
-  for (const name of SYMLINKED_SHARED_FILES) {
-    const source = path.join(sourceHome, name);
-    if (!(await pathExists(source))) continue;
-    await ensureSymlink(path.join(targetHome, name), source);
+  // If a previous run wrote an apikey-mode auth.json (regular file) and this
+  // run has no apiKey, remove it so the chatgpt-mode symlink can be restored.
+  // Without this cleanup, ensureSymlink bails on a non-symlink and Codex keeps
+  // authenticating with the stale key after it is removed from configuration.
+  if (!apiKey && seedFromShared) {
+    const authPath = path.join(targetHome, "auth.json");
+    const existing = await fs.lstat(authPath).catch(() => null);
+    if (existing && !existing.isSymbolicLink()) {
+      await fs.rm(authPath, { force: true });
+    }
   }
 
-  for (const name of COPIED_SHARED_FILES) {
-    const source = path.join(sourceHome, name);
-    if (!(await pathExists(source))) continue;
-    await ensureCopiedFile(path.join(targetHome, name), source);
+  if (seedFromShared) {
+    for (const name of SYMLINKED_SHARED_FILES) {
+      const source = path.join(sourceHome, name);
+      if (!(await pathExists(source))) continue;
+      await ensureSymlink(path.join(targetHome, name), source);
+    }
+
+    for (const name of COPIED_SHARED_FILES) {
+      const source = path.join(sourceHome, name);
+      if (!(await pathExists(source))) continue;
+      await ensureCopiedFile(path.join(targetHome, name), source);
+    }
+
+    await onLog(
+      "stdout",
+      `[paperclip] Using ${isWorktreeMode(env) ? "worktree-isolated" : "Paperclip-managed"} Codex home "${targetHome}" (seeded from "${sourceHome}").\n`,
+    );
+  }
+
+  if (apiKey) {
+    await writeApiKeyAuthJson(targetHome, apiKey);
+    await onLog(
+      "stdout",
+      `[paperclip] Wrote API-key auth.json into Codex home "${targetHome}" from configured OPENAI_API_KEY.\n`,
+    );
   }
 
-  await onLog(
-    "stdout",
-    `[paperclip] Using ${isWorktreeMode(env) ? "worktree-isolated" : "Paperclip-managed"} Codex home "${targetHome}" (seeded from "${sourceHome}").\n`,
-  );
   return targetHome;
 }

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

@@ -10,6 +10,7 @@ const {
   prepareWorkspaceForSshExecution,
   restoreWorkspaceFromSshExecution,
   syncDirectoryToSsh,
+  startAdapterExecutionTargetPaperclipBridge,
 } = vi.hoisted(() => ({
   runChildProcess: vi.fn(async () => ({
     exitCode: 1,
@@ -22,9 +23,17 @@ const {
   })),
   ensureCommandResolvable: vi.fn(async () => undefined),
   resolveCommandForLogs: vi.fn(async () => "/usr/bin/codex"),
-  prepareWorkspaceForSshExecution: vi.fn(async () => undefined),
+  prepareWorkspaceForSshExecution: vi.fn(async () => ({ gitBacked: false })),
   restoreWorkspaceFromSshExecution: vi.fn(async () => undefined),
   syncDirectoryToSsh: vi.fn(async () => undefined),
+  startAdapterExecutionTargetPaperclipBridge: vi.fn(async () => ({
+    env: {
+      PAPERCLIP_API_URL: "http://127.0.0.1:4310",
+      PAPERCLIP_API_KEY: "bridge-token",
+      PAPERCLIP_API_BRIDGE_MODE: "queue_v1",
+    },
+    stop: async () => {},
+  })),
 }));
 
 vi.mock("@paperclipai/adapter-utils/server-utils", async () => {
@@ -51,6 +60,16 @@ vi.mock("@paperclipai/adapter-utils/ssh", async () => {
   };
 });
 
+vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
+  const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>(
+    "@paperclipai/adapter-utils/execution-target",
+  );
+  return {
+    ...actual,
+    startAdapterExecutionTargetPaperclipBridge,
+  };
+});
+
 import { execute } from "./execute.js";
 
 describe("codex remote execution", () => {
@@ -70,10 +89,13 @@ describe("codex remote execution", () => {
     cleanupDirs.push(rootDir);
     const workspaceDir = path.join(rootDir, "workspace");
     const codexHomeDir = path.join(rootDir, "codex-home");
+    const managedRemoteWorkspace = "/remote/workspace/.paperclip-runtime/runs/run-1/workspace";
     await mkdir(workspaceDir, { recursive: true });
     await mkdir(codexHomeDir, { recursive: true });
     await writeFile(path.join(rootDir, "instructions.md"), "Use the remote workspace.\n", "utf8");
     await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");
+    const alternateWorkspaceDir = path.join(rootDir, "alternate-workspace");
+    await mkdir(alternateWorkspaceDir, { recursive: true });
 
     await execute({
       runId: "run-1",
@@ -100,7 +122,27 @@ describe("codex remote execution", () => {
         paperclipWorkspace: {
           cwd: workspaceDir,
           source: "project_primary",
+          strategy: "git_worktree",
+          workspaceId: "workspace-1",
+          repoUrl: "https://github.com/paperclipai/paperclip.git",
+          repoRef: "main",
+          branchName: "feature/remote-codex",
+          worktreePath: workspaceDir,
         },
+        paperclipWorkspaces: [
+          {
+            workspaceId: "workspace-1",
+            cwd: workspaceDir,
+            repoUrl: "https://github.com/paperclipai/paperclip.git",
+            repoRef: "main",
+          },
+          {
+            workspaceId: "workspace-2",
+            cwd: alternateWorkspaceDir,
+            repoUrl: "https://github.com/paperclipai/paperclip.git",
+            repoRef: "feature/other",
+          },
+        ],
       },
       executionTransport: {
         remoteExecution: {
@@ -120,12 +162,12 @@ describe("codex remote execution", () => {
     expect(prepareWorkspaceForSshExecution).toHaveBeenCalledTimes(1);
     expect(prepareWorkspaceForSshExecution).toHaveBeenCalledWith(expect.objectContaining({
       localDir: workspaceDir,
-      remoteDir: "/remote/workspace",
+      remoteDir: managedRemoteWorkspace,
     }));
     expect(syncDirectoryToSsh).toHaveBeenCalledTimes(1);
     expect(syncDirectoryToSsh).toHaveBeenCalledWith(expect.objectContaining({
       localDir: codexHomeDir,
-      remoteDir: "/remote/workspace/.paperclip-runtime/codex/home",
+      remoteDir: `${managedRemoteWorkspace}/.paperclip-runtime/codex/home`,
       followSymlinks: true,
     }));
 
@@ -133,12 +175,31 @@ describe("codex remote execution", () => {
     const call = runChildProcess.mock.calls[0] as unknown as
       | [string, string, string[], { env: Record<string, string>; remoteExecution?: { remoteCwd: string } | null }]
       | undefined;
-    expect(call?.[3].env.CODEX_HOME).toBe("/remote/workspace/.paperclip-runtime/codex/home");
-    expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");
+    expect(call?.[2]).not.toContain("--skip-git-repo-check");
+    expect(call?.[3].env.CODEX_HOME).toBe(`${managedRemoteWorkspace}/.paperclip-runtime/codex/home`);
+    expect(call?.[3].env.PAPERCLIP_WORKSPACE_CWD).toBe(managedRemoteWorkspace);
+    expect(call?.[3].env.PAPERCLIP_WORKSPACE_WORKTREE_PATH).toBeUndefined();
+    expect(JSON.parse(call?.[3].env.PAPERCLIP_WORKSPACES_JSON ?? "[]")).toEqual([
+      {
+        workspaceId: "workspace-1",
+        cwd: managedRemoteWorkspace,
+        repoUrl: "https://github.com/paperclipai/paperclip.git",
+        repoRef: "main",
+      },
+      {
+        workspaceId: "workspace-2",
+        repoUrl: "https://github.com/paperclipai/paperclip.git",
+        repoRef: "feature/other",
+      },
+    ]);
+    expect(call?.[3].env.PAPERCLIP_API_URL).toBe("http://127.0.0.1:4310");
+    expect(call?.[3].env.PAPERCLIP_API_BRIDGE_MODE).toBe("queue_v1");
+    expect(call?.[3].remoteExecution?.remoteCwd).toBe(managedRemoteWorkspace);
+    expect(startAdapterExecutionTargetPaperclipBridge).toHaveBeenCalledTimes(1);
     expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledTimes(1);
     expect(restoreWorkspaceFromSshExecution).toHaveBeenCalledWith(expect.objectContaining({
       localDir: workspaceDir,
-      remoteDir: "/remote/workspace",
+      remoteDir: managedRemoteWorkspace,
     }));
   });
 
@@ -210,6 +271,7 @@ describe("codex remote execution", () => {
     cleanupDirs.push(rootDir);
     const workspaceDir = path.join(rootDir, "workspace");
     const codexHomeDir = path.join(rootDir, "codex-home");
+    const managedRemoteWorkspace = "/remote/workspace/.paperclip-runtime/runs/run-ssh-resume/workspace";
     await mkdir(workspaceDir, { recursive: true });
     await mkdir(codexHomeDir, { recursive: true });
     await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");
@@ -227,13 +289,13 @@ describe("codex remote execution", () => {
         sessionId: "session-123",
         sessionParams: {
           sessionId: "session-123",
-          cwd: "/remote/workspace",
+          cwd: managedRemoteWorkspace,
           remoteExecution: {
             transport: "ssh",
             host: "127.0.0.1",
             port: 2222,
             username: "fixture",
-            remoteCwd: "/remote/workspace",
+            remoteCwd: managedRemoteWorkspace,
           },
         },
         sessionDisplayId: "session-123",
@@ -282,6 +344,7 @@ describe("codex remote execution", () => {
     cleanupDirs.push(rootDir);
     const workspaceDir = path.join(rootDir, "workspace");
     const codexHomeDir = path.join(rootDir, "codex-home");
+    const managedRemoteWorkspace = "/remote/workspace/.paperclip-runtime/runs/run-target/workspace";
     await mkdir(workspaceDir, { recursive: true });
     await mkdir(codexHomeDir, { recursive: true });
     await writeFile(path.join(codexHomeDir, "auth.json"), "{}", "utf8");
@@ -299,13 +362,13 @@ describe("codex remote execution", () => {
         sessionId: "session-123",
         sessionParams: {
           sessionId: "session-123",
-          cwd: "/remote/workspace",
+          cwd: managedRemoteWorkspace,
           remoteExecution: {
             transport: "ssh",
             host: "127.0.0.1",
             port: 2222,
             username: "fixture",
-            remoteCwd: "/remote/workspace",
+            remoteCwd: managedRemoteWorkspace,
           },
         },
         sessionDisplayId: "session-123",
@@ -353,7 +416,7 @@ describe("codex remote execution", () => {
       "session-123",
       "-",
     ]);
-    expect(call?.[3].env.CODEX_HOME).toBe("/remote/workspace/.paperclip-runtime/codex/home");
-    expect(call?.[3].remoteExecution?.remoteCwd).toBe("/remote/workspace");
+    expect(call?.[3].env.CODEX_HOME).toBe(`${managedRemoteWorkspace}/.paperclip-runtime/codex/home`);
+    expect(call?.[3].remoteExecution?.remoteCwd).toBe(managedRemoteWorkspace);
   });
 });

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

@@ -4,15 +4,17 @@ import { fileURLToPath } from "node:url";
 import { inferOpenAiCompatibleBiller, type AdapterExecutionContext, type AdapterExecutionResult } from "@paperclipai/adapter-utils";
 import {
   adapterExecutionTargetIsRemote,
-  adapterExecutionTargetPaperclipApiUrl,
   adapterExecutionTargetRemoteCwd,
+  overrideAdapterExecutionTargetRemoteCwd,
   adapterExecutionTargetSessionIdentity,
   adapterExecutionTargetSessionMatches,
   adapterExecutionTargetUsesPaperclipBridge,
   describeAdapterExecutionTarget,
   ensureAdapterExecutionTargetCommandResolvable,
+  ensureAdapterExecutionTargetRuntimeCommandInstalled,
   prepareAdapterExecutionTargetRuntime,
   readAdapterExecutionTarget,
+  resolveAdapterExecutionTargetTimeoutSec,
   resolveAdapterExecutionTargetCommandForLogs,
   runAdapterExecutionTargetProcess,
   startAdapterExecutionTargetPaperclipBridge,
@@ -21,13 +23,14 @@ import {
   asString,
   asNumber,
   parseObject,
-  applyPaperclipWorkspaceEnv,
   buildPaperclipEnv,
   buildInvocationEnvForLogs,
   ensureAbsoluteDirectory,
   ensurePaperclipSkillSymlink,
   ensurePathInEnv,
+  refreshPaperclipWorkspaceEnvForExecution,
   readPaperclipRuntimeSkillEntries,
+  readPaperclipIssueWorkModeFromContext,
   resolvePaperclipDesiredSkillNames,
   renderTemplate,
   renderPaperclipWakePrompt,
@@ -44,6 +47,7 @@ import {
 import { pathExists, prepareManagedCodexHome, resolveManagedCodexHomeDir, resolveSharedCodexHomeDir } from "./codex-home.js";
 import { resolveCodexDesiredSkillNames } from "./skills.js";
 import { buildCodexExecArgs } from "./codex-args.js";
+import { SANDBOX_INSTALL_COMMAND } from "../index.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -331,8 +335,16 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const codexSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
   const desiredSkillNames = resolveCodexDesiredSkillNames(config, codexSkillEntries);
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+  const configuredOpenAiApiKey =
+    typeof envConfig.OPENAI_API_KEY === "string" && envConfig.OPENAI_API_KEY.trim().length > 0
+      ? envConfig.OPENAI_API_KEY.trim()
+      : null;
   const preparedManagedCodexHome =
-    configuredCodexHome ? null : await prepareManagedCodexHome(process.env, onLog, agent.companyId);
+    configuredCodexHome
+      ? null
+      : await prepareManagedCodexHome(process.env, onLog, agent.companyId, {
+          apiKey: configuredOpenAiApiKey,
+        });
   const defaultCodexHome = resolveManagedCodexHomeDir(process.env, agent.companyId);
   const effectiveCodexHome = configuredCodexHome ?? preparedManagedCodexHome ?? defaultCodexHome;
   await fs.mkdir(effectiveCodexHome, { recursive: true });
@@ -347,7 +359,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       desiredSkillNames,
     },
   );
-  const effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+  const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(
+    executionTarget,
+    asNumber(config.timeoutSec, 0),
+  );
+  const graceSec = asNumber(config.graceSec, 20);
+  let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
   const preparedExecutionTargetRuntime = executionTargetIsRemote
     ? await (async () => {
         await onLog(
@@ -355,9 +372,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
           `[paperclip] Syncing workspace and CODEX_HOME to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
         );
         return await prepareAdapterExecutionTargetRuntime({
+          runId,
           target: executionTarget,
           adapterKey: "codex",
+          timeoutSec,
           workspaceLocalDir: cwd,
+          installCommand: SANDBOX_INSTALL_COMMAND,
+          detectCommand: command,
           assets: [
             {
               key: "home",
@@ -368,6 +389,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         });
       })()
     : null;
+  if (preparedExecutionTargetRuntime?.workspaceRemoteDir) {
+    effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir;
+  }
+  const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
+  const executionTargetIsSandbox =
+    runtimeExecutionTarget?.kind === "remote" && runtimeExecutionTarget.transport === "sandbox";
   const restoreRemoteWorkspace = preparedExecutionTargetRuntime
     ? () => preparedExecutionTargetRuntime.restoreWorkspace()
     : null;
@@ -404,9 +431,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
     : [];
   const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);
+  const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
   if (wakeTaskId) {
     env.PAPERCLIP_TASK_ID = wakeTaskId;
   }
+  if (issueWorkMode) {
+    env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
+  }
   if (wakeReason) {
     env.PAPERCLIP_WAKE_REASON = wakeReason;
   }
@@ -425,7 +456,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (wakePayloadJson) {
     env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
   }
-  applyPaperclipWorkspaceEnv(env, {
+  refreshPaperclipWorkspaceEnvForExecution({
+    env,
+    envConfig,
     workspaceCwd: effectiveWorkspaceCwd,
     workspaceSource,
     workspaceStrategy,
@@ -434,11 +467,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     workspaceRepoRef,
     workspaceBranch,
     workspaceWorktreePath,
+    workspaceHints,
     agentHome,
+    executionTargetIsRemote,
+    executionCwd: effectiveExecutionCwd,
   });
-  if (workspaceHints.length > 0) {
-    env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
-  }
   if (runtimeServiceIntents.length > 0) {
     env.PAPERCLIP_RUNTIME_SERVICE_INTENTS_JSON = JSON.stringify(runtimeServiceIntents);
   }
@@ -448,23 +481,17 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (runtimePrimaryUrl) {
     env.PAPERCLIP_RUNTIME_PRIMARY_URL = runtimePrimaryUrl;
   }
-  const targetPaperclipApiUrl = adapterExecutionTargetPaperclipApiUrl(executionTarget);
-  if (targetPaperclipApiUrl) {
-    env.PAPERCLIP_API_URL = targetPaperclipApiUrl;
-  }
-  for (const [k, v] of Object.entries(envConfig)) {
-    if (typeof v === "string") env[k] = v;
-  }
   env.CODEX_HOME = remoteCodexHome ?? effectiveCodexHome;
   if (!hasExplicitApiKey && authToken) {
     env.PAPERCLIP_API_KEY = authToken;
   }
-  if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
+  if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(runtimeExecutionTarget)) {
     paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
       runId,
-      target: executionTarget,
+      target: runtimeExecutionTarget,
       runtimeRootDir: preparedExecutionTargetRuntime?.runtimeRootDir,
       adapterKey: "codex",
+      timeoutSec,
       hostApiToken: env.PAPERCLIP_API_KEY,
       onLog,
     });
@@ -478,7 +505,22 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     ),
   );
   const billingType = resolveCodexBillingType(effectiveEnv);
-  const runtimeEnv = ensurePathInEnv(effectiveEnv);
+  const runtimeEnv = Object.fromEntries(
+    Object.entries(ensurePathInEnv(effectiveEnv)).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    ),
+  );
+  await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+    runId,
+    target: executionTarget,
+    installCommand: ctx.runtimeCommandSpec?.installCommand,
+    detectCommand: ctx.runtimeCommandSpec?.detectCommand,
+    cwd,
+    env: runtimeEnv,
+    timeoutSec,
+    graceSec,
+    onLog,
+  });
   await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv);
   const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
   const loggedEnv = buildInvocationEnvForLogs(env, {
@@ -487,9 +529,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     resolvedCommand,
   });
 
-  const timeoutSec = asNumber(config.timeoutSec, 0);
-  const graceSec = asNumber(config.graceSec, 20);
-
   const runtimeSessionParams = parseObject(runtime.sessionParams);
   const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
   const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
@@ -497,7 +536,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const canResumeSession =
     runtimeSessionId.length > 0 &&
     (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
-    adapterExecutionTargetSessionMatches(runtimeRemoteExecution, executionTarget);
+    adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
   const codexTransientFallbackMode = readCodexTransientFallbackMode(context);
   const forceSaferInvocation = fallbackModeUsesSaferInvocation(codexTransientFallbackMode);
   const forceFreshSession = fallbackModeUsesFreshSession(codexTransientFallbackMode);
@@ -614,6 +653,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     }
     return notes;
   })();
+  if (executionTargetIsSandbox) {
+    commandNotes.push(
+      "Added --skip-git-repo-check for sandbox execution because Codex requires an explicit trust bypass in headless remote workspaces.",
+    );
+  }
   const renderedPrompt = shouldUseResumeDeltaPrompt ? "" : renderTemplate(promptTemplate, templateData);
   const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
   const prompt = joinPromptSections([
@@ -636,7 +680,10 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const runAttempt = async (resumeSessionId: string | null) => {
     const execArgs = buildCodexExecArgs(
       forceSaferInvocation ? { ...config, fastMode: false } : config,
-      { resumeSessionId },
+      {
+        resumeSessionId,
+        skipGitRepoCheck: executionTargetIsSandbox,
+      },
     );
     const args = execArgs.args;
     const commandNotesWithFastMode =
@@ -660,7 +707,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
       });
     }
 
-    const proc = await runAdapterExecutionTargetProcess(runId, executionTarget, command, args, {
+    const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
       cwd,
       env,
       stdin: prompt,
@@ -713,7 +760,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
         cwd: effectiveExecutionCwd,
         ...(executionTargetIsRemote
           ? {
-              remoteExecution: adapterExecutionTargetSessionIdentity(executionTarget),
+              remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
             }
           : {}),
         ...(workspaceId ? { workspaceId } : {}),

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

@@ -0,0 +1,194 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
+
+const {
+  ensureAdapterExecutionTargetDirectory,
+  ensureAdapterExecutionTargetCommandResolvable,
+  maybeRunSandboxInstallCommand,
+  runAdapterExecutionTargetProcess,
+  describeAdapterExecutionTarget,
+  resolveAdapterExecutionTargetCwd,
+  prepareAdapterExecutionTargetRuntime,
+  prepareManagedCodexHome,
+  restoreWorkspace,
+} = vi.hoisted(() => {
+  const restoreWorkspace = vi.fn(async () => {});
+  return {
+    ensureAdapterExecutionTargetDirectory: vi.fn(async () => {}),
+    ensureAdapterExecutionTargetCommandResolvable: vi.fn(async () => {}),
+    maybeRunSandboxInstallCommand: vi.fn(async () => null),
+    runAdapterExecutionTargetProcess: vi.fn(async () => ({
+      exitCode: 0,
+      signal: null,
+      timedOut: false,
+      stdout: [
+        "{\"type\":\"thread.started\",\"thread_id\":\"thread-1\"}",
+        "{\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"hello\"}}",
+        "{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":1,\"cached_input_tokens\":0,\"output_tokens\":1}}",
+      ].join("\n"),
+      stderr: "",
+      pid: 123,
+      startedAt: new Date().toISOString(),
+    })),
+    describeAdapterExecutionTarget: vi.fn(() => "QA SSH"),
+    resolveAdapterExecutionTargetCwd: vi.fn((target, configuredCwd, fallbackCwd) => {
+      if (typeof configuredCwd === "string" && configuredCwd.trim().length > 0) return configuredCwd;
+      if (target && typeof target === "object" && "remoteCwd" in target && typeof target.remoteCwd === "string") {
+        return target.remoteCwd;
+      }
+      return fallbackCwd;
+    }),
+    prepareAdapterExecutionTargetRuntime: vi.fn(async () => ({
+      target: null,
+      workspaceRemoteDir: "/remote/workspace/.paperclip-runtime/runs/test/workspace",
+      runtimeRootDir: "/remote/workspace/.paperclip-runtime/runs/test/workspace/.paperclip-runtime/codex",
+      assetDirs: {
+        home: "/remote/workspace/.paperclip-runtime/runs/test/workspace/.paperclip-runtime/codex/home",
+      },
+      restoreWorkspace,
+    })),
+    prepareManagedCodexHome: vi.fn(async () => "/tmp/paperclip-managed-codex-home"),
+    restoreWorkspace,
+  };
+});
+
+vi.mock("@paperclipai/adapter-utils/execution-target", async () => {
+  const actual = await vi.importActual<typeof import("@paperclipai/adapter-utils/execution-target")>(
+    "@paperclipai/adapter-utils/execution-target",
+  );
+  return {
+    ...actual,
+    ensureAdapterExecutionTargetDirectory,
+    ensureAdapterExecutionTargetCommandResolvable,
+    maybeRunSandboxInstallCommand,
+    runAdapterExecutionTargetProcess,
+    describeAdapterExecutionTarget,
+    resolveAdapterExecutionTargetCwd,
+    prepareAdapterExecutionTargetRuntime,
+  };
+});
+
+vi.mock("./codex-home.js", async () => {
+  const actual = await vi.importActual<typeof import("./codex-home.js")>("./codex-home.js");
+  return {
+    ...actual,
+    prepareManagedCodexHome,
+  };
+});
+
+import { testEnvironment } from "./test.js";
+
+describe("codex remote environment diagnostics", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    delete process.env.OPENAI_API_KEY;
+  });
+
+  it("stages managed CODEX_HOME in an isolated runtime dir and keeps the probe cwd on the original remote workspace", async () => {
+    const remoteTarget: AdapterExecutionTarget = {
+      kind: "remote",
+      transport: "ssh",
+      remoteCwd: "/remote/workspace",
+      spec: {
+        host: "127.0.0.1",
+        port: 22,
+        username: "agent",
+        privateKey: "PRIVATE KEY",
+        knownHosts: "KNOWN HOSTS",
+        remoteCwd: "/remote/workspace",
+        remoteWorkspacePath: "/remote/workspace",
+        strictHostKeyChecking: false,
+      },
+    };
+
+    const result = await testEnvironment({
+      companyId: "company-1",
+      adapterType: "codex_local",
+      config: {
+        command: "codex",
+      },
+      executionTarget: remoteTarget,
+      environmentName: "QA SSH",
+    });
+
+    expect(result.status).toBe("pass");
+    expect(result.checks.some((check) => check.code === "codex_hello_probe_passed")).toBe(true);
+    expect(prepareManagedCodexHome).toHaveBeenCalledTimes(1);
+    expect(prepareAdapterExecutionTargetRuntime).toHaveBeenCalledTimes(1);
+    const runtimeCalls = prepareAdapterExecutionTargetRuntime.mock.calls as unknown as Array<[
+      {
+        workspaceLocalDir: string;
+        target?: { remoteCwd?: string };
+        workspaceRemoteDir?: string;
+      },
+    ]>;
+    const runtimeInput = runtimeCalls[0]?.[0];
+    expect(runtimeInput?.workspaceLocalDir).toContain(`${os.tmpdir()}/paperclip-codex-envtest-`);
+    expect(runtimeInput?.workspaceLocalDir).not.toBe("/remote/workspace");
+    expect(await fs.stat(runtimeInput!.workspaceLocalDir).catch(() => null)).toBeNull();
+    expect(runtimeInput?.target?.remoteCwd).toBe("/remote/workspace");
+    // `workspaceRemoteDir` is the base path passed to the runtime; the
+    // helper's per-run subdirectory is appended internally inside
+    // `prepareRemoteManagedRuntime`. Pre-building a per-run prefix here
+    // would double-nest the run id in the final path.
+    expect(runtimeInput?.workspaceRemoteDir).toBe("/remote/workspace");
+    expect(runAdapterExecutionTargetProcess).toHaveBeenCalledTimes(1);
+    const probeCall = runAdapterExecutionTargetProcess.mock.calls[0] as unknown as
+      | [string, { kind: string; remoteCwd: string }, string, string[], { cwd: string; env: Record<string, string> }]
+      | undefined;
+    expect(probeCall?.[1]).toMatchObject({
+      kind: "remote",
+      remoteCwd: "/remote/workspace",
+    });
+    expect(probeCall?.[4]).toMatchObject({
+      cwd: "/remote/workspace",
+      env: expect.objectContaining({
+        CODEX_HOME: "/remote/workspace/.paperclip-runtime/runs/test/workspace/.paperclip-runtime/codex/home",
+      }),
+    });
+    expect(restoreWorkspace).toHaveBeenCalledTimes(1);
+  });
+
+  it("avoids /tmp CODEX_HOME for remote API-key hello probes", async () => {
+    const remoteTarget: AdapterExecutionTarget = {
+      kind: "remote",
+      transport: "sandbox",
+      providerKey: "cloudflare",
+      remoteCwd: "/remote/workspace",
+      runner: {
+        execute: async () => ({
+          exitCode: 0,
+          signal: null,
+          timedOut: false,
+          stdout: "",
+          stderr: "",
+          pid: null,
+          startedAt: new Date().toISOString(),
+        }),
+      },
+    };
+
+    const result = await testEnvironment({
+      companyId: "company-1",
+      adapterType: "codex_local",
+      config: {
+        command: "codex",
+        env: {
+          OPENAI_API_KEY: "sk-test",
+        },
+      },
+      executionTarget: remoteTarget,
+      environmentName: "QA Cloudflare",
+    });
+
+    expect(result.status).toBe("pass");
+    const probeCall = runAdapterExecutionTargetProcess.mock.calls[0] as unknown as
+      | [string, AdapterExecutionTarget, string, string[], { cwd: string; env: Record<string, string> }]
+      | undefined;
+    expect(probeCall?.[4].env.CODEX_HOME).toContain("/remote/workspace/.paperclip-runtime/codex/probe-home-codex-envtest-");
+    expect(probeCall?.[4].env.CODEX_HOME?.startsWith("/tmp/")).toBe(false);
+    expect(probeCall?.[3]).toContain("--skip-git-repo-check");
+  });
+});

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

@@ -11,14 +11,20 @@ import {
 import {
   ensureAdapterExecutionTargetCommandResolvable,
   ensureAdapterExecutionTargetDirectory,
+  maybeRunSandboxInstallCommand,
   runAdapterExecutionTargetProcess,
   describeAdapterExecutionTarget,
   resolveAdapterExecutionTargetCwd,
+  prepareAdapterExecutionTargetRuntime,
 } from "@paperclipai/adapter-utils/execution-target";
+import fs from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
 import { parseCodexJsonl } from "./parse.js";
+import { SANDBOX_INSTALL_COMMAND } from "../index.js";
 import { codexHomeDir, readCodexAuthInfo } from "./quota.js";
 import { buildCodexExecArgs } from "./codex-args.js";
+import { prepareManagedCodexHome } from "./codex-home.js";
 
 function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
   if (checks.some((check) => check.level === "error")) return "fail";
@@ -55,6 +61,99 @@ function summarizeProbeDetail(stdout: string, stderr: string, parsedError: strin
 const CODEX_AUTH_REQUIRED_RE =
   /(?:not\s+logged\s+in|login\s+required|authentication\s+required|unauthorized|invalid(?:\s+or\s+missing)?\s+api(?:[_\s-]?key)?|openai[_\s-]?api[_\s-]?key|api[_\s-]?key.*required|please\s+run\s+`?codex\s+login`?)/i;
 
+async function prepareCodexHelloProbe(input: {
+  runId: string;
+  companyId: string;
+  target: AdapterEnvironmentTestContext["executionTarget"] | null;
+  targetIsRemote: boolean;
+  cwd: string;
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  probeApiKey: string | null;
+}): Promise<{
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  cleanup: () => Promise<void>;
+}> {
+  let preparedRuntime: Awaited<ReturnType<typeof prepareAdapterExecutionTargetRuntime>> | null = null;
+  let preparedRuntimeWorkspaceLocalDir: string | null = null;
+
+  const cleanup = async () => {
+    await preparedRuntime?.restoreWorkspace().catch(() => {});
+    if (preparedRuntimeWorkspaceLocalDir) {
+      await fs.rm(preparedRuntimeWorkspaceLocalDir, { recursive: true, force: true }).catch(() => {});
+    }
+  };
+
+  if (input.targetIsRemote && !input.probeApiKey) {
+    const managedHome = await prepareManagedCodexHome(process.env, async () => {}, input.companyId, {
+      apiKey: null,
+    });
+    preparedRuntimeWorkspaceLocalDir = await fs.mkdtemp(
+      path.join(os.tmpdir(), `paperclip-codex-envtest-${input.runId}-`),
+    );
+    preparedRuntime = await prepareAdapterExecutionTargetRuntime({
+      runId: input.runId,
+      target: input.target,
+      adapterKey: "codex",
+      workspaceLocalDir: preparedRuntimeWorkspaceLocalDir,
+      // Pass `input.cwd` as the base (not a pre-built per-run subdir).
+      // `prepareRemoteManagedRuntime` itself appends
+      // `.paperclip-runtime/runs/<runId>/workspace` to whatever it gets, so
+      // pre-building a per-run path here would double-nest the run ID.
+      workspaceRemoteDir: input.cwd,
+      installCommand: SANDBOX_INSTALL_COMMAND,
+      detectCommand: input.command,
+      assets: [
+        {
+          key: "home",
+          localDir: managedHome,
+          followSymlinks: true,
+        },
+      ],
+    });
+
+    return {
+      command: input.command,
+      args: input.args,
+      env: preparedRuntime.assetDirs.home
+        ? { ...input.env, CODEX_HOME: preparedRuntime.assetDirs.home }
+        : { ...input.env },
+      cleanup,
+    };
+  }
+
+  if (input.probeApiKey) {
+    const probeHome = input.targetIsRemote
+      ? path.posix.join(input.cwd, ".paperclip-runtime", "codex", `probe-home-${input.runId}`)
+      : path.join(os.tmpdir(), `paperclip-codex-probe-${input.runId}`);
+    return {
+      command: "sh",
+      args: [
+        "-c",
+        'set -e; mkdir -p "$CODEX_HOME"; umask 077; printf "%s" "$_PAPERCLIP_CODEX_AUTH_JSON" > "$CODEX_HOME/auth.json"; unset _PAPERCLIP_CODEX_AUTH_JSON; trap \'rm -rf "$CODEX_HOME"\' EXIT INT TERM; "$0" "$@"',
+        input.command,
+        ...input.args,
+      ],
+      env: {
+        ...input.env,
+        CODEX_HOME: probeHome,
+        _PAPERCLIP_CODEX_AUTH_JSON: JSON.stringify({ OPENAI_API_KEY: input.probeApiKey }),
+      },
+      cleanup,
+    };
+  }
+
+  return {
+    command: input.command,
+    args: input.args,
+    env: { ...input.env },
+    cleanup,
+  };
+}
+
 export async function testEnvironment(
   ctx: AdapterEnvironmentTestContext,
 ): Promise<AdapterEnvironmentTestResult> {
@@ -63,6 +162,7 @@ export async function testEnvironment(
   const command = asString(config.command, "codex");
   const target = ctx.executionTarget ?? null;
   const targetIsRemote = target?.kind === "remote";
+  const targetIsSandbox = target?.kind === "remote" && target.transport === "sandbox";
   const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());
   const targetLabel = targetIsRemote
     ? ctx.environmentName ?? describeAdapterExecutionTarget(target)
@@ -103,6 +203,15 @@ export async function testEnvironment(
     if (typeof value === "string") env[key] = value;
   }
   const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+  const installCheck = await maybeRunSandboxInstallCommand({
+    runId,
+    target,
+    adapterKey: "codex",
+    installCommand: SANDBOX_INSTALL_COMMAND,
+    detectCommand: command,
+    env,
+  });
+  if (installCheck) checks.push(installCheck);
   try {
     await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);
     checks.push({
@@ -163,7 +272,10 @@ export async function testEnvironment(
         hint: "Use the `codex` CLI command to run the automatic login and installation probe.",
       });
     } else {
-      const execArgs = buildCodexExecArgs({ ...config, fastMode: false });
+      const execArgs = buildCodexExecArgs(
+        { ...config, fastMode: false },
+        { skipGitRepoCheck: targetIsSandbox },
+      );
       const args = execArgs.args;
       if (execArgs.fastModeIgnoredReason) {
         checks.push({
@@ -173,64 +285,99 @@ export async function testEnvironment(
           hint: "Switch the agent model to GPT-5.4 or enter a manual model ID to enable Codex Fast mode.",
         });
       }
+      if (targetIsSandbox) {
+        checks.push({
+          code: "codex_git_repo_check_skipped",
+          level: "info",
+          message: "Added --skip-git-repo-check for sandbox hello probes.",
+          hint: "Codex requires an explicit trust bypass in headless remote sandbox workspaces.",
+        });
+      }
 
-      const probe = await runAdapterExecutionTargetProcess(
+      // Codex CLI (>= 0.122) ignores the OPENAI_API_KEY env var and only reads
+      // credentials from $CODEX_HOME/auth.json. When we have a key available,
+      // wrap the probe with a shell that materializes a per-run auth.json so
+      // the CLI can authenticate. The key content is passed via env (not on
+      // the command line) to avoid leaking it into process listings.
+      const probeApiKey = isNonEmpty(configOpenAiKey)
+        ? configOpenAiKey
+        : isNonEmpty(hostOpenAiKey)
+          ? hostOpenAiKey
+          : null;
+      const preparedProbe = await prepareCodexHelloProbe({
         runId,
+        companyId: ctx.companyId,
         target,
+        targetIsRemote,
+        cwd,
         command,
         args,
-        {
-          cwd,
-          env,
-          timeoutSec: 45,
-          graceSec: 5,
-          stdin: "Respond with hello.",
-          onLog: async () => {},
-        },
-      );
-      const parsed = parseCodexJsonl(probe.stdout);
-      const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
-      const authEvidence = `${parsed.errorMessage ?? ""}\n${probe.stdout}\n${probe.stderr}`.trim();
+        env,
+        probeApiKey,
+      });
+      try {
+        const probe = await runAdapterExecutionTargetProcess(
+          runId,
+          target,
+          preparedProbe.command,
+          preparedProbe.args,
+          {
+            cwd,
+            env: preparedProbe.env,
+            timeoutSec: 45,
+            graceSec: 5,
+            stdin: "Respond with hello.",
+            onLog: async () => {},
+          },
+        );
+        const parsed = parseCodexJsonl(probe.stdout);
+        const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
+        const authEvidence = `${parsed.errorMessage ?? ""}\n${probe.stdout}\n${probe.stderr}`.trim();
 
-      if (probe.timedOut) {
-        checks.push({
-          code: "codex_hello_probe_timed_out",
-          level: "warn",
-          message: "Codex hello probe timed out.",
-          hint: "Retry the probe. If this persists, verify Codex can run `Respond with hello` from this directory manually.",
-        });
-      } else if ((probe.exitCode ?? 1) === 0) {
-        const summary = parsed.summary.trim();
-        const hasHello = /\bhello\b/i.test(summary);
-        checks.push({
-          code: hasHello ? "codex_hello_probe_passed" : "codex_hello_probe_unexpected_output",
-          level: hasHello ? "info" : "warn",
-          message: hasHello
-            ? "Codex hello probe succeeded."
-            : "Codex probe ran but did not return `hello` as expected.",
-          ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
-          ...(hasHello
-            ? {}
-            : {
-                hint: "Try the probe manually (`codex exec --json -` then prompt: Respond with hello) to inspect full output.",
-              }),
-        });
-      } else if (CODEX_AUTH_REQUIRED_RE.test(authEvidence)) {
-        checks.push({
-          code: "codex_hello_probe_auth_required",
-          level: "warn",
-          message: "Codex CLI is installed, but authentication is not ready.",
-          ...(detail ? { detail } : {}),
-          hint: "Configure OPENAI_API_KEY in adapter env/shell or run `codex login`, then retry the probe.",
-        });
-      } else {
-        checks.push({
-          code: "codex_hello_probe_failed",
-          level: "error",
-          message: "Codex hello probe failed.",
-          ...(detail ? { detail } : {}),
-          hint: "Run `codex exec --json -` manually in this working directory and prompt `Respond with hello` to debug.",
-        });
+        if (probe.timedOut) {
+          checks.push({
+            code: "codex_hello_probe_timed_out",
+            level: "warn",
+            message: "Codex hello probe timed out.",
+            hint: "Retry the probe. If this persists, verify Codex can run `Respond with hello` from this directory manually.",
+          });
+        } else if ((probe.exitCode ?? 1) === 0) {
+          const summary = parsed.summary.trim();
+          const hasHello = /\bhello\b/i.test(summary);
+          checks.push({
+            code: hasHello ? "codex_hello_probe_passed" : "codex_hello_probe_unexpected_output",
+            level: hasHello ? "info" : "warn",
+            message: hasHello
+              ? "Codex hello probe succeeded."
+              : "Codex probe ran but did not return `hello` as expected.",
+            ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
+            ...(hasHello
+              ? {}
+              : {
+                  hint: "Try the probe manually (`codex exec --json -` then prompt: Respond with hello) to inspect full output.",
+                }),
+          });
+        } else if (CODEX_AUTH_REQUIRED_RE.test(authEvidence)) {
+          checks.push({
+            code: "codex_hello_probe_auth_required",
+            level: "warn",
+            message: "Codex CLI is installed, but authentication is not ready.",
+            ...(detail ? { detail } : {}),
+            hint: probeApiKey
+              ? "OPENAI_API_KEY was provided but Codex still rejected the request. Verify the key is valid for the OpenAI Responses API (e.g. `curl -H \"Authorization: Bearer $OPENAI_API_KEY\" https://api.openai.com/v1/models`), or run `codex login` and seed `~/.codex/auth.json`."
+              : "Codex CLI does not read OPENAI_API_KEY from the environment; set OPENAI_API_KEY in this adapter's config (so Paperclip writes it to `$CODEX_HOME/auth.json`) or run `codex login` on the host first.",
+          });
+        } else {
+          checks.push({
+            code: "codex_hello_probe_failed",
+            level: "error",
+            message: "Codex hello probe failed.",
+            ...(detail ? { detail } : {}),
+            hint: "Run `codex exec --json -` manually in this working directory and prompt `Respond with hello` to debug.",
+          });
+        }
+      } finally {
+        await preparedProbe.cleanup();
       }
     }
   }

packages/adapters/cursor-cloud/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@paperclipai/adapter-cursor-cloud",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/cursor-cloud"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./server": {
+        "types": "./dist/server/index.d.ts",
+        "import": "./dist/server/index.js"
+      },
+      "./ui": {
+        "types": "./dist/ui/index.d.ts",
+        "import": "./dist/ui/index.js"
+      },
+      "./cli": {
+        "types": "./dist/cli/index.d.ts",
+        "import": "./dist/cli/index.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@cursor/sdk": "^1.0.12",
+    "@paperclipai/adapter-utils": "workspace:*",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.7.3"
+  }
+}

packages/adapters/cursor-cloud/src/cli/format-event.ts

@@ -0,0 +1,42 @@
+import pc from "picocolors";
+import { parseCursorCloudStdoutLine } from "../ui/parse-stdout.js";
+
+export function printCursorCloudEvent(raw: string, _debug: boolean): void {
+  const entries = parseCursorCloudStdoutLine(raw, new Date().toISOString());
+  for (const entry of entries) {
+    switch (entry.kind) {
+      case "assistant":
+        console.log(pc.green(`assistant: ${entry.text}`));
+        break;
+      case "thinking":
+        console.log(pc.gray(`thinking: ${entry.text}`));
+        break;
+      case "user":
+        console.log(pc.gray(`user: ${entry.text}`));
+        break;
+      case "tool_call":
+        console.log(pc.yellow(`tool_call: ${entry.name}`));
+        break;
+      case "tool_result":
+        console.log((entry.isError ? pc.red : pc.cyan)(entry.content || "tool result"));
+        break;
+      case "result":
+        console.log((entry.isError ? pc.red : pc.blue)(`result: ${entry.subtype}${entry.text ? ` - ${entry.text}` : ""}`));
+        break;
+      case "stderr":
+        console.error(pc.red(entry.text));
+        break;
+      case "system":
+        console.log(pc.blue(entry.text));
+        break;
+      case "init":
+        console.log(pc.blue(`Cursor Cloud init (${entry.sessionId})`));
+        break;
+      case "stdout":
+        console.log(entry.text);
+        break;
+      default:
+        console.log("text" in entry ? entry.text : JSON.stringify(entry));
+    }
+  }
+}

packages/adapters/cursor-cloud/src/cli/index.ts

@@ -0,0 +1 @@
+export { printCursorCloudEvent } from "./format-event.js";