Release changelog v2026.513.0 (#5944)

## Summary

- Add `releases/v2026.513.0.md` covering the stable release range
`v2026.512.0..origin/master` (6 PRs).
- Includes one new DB migration (`0084_issue_recovery_actions`) under
the Upgrade Guide.
- No breaking changes detected; all PRs are core-maintainer commits so
the Contributors section is omitted.

## Highlights captured

- Source-scoped recovery actions
([#5599](https://github.com/paperclipai/paperclip/pull/5599))
- Blocked Inbox attention view
([#5603](https://github.com/paperclipai/paperclip/pull/5603))
- Local plugin development workflow
([#5821](https://github.com/paperclipai/paperclip/pull/5821))

## Test plan

- [ ] Reviewer confirms the highlight/improvement/fix categorization
matches release intent
- [ ] Reviewer confirms `0084_issue_recovery_actions` upgrade note is
accurate
- [ ] Reviewer signs off on `releases/v2026.513.0.md` for the stable
release cut

Generated under [PAP-9378](/PAP/issues/PAP-9378) via the
`release-changelog` skill.

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

.github/workflows/agent-runtime-images.yml

@@ -1,73 +0,0 @@
-name: Agent runtime images
-
-on:
-  push:
-    branches: [master]
-    paths:
-      - "docker/agent-runtime/**"
-      - "tools/agent-shim/**"
-      - "tools/workspace-init/**"
-      - "packages/workspace-strategy/**"
-      - ".github/workflows/agent-runtime-images.yml"
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Image version tag (e.g., v1.0.0 or dev-test)"
-        required: true
-        default: "dev"
-
-permissions:
-  contents: read
-  packages: write
-  id-token: write   # cosign keyless OIDC
-
-env:
-  REGISTRY: ghcr.io/paperclipai
-  VERSION: ${{ github.event.inputs.version || format('git-{0}', github.sha) }}
-
-jobs:
-  build-and-sign:
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Set up QEMU (multi-arch builds)
-        uses: docker/setup-qemu-action@v3
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log into GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Install cosign
-        uses: sigstore/cosign-installer@v3
-
-      - name: Build + push base + claude (multi-arch)
-        id: bake
-        run: |
-          docker buildx bake \
-            -f docker/agent-runtime/buildx-bake.hcl \
-            --set "*.platforms=linux/amd64,linux/arm64" \
-            --set "*.push=true" \
-            --metadata-file=bake-metadata.json
-          # Extract digests for cosign signing
-          BASE_DIGEST=$(jq -r '."base"."containerimage.digest"' bake-metadata.json)
-          CLAUDE_DIGEST=$(jq -r '."claude"."containerimage.digest"' bake-metadata.json)
-          echo "base_digest=$BASE_DIGEST" >> "$GITHUB_OUTPUT"
-          echo "claude_digest=$CLAUDE_DIGEST" >> "$GITHUB_OUTPUT"
-        env:
-          VERSION: ${{ env.VERSION }}
-          REGISTRY: ${{ env.REGISTRY }}
-
-      - name: Cosign sign base
-        run: |
-          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-base@${{ steps.bake.outputs.base_digest }}"
-
-      - name: Cosign sign claude
-        run: |
-          cosign sign --yes "${{ env.REGISTRY }}/agent-runtime-claude@${{ steps.bake.outputs.claude_digest }}"

.github/workflows/k8s-integration.yml

@@ -1,112 +0,0 @@
-name: K8s Integration Tests
-
-on:
-  pull_request:
-    paths:
-      - "packages/adapters/kubernetes-execution/**"
-      - "server/src/services/cluster-connections*"
-      - "server/src/services/cluster-namespace-bindings*"
-      - "server/src/services/cluster-tenant-policies*"
-      - "server/src/adapters/execution-target*"
-      - "server/src/adapters/execution-targets/**"
-      - "server/src/__tests__/k8s-*"
-      - "server/vitest.integration.config.ts"
-      - ".github/workflows/k8s-integration.yml"
-  push:
-    branches: [master, main]
-    paths:
-      - "packages/adapters/kubernetes-execution/**"
-      - "server/src/services/cluster-connections*"
-      - "server/src/services/cluster-namespace-bindings*"
-      - "server/src/services/cluster-tenant-policies*"
-      - "server/src/adapters/execution-target*"
-      - "server/src/adapters/execution-targets/**"
-      - "server/src/__tests__/k8s-*"
-      - "server/vitest.integration.config.ts"
-
-jobs:
-  k8s-integration:
-    runs-on: ubuntu-latest
-    timeout-minutes: 25
-
-    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 --lockfile-only --ignore-scripts --no-frozen-lockfile
-          pnpm install --frozen-lockfile
-
-      - name: Install kind
-        run: |
-          curl -sLo /tmp/kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-amd64
-          chmod +x /tmp/kind
-          sudo mv /tmp/kind /usr/local/bin/kind
-          kind --version
-
-      - name: Install kubectl
-        # Pinned to match the kind v0.24.0 default node image (Kubernetes
-        # v1.31.x). Bump deliberately when updating kind so the client/server
-        # skew stays within the supported one-minor-version window.
-        env:
-          KUBECTL_VERSION: v1.31.0
-        run: |
-          curl -sLo /tmp/kubectl "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
-          chmod +x /tmp/kubectl
-          sudo mv /tmp/kubectl /usr/local/bin/kubectl
-          kubectl version --client
-
-      - name: Build workspace dependencies
-        run: |
-          pnpm --filter @paperclipai/adapter-utils build
-          pnpm --filter @paperclipai/execution-target-kubernetes build
-
-      - name: Run k8s-execution integration tests
-        run: pnpm --filter @paperclipai/execution-target-kubernetes test:integration
-
-      - name: Run server k8s end-to-end smoke
-        # Vitest's include patterns in vitest.integration.config.ts are relative
-        # to the cwd, not the config file path. Run from server/ so they resolve.
-        working-directory: server
-        run: pnpm exec vitest run --config vitest.integration.config.ts k8s-cli-end-to-end
-
-      # M3a: opt-in real-claude-code test. Runs only on PRs from the same
-      # repo (forks don't get secret access). Empirical measurement test is
-      # NOT in CI — operator runs it on-demand.
-      - name: Run real-claude-code integration test (gated on Anthropic key)
-        if: ${{ secrets.ANTHROPIC_API_KEY != '' && github.event.pull_request.head.repo.fork == false }}
-        env:
-          K8S_INTEGRATION: "1"
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-        working-directory: packages/adapters/kubernetes-execution
-        run: pnpm exec vitest run test/integration/claude-code-real.test.ts
-
-      - name: Collect kind cluster logs on failure
-        if: failure()
-        run: |
-          mkdir -p kind-logs
-          for c in $(kind get clusters 2>/dev/null || true); do
-            echo "=== Logs for cluster: $c ==="
-            kind export logs "./kind-logs/$c" --name "$c" || true
-          done
-
-      - name: Upload kind logs as artifact
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: kind-logs-${{ github.run_id }}
-          path: kind-logs/
-          if-no-files-found: ignore
-          retention-days: 7

.github/workflows/pr.yml

@@ -83,9 +83,7 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: |
-          pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
-          pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Typecheck workspaces whose build scripts skip TypeScript
         run: pnpm run typecheck:build-gaps
@@ -137,9 +135,7 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: |
-          pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
-          pnpm install --frozen-lockfile
+        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 }}
@@ -166,9 +162,7 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: |
-          pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
-          pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       # `release.sh` always executes its Step 2/7 workspace build, even when
       # `--skip-verify` bypasses the initial verification gate.
@@ -199,9 +193,7 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: |
-          pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
-          pnpm install --frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Install Playwright
         run: npx playwright install --with-deps chromium

Dockerfile

@@ -28,7 +28,6 @@ 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/kubernetes-execution/package.json packages/adapters/kubernetes-execution/
 COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
 COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
 COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
@@ -36,8 +35,6 @@ COPY packages/plugins/sdk/package.json packages/plugins/sdk/
 COPY --parents packages/plugins/sandbox-providers/./*/package.json packages/plugins/sandbox-providers/
 COPY packages/plugins/paperclip-plugin-fake-sandbox/package.json packages/plugins/paperclip-plugin-fake-sandbox/
 COPY packages/plugins/plugin-llm-wiki/package.json packages/plugins/plugin-llm-wiki/
-COPY packages/workspace-strategy/package.json packages/workspace-strategy/
-COPY tools/workspace-init/package.json tools/workspace-init/
 COPY patches/ patches/
 
 RUN pnpm install --frozen-lockfile

ROADMAP.md

@@ -48,32 +48,10 @@ Paperclip should support explicit review and approval stages as first-class work
 
 Paperclip needs a clearer path from solo operator to real human teams. That means shared board access, safer collaboration, and a better model for several humans supervising the same autonomous company.
 
-### 🔄 Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+### ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
 
 We want agents to run in more remote and sandboxed environments while preserving the same Paperclip control-plane model. This makes the system safer, more flexible, and more useful outside a single trusted local machine.
 
-- ✅ **Multi-tenant Kubernetes execution target — Milestone 1 (headless tenant provisioning)** — landed 2026-05-09
-  - Spec: [docs/superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md](docs/superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md)
-  - Plan: [docs/superpowers/plans/2026-05-08-paperclip-cloud-adapter-m1-plan.md](docs/superpowers/plans/2026-05-08-paperclip-cloud-adapter-m1-plan.md)
-  - Operator quickstart: [docs/k8s-execution/quickstart.md](docs/k8s-execution/quickstart.md)
-- ✅ **Multi-tenant Kubernetes execution target — Milestone 2 (agent execution end-to-end)** — landed 2026-05-09
-  - Plan: [docs/superpowers/plans/2026-05-09-paperclip-cloud-adapter-m2-plan.md](docs/superpowers/plans/2026-05-09-paperclip-cloud-adapter-m2-plan.md)
-  - Operator walkthrough: [docs/k8s-execution/agent-execution-flow.md](docs/k8s-execution/agent-execution-flow.md)
-  - Troubleshooting: [docs/k8s-execution/troubleshooting.md](docs/k8s-execution/troubleshooting.md)
-  - Ships: workspace-strategy + workspace-init, paperclip-agent-shim, agent-runtime-base / agent-runtime-claude images (multi-arch + cosign), bootstrap-token + run-JWT exchange, per-Job ephemeral Secrets, PVC builder, Job lifecycle (logs + events + cancellation), claude_local routed through Kubernetes target.
-
-#### M3 — Production hardening + UI (next)
-
-- [ ] Web UI: cluster connection management, namespace bindings, tenant policy editing.
-- [ ] Web UI: live run dashboard with log tail and event timeline.
-- [ ] Real claude-code end-to-end (replaces M2's fake-agent integration test).
-- [ ] Real `issueGitCredentials` plumbing (GitHub App or per-tenant deploy token).
-- [ ] Empirical resource defaults from real claude_local runs (closes Risk #4).
-- [ ] Per-tenant Cilium policies fully wired.
-- [ ] Cross-replica rate-limit store (Redis or fronting proxy) — current limiter is per-replica.
-- [ ] Cross-cluster TokenReview (defer to V2, but track here).
-- [ ] Operator-controlled image allow-lists per cluster.
-
 ### ⚪ Artifacts & Work Products
 
 Paperclip should make outputs first-class. That means generated artifacts, previews, deployable outputs, and the handoff from "agent did work" to "here is the result" should become more visible and easier to operate.

cli/package.json

@@ -48,7 +48,6 @@
     "@paperclipai/adapter-openclaw-gateway": "workspace:*",
     "@paperclipai/adapter-utils": "workspace:*",
     "@paperclipai/db": "workspace:*",
-    "@paperclipai/execution-target-kubernetes": "workspace:*",
     "@paperclipai/server": "workspace:*",
     "@paperclipai/shared": "workspace:*",
     "drizzle-orm": "0.45.2",

cli/src/commands/cluster-cmd.ts

@@ -1,201 +0,0 @@
-/**
- * CLI wiring for `paperclipai cluster <subcommand>`.
- *
- * Bridges Commander with the pure createClusterCommand() factory,
- * constructing real service deps from DB + Kubernetes lazily on demand.
- *
- * Service-access pattern: direct DB (no HTTP routes exist yet for cluster ops).
- */
-
-import type { Command } from "commander";
-import { eq } from "drizzle-orm";
-import { createDb, companies } from "@paperclipai/db";
-import { clusterConnectionsService } from "@paperclipai/server/services/cluster-connections";
-import { clusterTenantPoliciesService } from "@paperclipai/server/services/cluster-tenant-policies";
-import { clusterNamespaceBindingsService } from "@paperclipai/server/services/cluster-namespace-bindings";
-import { createKubernetesExecutionDriver } from "@paperclipai/execution-target-kubernetes";
-import { getSecretProvider } from "@paperclipai/server/secrets/provider-registry";
-import { readConfig } from "../config/store.js";
-import { createClusterCommand, deriveCompanySlug } from "./cluster.js";
-
-function resolveDbUrl(configPath?: string): string {
-  if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
-  const config = readConfig(configPath);
-  if (config?.database.mode === "postgres" && config.database.connectionString) {
-    return config.database.connectionString;
-  }
-  const port = config?.database.embeddedPostgresPort ?? 54329;
-  return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-}
-
-function buildDeps(opts: { config?: string }) {
-  const db = createDb(resolveDbUrl(opts.config));
-
-  const connsSvc = clusterConnectionsService(db, {
-    resolveSecret: async (ref) => {
-      const provider = getSecretProvider(ref.provider as Parameters<typeof getSecretProvider>[0]);
-      return provider.resolveVersion({ material: {}, externalRef: ref.name });
-    },
-  });
-
-  const driver = createKubernetesExecutionDriver({
-    resolveConnection: (id: string) => connsSvc.resolve(id),
-  });
-
-  return {
-    clusterConnections: connsSvc,
-    tenantPolicies: clusterTenantPoliciesService(db),
-    driver,
-    companies: {
-      async getById(id: string) {
-        const [row] = await db.select().from(companies).where(eq(companies.id, id));
-        if (!row) return null;
-        return {
-          id: row.id,
-          name: row.name,
-          slug: deriveCompanySlug(row.name),
-        };
-      },
-    },
-    namespaceBindings: clusterNamespaceBindingsService(db),
-    print: (line: string) => console.log(line),
-  };
-}
-
-export function registerClusterCommands(program: Command): void {
-  const clusterCmd = program
-    .command("cluster")
-    .description("Manage Kubernetes cluster connections and tenant provisioning")
-    .option("-c, --config <path>", "Path to config file")
-    .option("-d, --data-dir <path>", "Paperclip data directory root");
-
-  clusterCmd
-    .command("add")
-    .description("Register a new cluster connection")
-    .requiredOption("--label <name>", "Human-readable label")
-    .requiredOption("--kind <kind>", "Connection kind: in-cluster | kubeconfig")
-    .option("--kubeconfig-secret <ref>", "Secret reference in <provider>:<name> format")
-    .option("--paperclip-public-url <url>", "Public URL of this Paperclip instance")
-    .option("--image-registry <url>", "Container image registry URL")
-    .action(async (opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const args = [
-        "add",
-        "--label", opts.label,
-        "--kind", opts.kind,
-        ...(opts.kubeconfigSecret ? ["--kubeconfig-secret", opts.kubeconfigSecret] : []),
-        ...(opts.paperclipPublicUrl ? ["--paperclip-public-url", opts.paperclipPublicUrl] : []),
-        ...(opts.imageRegistry ? ["--image-registry", opts.imageRegistry] : []),
-      ];
-      const code = await createClusterCommand(deps).run(args);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("list")
-    .description("List all cluster connections")
-    .action(async (_opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const code = await createClusterCommand(deps).run(["list"]);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("test <id>")
-    .description("Connect to a cluster and probe its capabilities")
-    .action(async (id, _opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const code = await createClusterCommand(deps).run(["test", id]);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("remove <id>")
-    .description("Remove a cluster connection")
-    .action(async (id, _opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const code = await createClusterCommand(deps).run(["remove", id]);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("ensure-tenant <clusterId> <companyId>")
-    .description("Provision a tenant namespace for a company on the given cluster")
-    .action(async (clusterId, companyId, _opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const code = await createClusterCommand(deps).run(["ensure-tenant", clusterId, companyId]);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("doctor <id>")
-    .description("Run M1 health checks on a cluster connection")
-    .action(async (id, _opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const code = await createClusterCommand(deps).run(["doctor", id]);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("set-git-credentials")
-    .description("Bind a git credentials secret to a cluster_tenant_policy row")
-    .requiredOption("--cluster <id>", "Cluster connection ID")
-    .requiredOption("--company <id>", "Company ID")
-    .requiredOption("--secret-id <uuid>", "Company secret UUID containing git credentials JSON")
-    .action(async (opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const args = [
-        "set-git-credentials",
-        "--cluster", opts.cluster,
-        "--company", opts.company,
-        "--secret-id", opts.secretId,
-      ];
-      const code = await createClusterCommand(deps).run(args);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("set-cilium-policy")
-    .description("Update per-tenant Cilium DNS allow-list and egress CIDRs")
-    .requiredOption("--cluster <id>", "Cluster connection ID")
-    .requiredOption("--company <id>", "Company ID")
-    .option("--cilium-dns <list>", "Comma-separated DNS allow-list (empty string clears)")
-    .option("--cilium-cidrs <list>", "Comma-separated egress CIDR list (empty string clears)")
-    .action(async (opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const args = [
-        "set-cilium-policy",
-        "--cluster", opts.cluster,
-        "--company", opts.company,
-        ...(opts.ciliumDns !== undefined ? ["--cilium-dns", opts.ciliumDns] : []),
-        ...(opts.ciliumCidrs !== undefined ? ["--cilium-cidrs", opts.ciliumCidrs] : []),
-      ];
-      const code = await createClusterCommand(deps).run(args);
-      if (code !== 0) process.exit(code);
-    });
-
-  clusterCmd
-    .command("set-image-allowlist")
-    .description("Set the per-cluster image prefix allow-list (empty clears)")
-    .requiredOption("--cluster <id>", "Cluster connection ID")
-    .option("--prefixes <list>", "Comma-separated image prefix list (empty string clears)")
-    .action(async (opts, cmd) => {
-      const globalOpts = cmd.parent?.parent?.opts() as { config?: string };
-      const deps = buildDeps(globalOpts);
-      const args = [
-        "set-image-allowlist",
-        "--cluster", opts.cluster,
-        ...(opts.prefixes !== undefined ? ["--prefixes", opts.prefixes] : []),
-      ];
-      const code = await createClusterCommand(deps).run(args);
-      if (code !== 0) process.exit(code);
-    });
-}

cli/src/commands/cluster.test.ts

@@ -1,473 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { createClusterCommand, type ClusterCommandDeps } from "./cluster.js";
-
-// ---------------------------------------------------------------------------
-// Mock helpers
-// ---------------------------------------------------------------------------
-
-const MOCK_ROW = {
-  id: "c-1",
-  label: "kind",
-  kind: "kubeconfig" as const,
-  kubeconfigSecretRef: null,
-  apiServerUrl: null,
-  defaultNamespacePrefix: "paperclip-",
-  capabilities: { cilium: false, storageClass: "standard", architectures: ["amd64"] as const },
-  paperclipPublicUrl: null,
-  imageRegistry: null,
-  allowAgentImageOverride: false,
-  imageAllowlist: [] as string[],
-  createdAt: new Date(),
-  createdBy: "x",
-};
-
-const MOCK_RESOLVED = {
-  ...MOCK_ROW,
-  kubeconfigYaml: "<yaml>",
-};
-
-function mocks(): ClusterCommandDeps {
-  return {
-    clusterConnections: {
-      create: vi.fn(async (i: { label: string }) => ({
-        ...MOCK_ROW,
-        id: "c-1",
-        label: i.label,
-      })) as any,
-      list: vi.fn(async () => [MOCK_ROW]) as any,
-      get: vi.fn(async () => MOCK_ROW) as any,
-      delete: vi.fn(async () => {}) as any,
-      resolve: vi.fn(async () => MOCK_RESOLVED) as any,
-      update: vi.fn(async () => MOCK_ROW) as any,
-    },
-    tenantPolicies: {
-      get: vi.fn(async () => null) as any,
-      upsert: vi.fn(async () => ({} as any)) as any,
-    },
-    driver: {
-      type: "kubernetes" as const,
-      validateTarget: vi.fn(async () => {}) as any,
-      ensureTenant: vi.fn(async () => ({
-        namespace: "paperclip-acme",
-        ciliumApplied: false,
-      })) as any,
-      run: vi.fn() as any,
-    },
-    companies: {
-      getById: vi.fn(async () => ({ id: "co-1", name: "Acme Corp", slug: "acme" })),
-    },
-    namespaceBindings: {
-      record: vi.fn(async () => {}),
-    },
-    print: (s: string) => out.push(s),
-  };
-}
-
-let out: string[];
-
-beforeEach(() => {
-  out = [];
-});
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe("cluster commands", () => {
-  it("add: creates a connection and prints its id and label", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "add",
-      "--label", "kind",
-      "--kind", "kubeconfig",
-      "--kubeconfig-secret", "local_encrypted:my-cfg",
-    ]);
-    expect(code).toBe(0);
-    expect(out.join("\n")).toContain("c-1");
-    expect(m.clusterConnections.create).toHaveBeenCalled();
-    // kubeconfig-secret parsed correctly
-    const arg = (m.clusterConnections.create as any).mock.calls[0][0];
-    expect(arg.kubeconfigSecretRef).toEqual({ provider: "local_encrypted", name: "my-cfg" });
-  });
-
-  it("add: returns non-zero when --label is missing", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["add", "--kind", "kubeconfig"]);
-    expect(code).not.toBe(0);
-    expect(m.clusterConnections.create).not.toHaveBeenCalled();
-  });
-
-  it("add: returns non-zero when --kind is invalid", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["add", "--label", "x", "--kind", "nomad"]);
-    expect(code).not.toBe(0);
-  });
-
-  it("add: passes --cilium / --storage-class / --arch through to capabilities", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "add",
-      "--label", "prod-eks",
-      "--kind", "kubeconfig",
-      "--kubeconfig-secret", "aws_secrets:prod",
-      "--cilium",
-      "--storage-class", "gp3",
-      "--arch", "amd64,arm64",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.clusterConnections.create as any).mock.calls[0][0];
-    expect(arg.capabilities).toEqual({
-      cilium: true,
-      storageClass: "gp3",
-      architectures: ["amd64", "arm64"],
-    });
-  });
-
-  it("add: defaults capabilities to single-arch x86 without Cilium when no flags are passed", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "add",
-      "--label", "kind",
-      "--kind", "kubeconfig",
-      "--kubeconfig-secret", "local_encrypted:my-cfg",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.clusterConnections.create as any).mock.calls[0][0];
-    expect(arg.capabilities).toEqual({
-      cilium: false,
-      storageClass: "standard",
-      architectures: ["amd64"],
-    });
-  });
-
-  it("add: rejects --arch with an unsupported value", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "add",
-      "--label", "x",
-      "--kind", "kubeconfig",
-      "--kubeconfig-secret", "local_encrypted:y",
-      "--arch", "ppc64le",
-    ]);
-    expect(code).not.toBe(0);
-    expect(m.clusterConnections.create).not.toHaveBeenCalled();
-  });
-
-  it("list: prints connections with capabilities", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["list"]);
-    expect(code).toBe(0);
-    const printed = out.join("\n");
-    expect(printed).toContain("kind");
-    expect(printed).toContain("standard");
-    expect(printed).toContain("amd64");
-  });
-
-  it("list: prints a message when there are no connections", async () => {
-    const m = mocks();
-    (m.clusterConnections.list as any).mockResolvedValue([]);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["list"]);
-    expect(code).toBe(0);
-    expect(out.join("\n")).toMatch(/no cluster/i);
-  });
-
-  it("test: prints resolved connection details", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["test", "c-1"]);
-    expect(code).toBe(0);
-    const printed = out.join("\n");
-    expect(printed).toMatch(/ok/i);
-    expect(printed).toContain("standard");
-    expect(printed).toContain("amd64");
-  });
-
-  it("test: returns non-zero when connection is not found", async () => {
-    const m = mocks();
-    (m.clusterConnections.resolve as any).mockResolvedValue(null);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["test", "c-missing"]);
-    expect(code).not.toBe(0);
-    expect(out.join("\n")).toMatch(/not found/i);
-  });
-
-  it("ensure-tenant: calls driver.ensureTenant, records the binding, and prints the namespace", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["ensure-tenant", "c-1", "co-1"]);
-    expect(code).toBe(0);
-    expect(out.join("\n")).toContain("paperclip-acme");
-    expect(m.driver.ensureTenant).toHaveBeenCalled();
-    expect(m.namespaceBindings.record).toHaveBeenCalledWith({
-      clusterConnectionId: "c-1",
-      companyId: "co-1",
-      namespaceName: "paperclip-acme",
-    });
-  });
-
-  it("ensure-tenant: passes slug from company object to driver", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    await cmd.run(["ensure-tenant", "c-1", "co-1"]);
-    const arg = (m.driver.ensureTenant as any).mock.calls[0][0];
-    expect(arg.company.slug).toBe("acme");
-  });
-
-  it("ensure-tenant: returns non-zero exit code when company is not found", async () => {
-    const m = mocks();
-    (m.companies.getById as any).mockResolvedValue(null);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["ensure-tenant", "c-1", "co-missing"]);
-    expect(code).not.toBe(0);
-    expect(out.join("\n")).toMatch(/not found/i);
-    expect(m.driver.ensureTenant).not.toHaveBeenCalled();
-    expect(m.namespaceBindings.record).not.toHaveBeenCalled();
-  });
-
-  it("ensure-tenant: returns non-zero when args are missing", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["ensure-tenant", "c-1"]);
-    expect(code).not.toBe(0);
-  });
-
-  it("remove: calls clusterConnections.delete", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["remove", "c-1"]);
-    expect(code).toBe(0);
-    expect(m.clusterConnections.delete).toHaveBeenCalledWith("c-1");
-  });
-
-  it("remove: returns non-zero when id is missing", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["remove"]);
-    expect(code).not.toBe(0);
-  });
-
-  it("doctor: validates connection, probes capabilities, prints results", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["doctor", "c-1"]);
-    expect(code).toBe(0);
-    const printed = out.join("\n");
-    expect(printed).toMatch(/storageClass|cilium|amd64/i);
-    expect(printed).toContain("ClusterRole");
-  });
-
-  it("doctor: returns non-zero when connection is not found", async () => {
-    const m = mocks();
-    (m.clusterConnections.resolve as any).mockResolvedValue(null);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["doctor", "c-missing"]);
-    expect(code).not.toBe(0);
-    expect(out.join("\n")).toMatch(/not found/i);
-  });
-
-  it("doctor: returns non-zero when id is missing", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["doctor"]);
-    expect(code).not.toBe(0);
-  });
-
-  it("unknown subcommand: non-zero exit and usage hint", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["nonsense"]);
-    expect(code).not.toBe(0);
-    expect(out.join("\n")).toMatch(/usage|cluster/i);
-  });
-
-  it("no subcommand: non-zero exit and usage hint", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([]);
-    expect(code).not.toBe(0);
-    expect(out.join("\n")).toMatch(/usage|cluster/i);
-  });
-
-  it("set-git-credentials: writes gitCredentialsSecretId on the tenant policy", async () => {
-    const m = mocks();
-    (m.tenantPolicies.upsert as any).mockResolvedValue({
-      clusterConnectionId: "c-1",
-      companyId: "co-1",
-      quota: null, limitRange: null,
-      additionalAllowFqdns: [],
-      imageOverrides: null,
-      gitCredentialsSecretId: "11111111-1111-1111-1111-111111111111",
-      ciliumDnsAllowlist: [],
-      ciliumEgressCidrs: [],
-      httpProxyUrl: null,
-    });
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-git-credentials",
-      "--cluster", "c-1",
-      "--company", "co-1",
-      "--secret-id", "11111111-1111-1111-1111-111111111111",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.tenantPolicies.upsert as any).mock.calls[0][0];
-    expect(arg.gitCredentialsSecretId).toBe("11111111-1111-1111-1111-111111111111");
-    expect(arg.clusterConnectionId).toBe("c-1");
-    expect(arg.companyId).toBe("co-1");
-  });
-
-  it("set-git-credentials: rejects a non-UUID secret-id", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-git-credentials",
-      "--cluster", "c-1",
-      "--company", "co-1",
-      "--secret-id", "not-a-uuid",
-    ]);
-    expect(code).not.toBe(0);
-    expect(m.tenantPolicies.upsert).not.toHaveBeenCalled();
-  });
-
-  it("set-cilium-policy: passes --cilium-dns and --cilium-cidrs through as arrays", async () => {
-    const m = mocks();
-    (m.tenantPolicies.upsert as any).mockResolvedValue({
-      clusterConnectionId: "c-1", companyId: "co-1",
-      quota: null, limitRange: null, additionalAllowFqdns: [], imageOverrides: null,
-      gitCredentialsSecretId: null,
-      ciliumDnsAllowlist: ["api.anthropic.com", "github.com"],
-      ciliumEgressCidrs: ["10.42.0.0/16"],
-      httpProxyUrl: null,
-    });
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-cilium-policy",
-      "--cluster", "c-1",
-      "--company", "co-1",
-      "--cilium-dns", "api.anthropic.com,github.com",
-      "--cilium-cidrs", "10.42.0.0/16",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.tenantPolicies.upsert as any).mock.calls[0][0];
-    expect(arg.ciliumDnsAllowlist).toEqual(["api.anthropic.com", "github.com"]);
-    expect(arg.ciliumEgressCidrs).toEqual(["10.42.0.0/16"]);
-    expect(arg.clusterConnectionId).toBe("c-1");
-    expect(arg.companyId).toBe("co-1");
-  });
-
-  it("set-cilium-policy: trims and ignores empty entries in comma lists", async () => {
-    const m = mocks();
-    (m.tenantPolicies.upsert as any).mockResolvedValue({
-      clusterConnectionId: "c-1", companyId: "co-1",
-      quota: null, limitRange: null, additionalAllowFqdns: [], imageOverrides: null,
-      gitCredentialsSecretId: null,
-      ciliumDnsAllowlist: ["api.anthropic.com"],
-      ciliumEgressCidrs: [],
-      httpProxyUrl: null,
-    });
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-cilium-policy",
-      "--cluster", "c-1",
-      "--company", "co-1",
-      "--cilium-dns", " api.anthropic.com , , ",
-      "--cilium-cidrs", "",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.tenantPolicies.upsert as any).mock.calls[0][0];
-    expect(arg.ciliumDnsAllowlist).toEqual(["api.anthropic.com"]);
-    expect(arg.ciliumEgressCidrs).toEqual([]);
-  });
-
-  it("set-cilium-policy: omits a flag entirely → preserve-on-omit (field undefined)", async () => {
-    const m = mocks();
-    (m.tenantPolicies.upsert as any).mockResolvedValue({
-      clusterConnectionId: "c-1", companyId: "co-1",
-      quota: null, limitRange: null, additionalAllowFqdns: [], imageOverrides: null,
-      gitCredentialsSecretId: null,
-      ciliumDnsAllowlist: [], ciliumEgressCidrs: [], httpProxyUrl: null,
-    });
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-cilium-policy",
-      "--cluster", "c-1",
-      "--company", "co-1",
-      "--cilium-dns", "api.anthropic.com",
-      // --cilium-cidrs omitted entirely
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.tenantPolicies.upsert as any).mock.calls[0][0];
-    expect(arg.ciliumDnsAllowlist).toEqual(["api.anthropic.com"]);
-    // Undefined → service preserves existing on upsert (Task 2 semantics).
-    expect(arg.ciliumEgressCidrs).toBeUndefined();
-  });
-
-  it("set-cilium-policy: errors out if --cluster or --company is missing", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["set-cilium-policy", "--cluster", "c-1"]);
-    expect(code).not.toBe(0);
-    expect(m.tenantPolicies.upsert).not.toHaveBeenCalled();
-  });
-
-  it("set-image-allowlist: passes --prefixes through as a string array", async () => {
-    const m = mocks();
-    (m.clusterConnections.update as any) = vi.fn(async () => MOCK_ROW);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-image-allowlist",
-      "--cluster", "c-1",
-      "--prefixes", "ghcr.io/paperclipai/,internal.acme.com/agents/",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.clusterConnections.update as any).mock.calls[0];
-    expect(arg[0]).toBe("c-1");
-    expect(arg[1].imageAllowlist).toEqual([
-      "ghcr.io/paperclipai/",
-      "internal.acme.com/agents/",
-    ]);
-  });
-
-  it("set-image-allowlist: empty --prefixes clears the list", async () => {
-    const m = mocks();
-    (m.clusterConnections.update as any) = vi.fn(async () => MOCK_ROW);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-image-allowlist",
-      "--cluster", "c-1",
-      "--prefixes", "",
-    ]);
-    expect(code).toBe(0);
-    const arg = (m.clusterConnections.update as any).mock.calls[0];
-    expect(arg[1].imageAllowlist).toEqual([]);
-  });
-
-  it("set-image-allowlist: errors when --cluster missing", async () => {
-    const m = mocks();
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run(["set-image-allowlist", "--prefixes", "x/"]);
-    expect(code).not.toBe(0);
-  });
-
-  it("set-image-allowlist: errors when the cluster id does not match a row", async () => {
-    // update() returns null when no row matches. Without the not-found
-    // check, an operator with a stale id would see "Updated …" while
-    // nothing was persisted.
-    const m = mocks();
-    (m.clusterConnections.update as any) = vi.fn(async () => null);
-    const cmd = createClusterCommand(m);
-    const code = await cmd.run([
-      "set-image-allowlist",
-      "--cluster", "missing",
-      "--prefixes", "ghcr.io/paperclipai/",
-    ]);
-    expect(code).toBe(1);
-  });
-});

cli/src/commands/cluster.ts

@@ -1,527 +0,0 @@
-/**
- * paperclipai cluster <subcommand>
- *
- * Subcommands:
- *   add           --label <name> --kind <in-cluster|kubeconfig>
- *                 [--kubeconfig-secret <provider:name>]
- *                 [--paperclip-public-url <url>]
- *                 [--image-registry <url>]
- *   list
- *   test          <id>
- *   remove        <id>
- *   ensure-tenant <clusterId> <companyId>
- *   doctor        <id>
- *
- * Service-access pattern: direct DB (no HTTP server routes exist yet for cluster operations).
- *
- * The ClusterCommandDeps interface is injected so all logic is fully unit-testable
- * without real DB or Kubernetes connectivity.
- */
-
-import type {
-  ClusterCapabilities,
-  ResolvedClusterConnection,
-  TenantPolicy as KubernetesTenantPolicy,
-} from "@paperclipai/execution-target-kubernetes";
-
-// ---------------------------------------------------------------------------
-// Dependency interfaces (mirroring the real service shapes without importing
-// from server sub-paths that don't exist in the package exports map)
-// ---------------------------------------------------------------------------
-
-export type ClusterKind = "in-cluster" | "kubeconfig";
-
-export interface ClusterConnectionRow {
-  id: string;
-  label: string;
-  kind: ClusterKind;
-  kubeconfigSecretRef: { provider: string; name: string } | null;
-  apiServerUrl: string | null;
-  defaultNamespacePrefix: string;
-  capabilities: ClusterCapabilities;
-  paperclipPublicUrl: string | null;
-  imageRegistry: string | null;
-  allowAgentImageOverride: boolean;
-  imageAllowlist: string[];
-  createdAt: Date;
-  createdBy: string;
-}
-
-export interface CreateClusterConnectionInput {
-  label: string;
-  kind: ClusterKind;
-  kubeconfigSecretRef?: { provider: string; name: string };
-  apiServerUrl?: string;
-  defaultNamespacePrefix?: string;
-  capabilities: ClusterCapabilities;
-  paperclipPublicUrl?: string;
-  imageRegistry?: string;
-  allowAgentImageOverride?: boolean;
-  createdBy: string;
-}
-
-export interface ClusterConnectionsService {
-  create(input: CreateClusterConnectionInput): Promise<ClusterConnectionRow>;
-  list(): Promise<ClusterConnectionRow[]>;
-  get(id: string): Promise<ClusterConnectionRow | null>;
-  delete(id: string): Promise<void>;
-  resolve(id: string): Promise<ResolvedClusterConnection | null>;
-  // Returns null when the id does not match a row (so the CLI's
-  // not-found guard in cmdSetImageAllowlist actually narrows the type).
-  update(id: string, input: { imageAllowlist?: string[] }): Promise<ClusterConnectionRow | null>;
-}
-
-export interface TenantPolicy {
-  quota: KubernetesTenantPolicy["quota"];
-  limitRange: KubernetesTenantPolicy["limitRange"];
-  additionalAllowFqdns: string[];
-  imageOverrides: Record<string, string> | null;
-  /** Cilium DSL: tenant-restrictive FQDN allow-list, intersected with M1 baseline. */
-  ciliumDnsAllowlist: string[];
-  /** Cilium DSL: tenant-restrictive CIDR allow-list, intersected with M1 baseline. */
-  ciliumEgressCidrs: string[];
-}
-
-export interface TenantPolicyRow extends TenantPolicy {
-  clusterConnectionId: string;
-  companyId: string;
-}
-
-export interface UpsertTenantPolicyInput {
-  clusterConnectionId: string;
-  companyId: string;
-  quota: KubernetesTenantPolicy["quota"];
-  limitRange: KubernetesTenantPolicy["limitRange"];
-  additionalAllowFqdns: string[];
-  imageOverrides: Record<string, string> | null;
-  gitCredentialsSecretId?: string;
-  ciliumDnsAllowlist?: string[];
-  ciliumEgressCidrs?: string[];
-}
-
-export interface ClusterTenantPoliciesService {
-  get(clusterConnectionId: string, companyId: string): Promise<TenantPolicyRow | null>;
-  upsert(input: UpsertTenantPolicyInput): Promise<TenantPolicyRow>;
-}
-
-export interface EnsureTenantResult {
-  namespace: string;
-  ciliumApplied: boolean;
-}
-
-export interface KubernetesDriver {
-  type: "kubernetes";
-  validateTarget(target: unknown): Promise<void>;
-  ensureTenant(input: {
-    clusterConnectionId: string;
-    company: { id: string; slug: string };
-    tenantPolicy: TenantPolicy | null;
-    driverServiceAccount: { name: string; namespace: string };
-    controlPlane: {
-      topology: "in-cluster" | "cross-cluster";
-      namespaceLabels: Record<string, string>;
-      podLabels: Record<string, string>;
-    };
-    adapterAllowFqdns: string[];
-    imagePullDockerConfigJson: string | null;
-  }): Promise<EnsureTenantResult>;
-  run(...args: unknown[]): unknown;
-}
-
-export interface CompaniesLookup {
-  getById(id: string): Promise<{ id: string; name: string; slug: string } | null>;
-}
-
-export interface NamespaceBindingsService {
-  record(input: {
-    clusterConnectionId: string;
-    companyId: string;
-    namespaceName: string;
-  }): Promise<void>;
-}
-
-export interface ClusterCommandDeps {
-  clusterConnections: ClusterConnectionsService;
-  tenantPolicies: ClusterTenantPoliciesService;
-  driver: KubernetesDriver;
-  companies: CompaniesLookup;
-  namespaceBindings: NamespaceBindingsService;
-  print: (line: string) => void;
-}
-
-export interface ClusterCommand {
-  run(argv: string[]): Promise<number>;
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-export function createClusterCommand(deps: ClusterCommandDeps): ClusterCommand {
-  return {
-    async run(argv) {
-      const [sub, ...rest] = argv;
-      switch (sub) {
-        case "add":           return cmdAdd(rest, deps);
-        case "list":          return cmdList(rest, deps);
-        case "test":          return cmdTest(rest, deps);
-        case "remove":        return cmdRemove(rest, deps);
-        case "ensure-tenant": return cmdEnsureTenant(rest, deps);
-        case "doctor":        return cmdDoctor(rest, deps);
-        case "set-git-credentials":   return cmdSetGitCredentials(rest, deps);
-        case "set-cilium-policy":     return cmdSetCiliumPolicy(rest, deps);
-        case "set-image-allowlist":   return cmdSetImageAllowlist(rest, deps);
-        default:
-          deps.print(
-            `Unknown subcommand: ${sub ?? "(none)"}\n` +
-            `Usage: cluster <add|list|test|remove|ensure-tenant|doctor|set-git-credentials|set-cilium-policy|set-image-allowlist>`,
-          );
-          return 2;
-      }
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Minimal flag parser (keeps this module free of commander/yargs deps)
-// ---------------------------------------------------------------------------
-
-function parseFlags(argv: string[]): { positional: string[]; flags: Record<string, string> } {
-  const positional: string[] = [];
-  const flags: Record<string, string> = {};
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
-      const val = argv[i + 1];
-      if (val !== undefined && !val.startsWith("--")) {
-        flags[key] = val;
-        i++;
-      } else {
-        flags[key] = "true";
-      }
-    } else {
-      positional.push(a);
-    }
-  }
-  return { positional, flags };
-}
-
-// ---------------------------------------------------------------------------
-// Derive a DNS-safe slug from company name (companies table has no slug col)
-// ---------------------------------------------------------------------------
-
-export function deriveCompanySlug(name: string): string {
-  return (
-    name
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, "-")
-      .replace(/^-+|-+$/g, "") || "company"
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Subcommand implementations
-// ---------------------------------------------------------------------------
-
-async function cmdAdd(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const { flags } = parseFlags(argv);
-  const label = flags["label"];
-  const kind = flags["kind"] as ClusterKind;
-  if (!label || !kind || (kind !== "in-cluster" && kind !== "kubeconfig")) {
-    deps.print(
-      "Usage: cluster add --label <name> --kind <in-cluster|kubeconfig> " +
-        "[--kubeconfig-secret <provider:name>] [--paperclip-public-url <url>] [--image-registry <url>] " +
-        "[--cilium] [--storage-class <name>] [--arch <amd64|arm64>] (--arch may repeat)",
-    );
-    return 2;
-  }
-
-  let kubeconfigSecretRef: { provider: string; name: string } | undefined;
-  if (flags["kubeconfig-secret"]) {
-    const colonIdx = flags["kubeconfig-secret"].indexOf(":");
-    if (colonIdx <= 0) {
-      deps.print("Invalid --kubeconfig-secret. Use <provider>:<name> (e.g. local_encrypted:my-cfg)");
-      return 2;
-    }
-    const provider = flags["kubeconfig-secret"].slice(0, colonIdx);
-    const name = flags["kubeconfig-secret"].slice(colonIdx + 1);
-    if (!name) {
-      deps.print("Invalid --kubeconfig-secret. Use <provider>:<name> (e.g. local_encrypted:my-cfg)");
-      return 2;
-    }
-    kubeconfigSecretRef = { provider, name };
-  }
-
-  const capabilities = parseCapabilityFlags(flags);
-  if (capabilities === null) {
-    deps.print("Invalid --arch. Allowed values: amd64, arm64.");
-    return 2;
-  }
-  // Defaults match the most common single-arch x86 cluster without Cilium installed.
-  // Operators must pass --cilium for clusters running Cilium so the agent
-  // egress NetworkPolicy + per-tenant CiliumNetworkPolicy actually engage.
-  // `paperclip cluster doctor` reports the detected installation so operators
-  // can verify before adding.
-
-  const created = await deps.clusterConnections.create({
-    label,
-    kind,
-    kubeconfigSecretRef,
-    paperclipPublicUrl: flags["paperclip-public-url"],
-    imageRegistry: flags["image-registry"],
-    capabilities,
-    createdBy: process.env.PAPERCLIP_CLI_USER ?? "cli",
-  });
-  deps.print(`Created cluster connection ${created.id} (${created.label})`);
-  deps.print(
-    `  capabilities: cilium=${capabilities.cilium} storageClass=${capabilities.storageClass} archs=${capabilities.architectures.join(",")}`,
-  );
-  return 0;
-}
-
-/**
- * Build a ClusterCapabilities object from CLI flags. Returns null when --arch
- * carries an unsupported value.
- */
-function parseCapabilityFlags(flags: Record<string, string>): ClusterCapabilities | null {
-  const cilium = flags["cilium"] === "true";
-  const storageClass = flags["storage-class"] ?? "standard";
-  const archRaw = flags["arch"];
-  // parseFlags only retains the last value of a repeated flag, so for
-  // multi-arch clusters the operator passes --arch as a comma list.
-  const architectures: ClusterCapabilities["architectures"] =
-    archRaw === undefined
-      ? ["amd64"]
-      : (archRaw.split(",").map((s) => s.trim()).filter(Boolean) as ClusterCapabilities["architectures"]);
-  for (const a of architectures) {
-    if (a !== "amd64" && a !== "arm64") return null;
-  }
-  if (architectures.length === 0) return null;
-  return { cilium, storageClass, architectures };
-}
-
-async function cmdList(_argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const rows = await deps.clusterConnections.list();
-  if (rows.length === 0) {
-    deps.print("No cluster connections.");
-    return 0;
-  }
-  for (const r of rows) {
-    deps.print(
-      `${r.id}\t${r.label}\t${r.kind}\t` +
-        `cilium=${r.capabilities.cilium}\t` +
-        `storageClass=${r.capabilities.storageClass}\t` +
-        `archs=${r.capabilities.architectures.join(",")}`,
-    );
-  }
-  return 0;
-}
-
-async function cmdTest(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const [id] = argv;
-  if (!id) {
-    deps.print("Usage: cluster test <id>");
-    return 2;
-  }
-  const resolved = await deps.clusterConnections.resolve(id);
-  if (!resolved) {
-    deps.print(`Cluster connection ${id} not found`);
-    return 1;
-  }
-  deps.print(`OK: connection ${id} resolves (label=${resolved.label})`);
-  deps.print(`  kind:         ${resolved.kind}`);
-  deps.print(`  cilium:       ${resolved.capabilities.cilium}`);
-  deps.print(`  storageClass: ${resolved.capabilities.storageClass}`);
-  deps.print(`  archs:        ${resolved.capabilities.architectures.join(", ")}`);
-  return 0;
-}
-
-async function cmdRemove(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const [id] = argv;
-  if (!id) {
-    deps.print("Usage: cluster remove <id>");
-    return 2;
-  }
-  await deps.clusterConnections.delete(id);
-  deps.print(`Deleted cluster connection ${id}`);
-  return 0;
-}
-
-async function cmdEnsureTenant(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const [clusterId, companyId] = argv;
-  if (!clusterId || !companyId) {
-    deps.print("Usage: cluster ensure-tenant <clusterId> <companyId>");
-    return 2;
-  }
-
-  const company = await deps.companies.getById(companyId);
-  if (!company) {
-    deps.print(`Company ${companyId} not found`);
-    return 1;
-  }
-
-  const slug = company.slug ?? deriveCompanySlug(company.name);
-
-  const tp = await deps.tenantPolicies.get(clusterId, companyId);
-
-  const result = await deps.driver.ensureTenant({
-    clusterConnectionId: clusterId,
-    company: { id: company.id, slug },
-    tenantPolicy: tp
-      ? {
-          quota: tp.quota,
-          limitRange: tp.limitRange,
-          additionalAllowFqdns: tp.additionalAllowFqdns,
-          imageOverrides: tp.imageOverrides,
-          ciliumDnsAllowlist: tp.ciliumDnsAllowlist,
-          ciliumEgressCidrs: tp.ciliumEgressCidrs,
-        }
-      : null,
-    driverServiceAccount: {
-      name: process.env.PAPERCLIP_DRIVER_SA ?? "paperclip-driver",
-      namespace: process.env.PAPERCLIP_DRIVER_NAMESPACE ?? "paperclip-system",
-    },
-    controlPlane: {
-      topology: "cross-cluster",
-      namespaceLabels: {},
-      podLabels: {},
-    },
-    adapterAllowFqdns: [],
-    imagePullDockerConfigJson: null,
-  });
-
-  await deps.namespaceBindings.record({
-    clusterConnectionId: clusterId,
-    companyId,
-    namespaceName: result.namespace,
-  });
-
-  deps.print(`Provisioned namespace ${result.namespace} (cilium=${result.ciliumApplied})`);
-  return 0;
-}
-
-async function cmdDoctor(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const [id] = argv;
-  if (!id) {
-    deps.print("Usage: cluster doctor <id>");
-    return 2;
-  }
-
-  const resolved = await deps.clusterConnections.resolve(id);
-  if (!resolved) {
-    deps.print(`Cluster connection ${id} not found`);
-    return 1;
-  }
-
-  deps.print(`Doctor report for cluster connection ${id} (${resolved.label}):`);
-  deps.print(`  kind:         ${resolved.kind}`);
-  deps.print(`  cilium:       ${resolved.capabilities.cilium}`);
-  deps.print(`  storageClass: ${resolved.capabilities.storageClass}`);
-  deps.print(`  archs:        ${resolved.capabilities.architectures.join(", ")}`);
-  deps.print("");
-  deps.print(
-    `Apply the reference ClusterRole before first ensure-tenant:\n` +
-      `  kubectl apply -f packages/adapters/kubernetes-execution/manifests/paperclip-tenant-manager-clusterrole.yaml`,
-  );
-  return 0;
-}
-
-async function cmdSetGitCredentials(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const { flags } = parseFlags(argv);
-  const clusterId = flags["cluster"];
-  const companyId = flags["company"];
-  const secretId  = flags["secret-id"];
-  if (!clusterId || !companyId || !secretId) {
-    deps.print(
-      "Usage: cluster set-git-credentials --cluster <id> --company <id> --secret-id <uuid>",
-    );
-    return 2;
-  }
-  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-  if (!UUID.test(secretId)) {
-    deps.print(`Invalid --secret-id: expected a UUID, got "${secretId}"`);
-    return 2;
-  }
-
-  const existing = await deps.tenantPolicies.get(clusterId, companyId);
-  await deps.tenantPolicies.upsert({
-    clusterConnectionId: clusterId,
-    companyId,
-    quota: existing?.quota ?? null,
-    limitRange: existing?.limitRange ?? null,
-    additionalAllowFqdns: existing?.additionalAllowFqdns ?? [],
-    imageOverrides: existing?.imageOverrides ?? null,
-    gitCredentialsSecretId: secretId,
-  });
-  deps.print(`Updated tenant policy: gitCredentialsSecretId=${secretId}`);
-  return 0;
-}
-
-async function cmdSetCiliumPolicy(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const { flags } = parseFlags(argv);
-  const clusterId = flags["cluster"];
-  const companyId = flags["company"];
-  if (!clusterId || !companyId) {
-    deps.print(
-      "Usage: cluster set-cilium-policy --cluster <id> --company <id> " +
-        "[--cilium-dns \"a.com,b.com\"] [--cilium-cidrs \"10.0.0.0/8\"]",
-    );
-    return 2;
-  }
-
-  // Comma-list parsing: split, trim, drop empty entries. Caller passing
-  // --cilium-dns "" yields [] which clears the allowlist. Omitting a flag
-  // entirely yields undefined, which the service treats as preserve-on-omit.
-  const parseList = (raw: string | undefined): string[] | undefined => {
-    if (raw === undefined) return undefined;
-    return raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  };
-  const ciliumDnsAllowlist = parseList(flags["cilium-dns"]);
-  const ciliumEgressCidrs  = parseList(flags["cilium-cidrs"]);
-
-  const existing = await deps.tenantPolicies.get(clusterId, companyId);
-  await deps.tenantPolicies.upsert({
-    clusterConnectionId: clusterId,
-    companyId,
-    quota: existing?.quota ?? null,
-    limitRange: existing?.limitRange ?? null,
-    additionalAllowFqdns: existing?.additionalAllowFqdns ?? [],
-    imageOverrides: existing?.imageOverrides ?? null,
-    ciliumDnsAllowlist,
-    ciliumEgressCidrs,
-  });
-  const dnsLabel = ciliumDnsAllowlist === undefined ? "(unchanged)" : `[${ciliumDnsAllowlist.join(", ")}]`;
-  const cidrLabel = ciliumEgressCidrs === undefined ? "(unchanged)" : `[${ciliumEgressCidrs.join(", ")}]`;
-  deps.print(`Updated tenant Cilium DSL: dns=${dnsLabel} cidrs=${cidrLabel}`);
-  return 0;
-}
-
-async function cmdSetImageAllowlist(argv: string[], deps: ClusterCommandDeps): Promise<number> {
-  const { flags } = parseFlags(argv);
-  const clusterId = flags["cluster"];
-  if (!clusterId) {
-    deps.print(
-      "Usage: cluster set-image-allowlist --cluster <id> [--prefixes \"a/,b/\"]\n" +
-        "  --prefixes \"\" clears the allow-list (default behavior).",
-    );
-    return 2;
-  }
-  const raw = flags["prefixes"] ?? "";
-  // Comma-list parsing: split, trim, drop empty entries.
-  const imageAllowlist = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  // update() returns null when the cluster id does not match a row. Without
-  // checking, an operator passing a stale id would see "Updated …" while
-  // nothing was written.
-  const updated = await deps.clusterConnections.update(clusterId, { imageAllowlist });
-  if (!updated) {
-    deps.print(`Cluster connection ${clusterId} not found`);
-    return 1;
-  }
-  if (imageAllowlist.length === 0) {
-    deps.print(`Cleared image_allowlist for cluster ${clusterId}`);
-  } else {
-    deps.print(`Updated image_allowlist for cluster ${clusterId}: ${imageAllowlist.join(", ")}`);
-  }
-  return 0;
-}

cli/src/index.ts

@@ -25,7 +25,6 @@ import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
 import { registerWorktreeCommands } from "./commands/worktree.js";
 import { registerPluginCommands } from "./commands/client/plugin.js";
 import { registerClientAuthCommands } from "./commands/client/auth.js";
-import { registerClusterCommands } from "./commands/cluster-cmd.js";
 import { cliVersion } from "./version.js";
 
 const program = new Command();
@@ -153,7 +152,6 @@ registerSecretCommands(program);
 registerWorktreeCommands(program);
 registerEnvLabCommands(program);
 registerPluginCommands(program);
-registerClusterCommands(program);
 
 const auth = program.command("auth").description("Authentication and bootstrap utilities");
 

docker/agent-runtime/Dockerfile.acpx

@@ -1,15 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-USER root
-# acpx is the ACPX wrapper that bridges to claude / codex backends.
-# Verified npm package name: "acpx" (bin 'acpx' → dist/cli.js).
-RUN npm install -g acpx@latest \
-    && chown -R 1000:1000 /usr/lib/node_modules \
-    || true
-
-USER 1000:1000
-
-# Verify the CLI is on PATH for the shim's exec.LookPath
-RUN command -v acpx >/dev/null 2>&1 || (echo "acpx not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.base

@@ -1,68 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG NODE_VERSION=22
-ARG TARGETARCH
-
-# ---------- Stage 1: build agent-shim ----------
-FROM golang:1.25-bookworm AS shim-build
-ARG TARGETARCH
-WORKDIR /src
-COPY tools/agent-shim/ ./
-RUN CGO_ENABLED=0 GOOS=linux GOARCH=${TARGETARCH:-amd64} \
-    go build -ldflags='-s -w' -o /out/paperclip-agent-shim .
-
-# ---------- Stage 2: build workspace-init (Node) ----------
-FROM node:${NODE_VERSION}-bookworm-slim AS wsinit-build
-WORKDIR /src
-COPY pnpm-lock.yaml package.json pnpm-workspace.yaml tsconfig.base.json ./
-# Repo root pnpm config has patchedDependencies referencing ./patches/* — copy
-# the patch files so `pnpm install --frozen-lockfile` does not ENOENT on them
-# even though we install zero workspaces that consume embedded-postgres.
-COPY patches/ ./patches/
-COPY packages/workspace-strategy/ ./packages/workspace-strategy/
-COPY tools/workspace-init/ ./tools/workspace-init/
-RUN corepack enable && pnpm install --frozen-lockfile \
-    && pnpm --filter @paperclipai/workspace-strategy build \
-    && pnpm --filter @paperclipai/workspace-init build \
-    # Materialize publishConfig into the live package.json so that Node's
-    # production module resolution targets dist/ instead of src/*.ts. This
-    # mirrors what `pnpm publish` does, but for our local consumption inside
-    # the runtime image where TypeScript loaders are not present.
-    && node -e "const f='packages/workspace-strategy/package.json';const p=JSON.parse(require('fs').readFileSync(f,'utf8'));if(p.publishConfig&&p.publishConfig.exports){p.exports=p.publishConfig.exports;}require('fs').writeFileSync(f,JSON.stringify(p,null,2)+'\n');"
-
-# ---------- Stage 3: runtime base image ----------
-FROM ubuntu:22.04 AS base
-ARG NODE_VERSION
-RUN apt-get update && apt-get install -y --no-install-recommends \
-      ca-certificates curl git tini gnupg \
-    && rm -rf /var/lib/apt/lists/* \
-    && curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - \
-    && apt-get install -y --no-install-recommends nodejs \
-    && apt-get clean \
-    && rm -rf /var/lib/apt/lists/* \
-    && groupadd -g 1000 paperclip \
-    && useradd -u 1000 -g 1000 -d /home/paperclip -m -s /bin/bash paperclip
-
-COPY --from=shim-build   /out/paperclip-agent-shim                          /usr/local/bin/paperclip-agent-shim
-
-# workspace-init resolves @paperclipai/workspace-strategy via a pnpm workspace
-# symlink (tools/workspace-init/node_modules/@paperclipai/workspace-strategy ->
-# ../../../../packages/workspace-strategy). Mirror the /src layout under
-# /opt/paperclip/app so Node's module resolution and that relative symlink
-# both keep working at runtime.
-COPY --from=wsinit-build /src/tools/workspace-init/package.json              /opt/paperclip/app/tools/workspace-init/package.json
-COPY --from=wsinit-build /src/tools/workspace-init/dist                      /opt/paperclip/app/tools/workspace-init/dist
-COPY --from=wsinit-build /src/tools/workspace-init/node_modules              /opt/paperclip/app/tools/workspace-init/node_modules
-COPY --from=wsinit-build /src/packages/workspace-strategy/package.json       /opt/paperclip/app/packages/workspace-strategy/package.json
-COPY --from=wsinit-build /src/packages/workspace-strategy/dist               /opt/paperclip/app/packages/workspace-strategy/dist
-COPY --from=wsinit-build /src/node_modules                                   /opt/paperclip/app/node_modules
-
-# Convenience launcher so the init container can just run `paperclip-workspace-init`
-RUN printf '#!/bin/sh\nexec node --enable-source-maps /opt/paperclip/app/tools/workspace-init/dist/index.js "$@"\n' \
-      > /usr/local/bin/paperclip-workspace-init \
-    && chmod +x /usr/local/bin/paperclip-workspace-init \
-    && mkdir -p /run/paperclip
-
-USER 1000:1000
-WORKDIR /workspace
-ENTRYPOINT ["/usr/bin/tini", "--"]
-CMD ["/usr/local/bin/paperclip-agent-shim"]

docker/agent-runtime/Dockerfile.claude

@@ -1,16 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-USER root
-RUN npm install -g @anthropic-ai/claude-code@latest \
-    && chown -R 1000:1000 /usr/lib/node_modules \
-    || true
-
-# @anthropic-ai/claude-code installs as 'claude', but the shim expects 'claude-code'
-RUN command -v claude >/dev/null 2>&1 && ln -s /usr/bin/claude /usr/bin/claude-code || true
-
-USER 1000:1000
-
-# Verify the CLI is on PATH for the shim's exec.LookPath
-RUN command -v claude-code >/dev/null 2>&1 || (echo "claude-code not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.codex

@@ -1,13 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-USER root
-RUN npm install -g @openai/codex@latest \
-    && chown -R 1000:1000 /usr/lib/node_modules \
-    || true
-
-USER 1000:1000
-
-# Verify the CLI is on PATH for the shim's exec.LookPath
-RUN command -v codex >/dev/null 2>&1 || (echo "codex not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.gemini

@@ -1,13 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-USER root
-RUN npm install -g @google/gemini-cli@latest \
-    && chown -R 1000:1000 /usr/lib/node_modules \
-    || true
-
-USER 1000:1000
-
-# Verify the CLI is on PATH for the shim's exec.LookPath
-RUN command -v gemini >/dev/null 2>&1 || (echo "gemini not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.hermes

@@ -1,17 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-# hermes_local is in the legacy sessioned-adapter set but has no upstream
-# npm package wired into Paperclip locally yet (see
-# packages/adapter-utils/src/session-compaction.ts vs the absent
-# packages/adapters/hermes-local/). This stub image preserves a cloud
-# runtime slot for hermes_local; whoever ports the hermes binary to
-# Paperclip locally adds the `npm install -g <pkg>` and the PATH check
-# to this Dockerfile.
-#
-# Until then, runs targeting hermes_local on the cloud adapter will boot
-# the container but `agent-shim` will fail with "hermes not on PATH" when
-# it tries to invoke the CLI.
-
-USER 1000:1000

docker/agent-runtime/Dockerfile.opencode

@@ -1,14 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-USER root
-# opencode-ai npm package; binary on PATH is `opencode`.
-RUN npm install -g opencode-ai@latest \
-    && chown -R 1000:1000 /usr/lib/node_modules \
-    || true
-
-USER 1000:1000
-
-# Verify the CLI is on PATH for the shim's exec.LookPath
-RUN command -v opencode >/dev/null 2>&1 || (echo "opencode not on PATH"; exit 1)

docker/agent-runtime/Dockerfile.pi

@@ -1,16 +0,0 @@
-# syntax=docker/dockerfile:1.6
-ARG BASE_TAG=dev
-FROM paperclipai/agent-runtime-base:${BASE_TAG}
-
-USER root
-# pi is the multi-provider Pi coding-agent router. Verified npm package:
-# @mariozechner/pi-coding-agent (binary 'pi' → dist/cli.js). Same package
-# is used by SANDBOX_INSTALL_COMMAND in pi-local/src/index.ts.
-RUN npm install -g @mariozechner/pi-coding-agent@latest \
-    && chown -R 1000:1000 /usr/lib/node_modules \
-    || true
-
-USER 1000:1000
-
-# Verify the CLI is on PATH for the shim's exec.LookPath
-RUN command -v pi >/dev/null 2>&1 || (echo "pi not on PATH"; exit 1)

docker/agent-runtime/README.md

@@ -1,121 +0,0 @@
-# Agent Runtime Image Family
-
-Paperclip publishes container images for remote agents. Images are named `agent-runtime-{adapterType}:{paperclipVersion}` and distributed via `ghcr.io/paperclipai/`.
-
-## Image Lineup
-
-- **`agent-runtime-base`**: Foundation. Ubuntu 22.04 + Node 22 + git + tini + non-root user + shim + workspace-init.
-- **`agent-runtime-claude`**: Extends base with `@anthropic-ai/claude-code` CLI globally installed.
-- Future: Additional adapter-specific images follow the same pattern (e.g., `agent-runtime-go`, `agent-runtime-rust`).
-
-## Base Image Contents
-
-**OS & Runtime:**
-- Ubuntu 22.04
-- Node.js 22 (via NodeSource APT repo)
-- git
-- tini (PID-1 init, ensures signal propagation)
-- Non-root user `paperclip` (uid/gid 1000)
-
-**Paperclip Binaries:**
-- `/usr/local/bin/paperclip-agent-shim` — Go binary compiled from `tools/agent-shim/`. Reads `/run/paperclip/runtime-command.json` and `syscall.Exec`s the adapter CLI.
-- `/usr/local/bin/paperclip-workspace-init` — Node script entry point. Used by init container to bootstrap the workspace.
-
-**Defaults:**
-- `USER`: 1000:1000 (paperclip, non-root)
-- `WORKDIR`: `/workspace` — PVCs are mounted here
-- `ENTRYPOINT`: `/usr/bin/tini --` (PID-1 reaper, forwards signals)
-- `CMD`: `/usr/local/bin/paperclip-agent-shim`
-
-## Building Locally
-
-### Multi-architecture (amd64 + arm64)
-
-```bash
-docker buildx bake -f docker/agent-runtime/buildx-bake.hcl --push
-```
-
-### Host-only (faster iteration)
-
-Replace the architecture with your machine's native platform:
-
-```bash
-docker buildx bake -f docker/agent-runtime/buildx-bake.hcl \
-  --set "*.platforms=linux/$(uname -m | sed s/x86_64/amd64/)" \
-  --load
-```
-
-### Custom tag or registry
-
-```bash
-docker buildx bake -f docker/agent-runtime/buildx-bake.hcl \
-  --set "*.tags=myregistry/agent-runtime-base:mytag" \
-  --load
-```
-
-## Quickstart Smoke Test
-
-Build and verify the `agent-runtime-claude` image runs locally:
-
-```bash
-docker buildx bake -f docker/agent-runtime/buildx-bake.hcl \
-  --set "*.platforms=linux/$(uname -m | sed s/x86_64/amd64/)" \
-  --load
-docker run --rm ghcr.io/paperclipai/agent-runtime-claude:dev claude-code --version
-```
-
-## Init Container (workspace-init)
-
-The init container prepares the workspace before the agent starts. It reads environment variables, bootstraps the workspace directory tree, and exits.
-
-**Environment Variables:**
-- `PAPERCLIP_WORKSPACE_REQUEST` — JSON serialized workspace request (required)
-- `PAPERCLIP_WORKSPACE_ROOT` — Where to write workspace state (default: `/workspace`)
-- `BOOTSTRAP_TOKEN` — Authentication token for workspace API (required)
-- `PAPERCLIP_PUBLIC_URL` — Public endpoint for workspace callbacks (required)
-
-**Failure Modes:**
-Missing or invalid env vars → exit code 1. Pod init never repeats; failure blocks agent startup.
-
-## Agent Container (paperclip-agent-shim)
-
-The main agent runs as the shim process (PID 1 under tini). The shim:
-
-1. Reads `/run/paperclip/runtime-command.json` — a JSON file mounted by the Job controller
-2. Parses `{ command, args, ... }` — the adapter CLI and arguments
-3. `syscall.Exec`s the adapter process, replacing itself
-4. SIGTERM from kubelet propagates directly to the adapter (no process zombie)
-
-**runtime-command.json Contract:**
-```json
-{
-  "command": "claude-code",
-  "args": ["--token", "xyz", "--workspace", "/workspace"]
-}
-```
-
-The shim makes no assumptions about command structure; it is adapter-agnostic. Future adapters swap the command/args; the image remains the same.
-
-## Security Model
-
-- **Non-root execution** — user 1000:1000, no capability grant
-- **PSS Restricted compatible** — no privileged containers, no host mounts, read-only filesystem (except `/workspace` + `/tmp`)
-- **No secrets baked in** — API tokens, credentials come from per-Job ephemeral Secrets mounted as env vars or files
-- **Image signing** — cosign keyless OIDC in CI (see Task 29)
-
-## Versioning Policy
-
-**agent-runtime-base:**
-- Version tag `vX.Y.Z` published when the shim or workspace-init source changes
-- Includes all base layer content (OS, Node, git, tini, non-root user)
-
-**agent-runtime-claude:**
-- Builds on top of base at the same version tag
-- Version tag bumps independently when a new `@anthropic-ai/claude-code` release is pinned
-- Currently uses `npm install @anthropic-ai/claude-code@latest` for the `dev` tag; CI workflow (Task 29) will pin exact semver versions per release
-
-## Multi-arch Caveats
-
-- Both amd64 and arm64 images are built in CI; local builds require `--load` on single-arch or `--push` for multi-arch
-- Go shim cross-compilation is automatic via `GOARCH` (see Dockerfile.base Stage 1)
-- Node modules are platform-agnostic; workspace-init rebuilds without issues across architectures

docker/agent-runtime/buildx-bake.hcl

@@ -1,83 +0,0 @@
-group "default" {
-  targets = ["base", "claude", "codex", "gemini", "acpx", "opencode", "pi", "hermes"]
-}
-
-variable "VERSION" { default = "dev" }
-variable "REGISTRY" { default = "ghcr.io/paperclipai" }
-
-target "base" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.base"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-base:${VERSION}"]
-}
-
-target "claude" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.claude"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-claude:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}
-
-target "codex" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.codex"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-codex:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}
-
-target "gemini" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.gemini"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-gemini:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}
-
-target "acpx" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.acpx"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-acpx:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}
-
-target "opencode" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.opencode"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-opencode:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}
-
-target "pi" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.pi"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-pi:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}
-
-target "hermes" {
-  context = "."
-  dockerfile = "docker/agent-runtime/Dockerfile.hermes"
-  platforms = ["linux/amd64", "linux/arm64"]
-  tags = ["${REGISTRY}/agent-runtime-hermes:${VERSION}"]
-  contexts = {
-    "paperclipai/agent-runtime-base:${VERSION}" = "target:base"
-  }
-}

docs/k8s-execution/CHANGELOG.md

@@ -1,76 +0,0 @@
-# K8s Execution Target Changelog
-
-## M3b — 2026-05-09
-
-Production hardening of the Kubernetes execution path:
-
-- **Cross-replica Redis rate limiting.** New `createRedisSlidingWindowLimiter` backed by an atomic `EVAL` over Redis sorted sets. Factory in `server/src/routes/k8s-callback.ts` picks the Redis-backed limiter when `PAPERCLIP_REDIS_URL` is set, otherwise falls back to the in-memory limiter (single-replica only). Documented in `security-model.md`.
-- **Per-cluster image allow-list.** New `image_allowlist text[]` column on `cluster_connections`. Driver enforces prefix-match on both the resolved adapter image and any `target.imageOverride` before launching the Job; rejects with `errorCode: "image_not_allowed"`. New CLI subcommand `paperclip cluster set-image-allowlist`.
-- **Six new cloud-runtime adapter images:** `agent-runtime-codex`, `-gemini`, `-acpx`, `-opencode`, `-pi`, `-hermes`. Each has a Dockerfile, buildx-bake target, and busybox-style smoke test. Per-adapter env keys + default FQDN allow-list live in `packages/adapters/kubernetes-execution/src/orchestrator/adapter-defaults.ts` (single source of truth used by the driver). The driver now filters the per-Job env Secret to the adapter's declared `envKeys` and merges the adapter's `allowFqdns` into `ensureTenant`, removing the need for adapter-specific knowledge in server callers.
-- **Always-hash namespace derivation.** `deriveNamespaceName` now unconditionally appends `-<8-char-base36-hash(companyId)>` to every namespace, even for short clean slugs. Previously two companies with identical slugs (e.g. both named "Acme") collided on the `cluster_namespace_bindings` unique index, which blocked Company B onboarding. Always-hash makes namespace names globally unique by construction; the M1 takeover guard remains as belt-and-suspenders.
-- **Schema migration `0085`** adds the `image_allowlist` column.
-
-`hermes_local` ships as a stub Dockerfile because no upstream npm binary is wired into Paperclip locally yet (see `Dockerfile.hermes` for the gap and path forward).
-
-## M3a — 2026-05-09
-
-Production-readiness pass on the M2 Kubernetes execution path:
-
-- **Real claude-code end-to-end test** (`test/integration/claude-code-real.test.ts`). Gated on `K8S_INTEGRATION=1` + `ANTHROPIC_API_KEY`. Builds the real `agent-runtime-claude` image, seeds a workspace PVC with a fixture repo, runs the agent against real Anthropic, asserts the project name surfaces in pod logs.
-- **Real `issueGitCredentials`** (`server/src/services/git-credentials.ts`). Replaces the M2 stub. Resolves a `company_secrets` UUID via the existing `SecretProvider` registry, returns `{username, password}` decoded from JSON. New CLI subcommand `paperclip cluster set-git-credentials`.
-- **Empirical resource defaults** (`packages/adapters/kubernetes-execution/test/integration/empirical-measurement.test.ts`). 5 sequential real-claude-code runs measured under `metrics-server`. Defaults updated only when peaks crossed M1's threshold; new sizing doc at `docs/k8s-execution/sizing.md`.
-- **Per-tenant Cilium DSL** (`packages/adapters/kubernetes-execution/src/orchestrator/cilium-tenant-policy.ts`). New columns on `cluster_tenant_policies`: `cilium_dns_allowlist` + `cilium_egress_cidrs`. `ensureTenantNamespace` emits a *second* CNP that intersects with the M1 baseline (Cilium evaluates multiple CNPs as AND). Operator recipes at `docs/k8s-execution/cilium-recipes.md`.
-
-Schema migration `0084_tenant_policy_m3a.sql` adds 3 columns (`git_credentials_secret_id`, `cilium_dns_allowlist`, `cilium_egress_cidrs`) to `cluster_tenant_policies`.
-
-## 2026-05-09 — Phase A complete
-
-Workspace strategy + realization types now live in @paperclipai/workspace-strategy.
-@paperclipai/shared re-exports them so existing callers were not modified.
-Callers may opt to migrate imports in a follow-up; this PR keeps blast radius
-to the smallest reasonable cross-section.
-
-## 2026-05-09 — Phase C: server callback routes (M2 Tasks 13–16)
-
-Three callback endpoints used by the in-cluster agent shim are now mounted in
-the Paperclip server when `PAPERCLIP_RUN_JWT_SECRET` is configured:
-
-- `POST /api/agent-auth/exchange` — bootstrap token → run JWT (HS256, 1h TTL).
-- `POST /api/runs/:runId/events` — run JWT-authed structured event ingestion;
-  events land in `heartbeat_run_events` keyed by `(runId, seq)`.
-- `POST /api/workspace/git-credentials` — run JWT-authed short-TTL git creds.
-
-Rate limits (in-memory sliding window per replica):
-- `/agent-auth/exchange`: 10/min/IP (companyId is unknown until token validates).
-- `/runs/:runId/events`: 1000/min keyed by URL `:runId`.
-- `/workspace/git-credentials`: 30/min keyed by JWT runId claim, falling back
-  to client IP if no valid JWT presented.
-
-**Deferred to M3:**
-- Live git-credentials issuance (GitHub App installation tokens, per-tenant
-  deploy tokens). M2 ships the route and auth contract; the issuer currently
-  always returns `503 not_configured`. Wiring is a single-function swap on the
-  `issueGitCredentials` dependency.
-- Distributed rate limiting. The in-memory limiter is per-replica; multi-replica
-  deployments should lift this to Redis or a fronting proxy (Envoy/NGINX).
-- `PAPERCLIP_RUN_JWT_SECRET` must be supplied as an external secret. The route
-  factory fails fast at boot if it's unset, so deployments never silently
-  generate per-restart keys (which would invalidate every in-flight JWT).
-
-## 2026-05-09 — Risk #4 (empirical resource defaults) partially resolved
-
-The empirical-measurement integration test
-(`packages/adapters/kubernetes-execution/test/integration/empirical-measurement.test.ts`)
-provisions kind + metrics-server and runs a Job under measurement. Peak CPU /
-memory are captured via `kubectl top pod` polling and written to
-`docs/k8s-execution/sizing-fake-agent.md`.
-
-**M2 ships M1 defaults unchanged.** The measured workload (busybox echo loop)
-is not representative of real claude_local — its peak memory is well under
-100 Mi vs the M1 default of 256 Mi requests / 1 Gi limit. Real claude-code
-measurement requires the M3 agent-runtime-claude image with valid Anthropic
-protocol; it will be done in M3 and the defaults updated accordingly.
-
-The infrastructure (metrics-server bootstrap, pod-metrics polling, sizing.md
-generation) is in place. M3 only needs to swap the workload, not rebuild the
-harness.

docs/k8s-execution/adapters.md

@@ -1,94 +0,0 @@
-# Cloud-runtime adapter coverage
-
-The Kubernetes execution target ships a per-adapter runtime image for each
-local adapter Paperclip supports. The image is selected at run time by
-`adapter-defaults.ts:getAdapterDefaults()`, which also lists which env keys
-the driver exposes from the per-Job Secret and which FQDNs the tenant
-NetworkPolicy + Cilium baseline must permit egress to.
-
-| Adapter type      | Runtime image                                           | Env keys                                          | Default allowed FQDNs                                                  |
-|-------------------|---------------------------------------------------------|---------------------------------------------------|------------------------------------------------------------------------|
-| `claude_local`    | `ghcr.io/paperclipai/agent-runtime-claude`              | `ANTHROPIC_API_KEY`                               | `api.anthropic.com`                                                    |
-| `codex_local`     | `ghcr.io/paperclipai/agent-runtime-codex`               | `OPENAI_API_KEY`                                  | `api.openai.com`                                                       |
-| `gemini_local`    | `ghcr.io/paperclipai/agent-runtime-gemini`              | `GEMINI_API_KEY`, `GOOGLE_API_KEY`                | `generativelanguage.googleapis.com`                                    |
-| `acpx_local`      | `ghcr.io/paperclipai/agent-runtime-acpx`                | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`             | `api.anthropic.com`, `api.openai.com`                                  |
-| `opencode_local`  | `ghcr.io/paperclipai/agent-runtime-opencode`            | `OPENAI_API_KEY`                                  | `api.openai.com`                                                       |
-| `pi_local`        | `ghcr.io/paperclipai/agent-runtime-pi`                  | `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY` | `api.anthropic.com`, `api.openai.com`, `api.x.ai`                  |
-| `hermes_local`    | `ghcr.io/paperclipai/agent-runtime-hermes` (stub)       | _(none — upstream binary not yet wired)_          | _(none — operators set via tenant policy)_                             |
-
-Unknown adapter types fall back to `agent-runtime-base` with `envKeys=[]`
-and `allowFqdns=[]` — a deliberate fail-closed default.
-
-## Env-key filtering at the driver
-
-The per-Job env Secret is populated by the server from company secrets, but
-the driver materializes only the keys declared in the adapter's
-`envKeys` list into the container environment. Extra keys passed by the
-server are silently dropped as a defence-in-depth measure: a misconfigured
-secret resolver cannot leak unrelated provider credentials into a pod that
-has no business reading them. See
-`packages/adapters/kubernetes-execution/src/driver.ts`.
-
-## Per-tenant overrides
-
-### Extending the FQDN allow-list
-
-The tenant policy carries an `additionalAllowFqdns: string[]` field that is
-merged on top of the adapter defaults; the resulting NetworkPolicy + Cilium
-baseline allows BOTH. This field is set through the tenant-policy service
-(server-side); operators tightening egress per-tenant typically use the
-Cilium DSL instead — see `docs/k8s-execution/cilium-recipes.md`:
-
-```bash
-# Restrict a tenant to Anthropic + an internal git server.
-paperclip cluster set-cilium-policy \
-  --cluster <id> --company <id> \
-  --cilium-dns "api.anthropic.com" \
-  --cilium-cidrs "10.42.0.0/16"
-```
-
-The Cilium DSL emits a *second* CiliumNetworkPolicy that intersects with
-the adapter baseline; the effective egress is strictly tighter, never
-looser.
-
-### Restricting image choices
-
-Operators can also restrict which runtime images a cluster will pull via a
-per-cluster image allow-list (prefix match):
-
-```bash
-paperclip cluster set-image-allowlist \
-  --cluster <id> \
-  --prefixes "ghcr.io/paperclipai/,registry.acme.internal/paperclip/"
-```
-
-An empty `--prefixes ""` clears the allow-list (default behaviour: no
-restriction). Rationale and threat model are in
-`docs/k8s-execution/security-model.md`.
-
-## Building the runtime images
-
-The full set of runtime images is built via Docker buildx bake:
-
-```bash
-docker buildx bake --file docker/agent-runtime/buildx-bake.hcl \
-  --set "*.platforms=linux/amd64,linux/arm64" \
-  default
-```
-
-Individual targets: `base`, `claude`, `codex`, `gemini`, `acpx`,
-`opencode`, `pi`, `hermes`.
-
-## Adding a new adapter
-
-1. Add a `Dockerfile.<adapter>` under `docker/agent-runtime/` extending
-   `agent-runtime-base`.
-2. Add the bake target in `docker/agent-runtime/buildx-bake.hcl` and
-   include it in `group "default"`.
-3. Add a `<adapter>_local: { runtimeImage, envKeys, allowFqdns }` entry to
-   `packages/adapters/kubernetes-execution/src/orchestrator/adapter-defaults.ts`.
-4. Add a unit test in
-   `packages/adapters/kubernetes-execution/src/orchestrator/adapter-defaults.test.ts`
-   and a smoke test in
-   `packages/adapters/kubernetes-execution/test/integration/<adapter>-smoke.test.ts`.
-5. Update the table above.

docs/k8s-execution/agent-execution-flow.md

@@ -1,113 +0,0 @@
----
-title: Kubernetes Execution — Agent Execution Flow
-summary: End-to-end walkthrough of what happens when an operator runs an agent against a Kubernetes-bound tenant, from CLI invocation to assistant text streaming back
----
-
-This document traces the full path of one agent run on a Kubernetes execution target. Read it after [quickstart.md](./quickstart.md) — the cluster connection and tenant namespace must already exist before any of the steps below have meaning.
-
-The artifacts referenced are real and are produced by code that ships in M2. Pointers to source files are absolute paths inside this repo.
-
-## Sequence
-
-The numbered steps below trace one `paperclip agent run` from operator keystroke to assistant text in the operator's terminal.
-
-1. **CLI invocation.** The operator runs `paperclipai agent run --agent <id> --prompt "..."`. The CLI forwards the request to the Paperclip server through its normal authenticated control-plane API.
-
-2. **Server resolves the execution target.** The server looks up the agent's `executionTargetId`. If it points at a `kubernetes:<label>` target, the request is routed to the `KubernetesExecutionDriver` (`packages/adapters/kubernetes-execution/src/driver.ts`). For a `local` target, nothing in this document applies — the agent runs as a child process on the server host.
-
-3. **Driver mints a bootstrap token.** Before any pod is created, `driver.run()` calls the configured `BootstrapTokenMinter` (server-side wiring in `server/src/services/bootstrap-tokens.ts`) to mint a single-use token bound to `(agentId, companyId, runId)`. This token never leaves the server's process memory until it is sealed into the per-Job Secret in the next step.
-
-4. **Driver materializes per-Job objects.** Inside the tenant namespace `paperclip-<companySlug>` the driver creates, in order:
-   - A `PersistentVolumeClaim` (`packages/adapters/kubernetes-execution/src/orchestrator/pvc.ts`) for the agent's `/workspace` mount.
-   - A `Secret` of type `Opaque` (`.../orchestrator/secret.ts`) carrying `BOOTSTRAP_TOKEN`, redacted adapter env, and any per-tenant credentials. The Secret is created first; the Job is created next; finally the driver patches the Secret's `ownerReferences` to point at the Job so the Secret is garbage-collected when the Job's TTL expires.
-   - A `Job` (`.../orchestrator/job.ts`) with two containers:
-     - **Init container `workspace-init`** runs `/usr/local/bin/paperclip-workspace-init` from the `agent-runtime-base` image. It executes the workspace strategy from `@paperclipai/workspace-strategy` (e.g., clones a git repo into `/workspace`).
-     - **Main container `agent`** runs `/usr/bin/tini -- /usr/local/bin/paperclip-agent-shim` from the adapter-specific image (e.g., `agent-runtime-claude`).
-
-   Every object carries the labels `paperclip.ai/managed-by=paperclip`, `paperclip.ai/company-id=<uuid>`, `paperclip.ai/agent-id=<uuid>`, and `paperclip.ai/run-id=<runUlid>`.
-
-5. **Init container clones the workspace.** `workspace-init` reads `PAPERCLIP_WORKSPACE_STRATEGY` (a JSON blob) and executes it. For a `git_clone` strategy it calls `POST /api/workspace/git-credentials` against the Paperclip server, exchanging the bootstrap token for short-lived git credentials, then clones into `/workspace`. On success, the init container exits 0.
-
-6. **Main container starts the shim.** Kubernetes brings up the `agent` container after the init container succeeds. `paperclip-agent-shim` (Go binary, `tools/agent-shim/`) reads `/run/paperclip/runtime-command.json`, calls `POST /api/agent-auth/exchange` to swap the bootstrap token for a run-scoped JWT, then `syscall.Exec`s the adapter CLI (e.g. `claude-code` for `agent-runtime-claude`).
-
-7. **Adapter runs.** The adapter (e.g. claude-code) reads the prompt from its arguments / stdin, calls Anthropic's API, and streams its assistant text to stdout. While running it may post progress events through `POST /api/runs/:runId/events` using the run JWT.
-
-8. **Server tails pod logs.** While the Job is running, `driver.run()` opens a `pods/log` follow stream (`.../orchestrator/log-stream.ts`) for the `agent` container and forwards bytes to the adapter's normal log/event sink. The CLI receives those bytes through the same control-plane channel used by local-target runs and prints them to the operator's terminal.
-
-9. **Job terminates and garbage-collects.** When the adapter exits, the Job moves to `Succeeded` (or `Failed`). The driver maps the terminal state through `failure-mapping.ts`, returns the result, and Kubernetes garbage-collects the Job, Pod, and Secret per the Job's `ttlSecondsAfterFinished`. The PVC stays unless the tenant policy says otherwise (V2 will manage PVC reuse).
-
-## Inspecting a live run with kubectl
-
-Set a shell variable to the agent's namespace and run ID once:
-
-```bash
-NS=paperclip-<companySlug>
-RUN=<runUlid>
-```
-
-Both values appear in the CLI output and on the server's run record.
-
-```bash
-# Everything for this one run
-kubectl -n "$NS" get pods,jobs,pvcs,secrets,events \
-  -l "paperclip.ai/run-id=$RUN"
-```
-
-Sample output for a healthy run mid-flight:
-
-```
-NAME                      READY   STATUS    RESTARTS   AGE
-pod/run-<runUlid>-h2x7q   1/1     Running   0          18s
-
-NAME                  COMPLETIONS   DURATION   AGE
-job.batch/run-<runUlid>   0/1       18s        18s
-
-NAME                                    STATUS   VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE
-persistentvolumeclaim/run-<runUlid>     Bound    pvc-...  10Gi       RWO            standard       19s
-
-NAME                              TYPE     DATA   AGE
-secret/run-<runUlid>              Opaque   3      19s
-
-LAST SEEN   TYPE     REASON       OBJECT                       MESSAGE
-19s         Normal   Scheduled    pod/run-<runUlid>-h2x7q      Successfully assigned ...
-18s         Normal   Pulled       pod/run-<runUlid>-h2x7q      Container image "agent-runtime-base" already present
-18s         Normal   Started      pod/run-<runUlid>-h2x7q      Started container workspace-init
-12s         Normal   Started      pod/run-<runUlid>-h2x7q      Started container agent
-```
-
-Tail the agent container's logs directly (the same bytes the server forwards to the CLI):
-
-```bash
-kubectl -n "$NS" logs -f -l "paperclip.ai/run-id=$RUN" -c agent
-```
-
-Inspect the init container's output if you suspect a workspace clone failure:
-
-```bash
-kubectl -n "$NS" logs -l "paperclip.ai/run-id=$RUN" -c workspace-init
-```
-
-Describe the Pod to see scheduling, image-pull, and resource-quota events:
-
-```bash
-kubectl -n "$NS" describe pod -l "paperclip.ai/run-id=$RUN"
-```
-
-## Run ID is the correlation key
-
-Every persisted resource (Job, Pod, PVC, Secret) carries `paperclip.ai/run-id=<runUlid>`. Server-side log lines, OpenTelemetry spans, and DB rows use the same value. When a run misbehaves, list everything by that label first:
-
-```bash
-kubectl get all,pvc,secrets -A -l "paperclip.ai/run-id=$RUN"
-```
-
-## Failures and what to look at
-
-If the `kubectl` walkthrough above shows symptoms instead of healthy output, jump to [troubleshooting.md](./troubleshooting.md) which maps each common failure mode (Pending pods, ImagePullBackOff, init failures, bootstrap rejection, OOM, timeouts) to the exact recipe that diagnoses it.
-
-## Related
-
-- [Quickstart](./quickstart.md) — set up the cluster connection and provision a tenant
-- [Security model](./security-model.md) — isolation primitives applied to every run
-- [Troubleshooting](./troubleshooting.md) — operator failure-mode playbook
-- [Multi-tenant onboarding](./multi-tenant-onboarding.md) — playbook for provisioning multiple companies

docs/k8s-execution/cilium-recipes.md

@@ -1,76 +0,0 @@
-# Cilium tenant policy recipes
-
-The per-tenant Cilium DSL (`ciliumDnsAllowlist` + `ciliumEgressCidrs`) emits a
-*second* CiliumNetworkPolicy that intersects with M1's baseline. Cilium evaluates
-multiple selecting CNPs as AND, so every rule below produces an effective egress
-that is **strictly tighter** than the M1 default — never looser.
-
-## How to apply
-
-```bash
-paperclip cluster set-cilium-policy \
-  --cluster <cluster-id> \
-  --company <company-id> \
-  --cilium-dns "api.anthropic.com,github.com" \
-  --cilium-cidrs "10.42.0.0/16"
-```
-
-Empty arrays disable the second CNP — only the M1 baseline applies.
-
-## Recipe 1: Anthropic-only tenant
-
-A tenant that should reach only Anthropic + GitHub:
-
-```bash
-paperclip cluster set-cilium-policy \
-  --cluster c-1 --company co-1 \
-  --cilium-dns "api.anthropic.com,github.com"
-```
-
-The agent can hit the Anthropic API and clone GitHub repos. All other egress
-(other LLM providers, arbitrary internet, internal infra) is dropped.
-
-## Recipe 2: Self-hosted git tenant
-
-A tenant with a self-hosted git server on an internal network:
-
-```bash
-paperclip cluster set-cilium-policy \
-  --cluster c-1 --company co-1 \
-  --cilium-dns "api.anthropic.com" \
-  --cilium-cidrs "10.42.0.0/16"
-```
-
-`api.anthropic.com` for the LLM, `10.42.0.0/16` for the git server.
-
-## Recipe 3: Block everything outside a small allowlist
-
-Locking a tenant to one LLM provider and one internal repo CIDR:
-
-```bash
-paperclip cluster set-cilium-policy \
-  --cluster c-1 --company co-1 \
-  --cilium-dns "api.anthropic.com" \
-  --cilium-cidrs "192.168.10.0/24"
-```
-
-## Footguns
-
-- **DNS resolution is preserved automatically.** The builder always emits a
-  rule allowing kube-dns; an allowlist of `["api.anthropic.com"]` does not
-  accidentally block DNS resolution for that very host.
-- **CIDR allowlists also need a port.** This is an M3a limitation — the second
-  CNP grants TCP/443 + 80 implicitly. If the tenant needs a non-standard port
-  on a CIDR, contact the operator team (M3b will add explicit port flags).
-- **Wildcards.** Use `*.linear.app` for subdomain matching. The builder emits
-  `matchPattern` for entries containing `*` and `matchName` otherwise.
-
-## Verification
-
-```bash
-kubectl --kubeconfig <kubeconfig> -n paperclip-<slug> get ciliumnetworkpolicies
-```
-
-You should see two CNPs:
-- `paperclip-agent-egress-l7` (M1 baseline)
-- `paperclip-tenant-<slug>-restrict` (M3a tenant DSL — only when the arrays are non-empty)

docs/k8s-execution/cluster-rbac.md

@@ -1,190 +0,0 @@
----
-title: Kubernetes Execution — Cluster RBAC
-summary: Reference ClusterRole for the Paperclip driver, per-rule rationale, and ServiceAccount binding templates for in-cluster and cross-cluster topologies
----
-
-The Paperclip driver needs a `ClusterRole` to provision and manage tenant namespaces across the cluster. This document explains every permission in that role, and provides binding templates for both supported topologies.
-
-## Reference ClusterRole
-
-The canonical source is `packages/adapters/kubernetes-execution/manifests/paperclip-tenant-manager-clusterrole.yaml`. Its contents are reproduced here for reference:
-
-```yaml
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: paperclip-tenant-manager
-rules:
-  - apiGroups: [""]
-    resources: ["namespaces", "resourcequotas", "limitranges", "secrets", "serviceaccounts", "configmaps", "persistentvolumeclaims", "pods", "pods/log", "pods/exec"]
-    verbs: ["get", "list", "create", "update", "patch", "delete", "watch"]
-  - apiGroups: ["batch"]
-    resources: ["jobs"]
-    verbs: ["get", "list", "create", "update", "patch", "delete", "watch"]
-  - apiGroups: ["networking.k8s.io"]
-    resources: ["networkpolicies"]
-    verbs: ["get", "list", "create", "update", "patch", "delete"]
-  - apiGroups: ["rbac.authorization.k8s.io"]
-    resources: ["roles", "rolebindings"]
-    verbs: ["get", "list", "create", "update", "patch", "delete"]
-  - apiGroups: ["cilium.io"]
-    resources: ["ciliumnetworkpolicies"]
-    verbs: ["get", "list", "create", "update", "patch", "delete"]
-```
-
-Apply it to a cluster with:
-
-```bash
-kubectl apply -f packages/adapters/kubernetes-execution/manifests/paperclip-tenant-manager-clusterrole.yaml
-```
-
-## Rule-by-rule rationale
-
-### Core API group (`apiGroups: [""]`)
-
-| Resource | Why the driver needs it |
-|----------|------------------------|
-| `namespaces` | Create and patch tenant namespaces (`paperclip-{companySlug}`). The driver reads the existing namespace to check for `paperclip.ai/managed-by=paperclip` before mutating — it will not touch namespaces it did not create. `watch` is used in M2 to track namespace deletion events. |
-| `resourcequotas` | Apply `paperclip-tenant-quota` to each namespace. Must `patch` on re-provision (quota overrides from `cluster_tenant_policies`). |
-| `limitranges` | Apply `paperclip-tenant-limits`. Must `patch` on billing tier changes. |
-| `secrets` | (a) Create `paperclip-image-pull` (registry credentials per namespace). (b) In M2: create per-Job ephemeral Secrets that hold resolved `secret_ref` values; these carry an `OwnerReference` to the Job so Kubernetes GCs them automatically. |
-| `serviceaccounts` | Create the `paperclip-agent` ServiceAccount in each namespace (`automountServiceAccountToken: false`). |
-| `configmaps` | Reserved for M2: workspace-init config and adapter configuration injection via `ConfigMap` volumes. |
-| `persistentvolumeclaims` | M2: create per-agent `PVC` (`agent-{agentSlug}-workspace`) for warm workspace storage. `watch` is needed to wait for the PVC to be bound before submitting the Job. |
-| `pods` | M2: read pod status to determine Job phase; gate on pod `Ready` condition. |
-| `pods/log` | M2: stream container logs from agent pods back to the Paperclip run log via `ctx.onLog`. |
-| `pods/exec` | M2: reserved for workspace-init debug flows and operator diagnostics. Not used in M1. |
-
-### Batch API group (`apiGroups: ["batch"]`)
-
-| Resource | Why the driver needs it |
-|----------|------------------------|
-| `jobs` | M2: submit one `Job` per agent run. The driver needs `watch` to track the Job to completion and map terminal conditions to `AdapterExecutionResult` exit codes. `delete` is used for cancellation. |
-
-This rule is present in the ClusterRole now so that M2 can begin scheduling runs without an RBAC update. In M1, the driver's `run()` method returns `NOT_YET_SUPPORTED` before any Job is submitted.
-
-### Networking API group (`apiGroups: ["networking.k8s.io"]`)
-
-| Resource | Why the driver needs it |
-|----------|------------------------|
-| `networkpolicies` | Apply three `NetworkPolicy` objects per namespace: `default-deny-ingress`, `default-deny-egress`, `paperclip-agent-egress`. Must `patch` on re-provision to update the FQDN allowlist or control-plane selector. `watch` is not required (policies are reconciled at `ensure-tenant` time). |
-
-### RBAC API group (`apiGroups: ["rbac.authorization.k8s.io"]`)
-
-| Resource | Why the driver needs it |
-|----------|------------------------|
-| `roles` | Reserved for M2: in-namespace `Role` objects for fine-grained per-job access control. |
-| `rolebindings` | The driver creates a `RoleBinding` named `paperclip-driver` in each tenant namespace, binding the `paperclip-tenant-manager` ClusterRole to the driver ServiceAccount scoped to that namespace. This is required for the driver to have write access to namespaced resources after initial namespace creation. |
-
-**Important:** The ability to create `RoleBindings` is a powerful permission. The driver is constrained to bind only the roles it already holds (the k8s API enforces that you cannot grant more than you have). The `paperclip-driver` identity should be protected: the ServiceAccount token must not be exposed outside the control plane.
-
-### Cilium API group (`apiGroups: ["cilium.io"]`)
-
-| Resource | Why the driver needs it |
-|----------|------------------------|
-| `ciliumnetworkpolicies` | When the cluster has the Cilium CNI, apply a `CiliumNetworkPolicy` alongside the vanilla NetworkPolicy. The CNP provides L7/FQDN egress filtering (see [security-model.md](./security-model.md#cilium-variant-fqdn-allowlist-auto-detected)). If Cilium is not present, this rule is harmless — the `cilium.io` API group simply does not exist. |
-
-## Binding templates
-
-### In-cluster topology
-
-Paperclip server and agent workloads share the same cluster. The server pod's ServiceAccount in `paperclip-system` holds the driver identity.
-
-```yaml
-# Step 1: namespace for the Paperclip control plane
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: paperclip-system
----
-# Step 2: ServiceAccount for the driver
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: paperclip-driver
-  namespace: paperclip-system
----
-# Step 3: bind the ClusterRole cluster-wide
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: paperclip-driver
-subjects:
-  - kind: ServiceAccount
-    name: paperclip-driver
-    namespace: paperclip-system
-roleRef:
-  kind: ClusterRole
-  name: paperclip-tenant-manager
-  apiGroup: rbac.authorization.k8s.io
-```
-
-Apply:
-
-```bash
-kubectl apply -f paperclip-system-sa.yaml
-```
-
-The Paperclip server pod must run with `serviceAccountName: paperclip-driver`. The `@kubernetes/client-node` library will automatically use the in-cluster ServiceAccount token from `/var/run/secrets/kubernetes.io/serviceaccount/`.
-
-When adding the cluster connection, use `--kind in-cluster` (no `--kubeconfig-secret`):
-
-```bash
-paperclipai cluster add \
-  --label production \
-  --kind in-cluster
-```
-
-### Cross-cluster topology
-
-The Paperclip server runs outside the workload cluster. Access is via a stored kubeconfig whose embedded user must have the same permissions as the `paperclip-tenant-manager` ClusterRole.
-
-The kubeconfig user identity is cluster-specific. Apply the ClusterRole and a `ClusterRoleBinding` on the **workload cluster** that binds the kubeconfig user:
-
-```yaml
-# Apply to the workload cluster (not the control-plane cluster)
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: paperclip-driver-external
-subjects:
-  - kind: User
-    name: paperclip-driver   # must match the user in the kubeconfig
-    apiGroup: rbac.authorization.k8s.io
-roleRef:
-  kind: ClusterRole
-  name: paperclip-tenant-manager
-  apiGroup: rbac.authorization.k8s.io
-```
-
-```bash
-# Apply to the workload cluster
-kubectl apply -f paperclip-driver-external-crb.yaml \
-  --kubeconfig /path/to/workload-cluster-admin.kubeconfig
-```
-
-The kubeconfig stored in the Paperclip secret provider must have a `users[].user` entry that matches the `subjects[].name` above. With a certificate-based kubeconfig, the CN in the client certificate is the username.
-
-When adding the cluster connection:
-
-```bash
-paperclipai cluster add \
-  --label workload-cluster-1 \
-  --kind kubeconfig \
-  --kubeconfig-secret vault:secret/data/paperclip/wc1-kubeconfig
-```
-
-**Note:** The RBAC rules must be applied to every cluster the kubeconfig user is expected to manage. If a single kubeconfig contains multiple contexts, apply the ClusterRole and ClusterRoleBinding to each cluster independently.
-
-## Least-privilege notes
-
-The ClusterRole is broader than M1 strictly requires because it is designed to serve M1 through M2 without an RBAC update. In M1 the driver only provisions namespaces; in M2 it will also schedule Jobs and stream pod logs.
-
-If your security policy requires strict M1-only RBAC, you can create a narrower ClusterRole that omits `jobs`, `pods`, `pods/log`, `pods/exec`, `persistentvolumeclaims`, and `configmaps`. When M2 ships you will need to re-apply a wider role. This trade-off is yours to make as an operator.
-
-## Related
-
-- [Quickstart](./quickstart.md) — first-time cluster setup walkthrough
-- [Security model](./security-model.md) — how each provisioned object enforces isolation
-- [Multi-tenant onboarding](./multi-tenant-onboarding.md) — provisioning multiple tenants
-- [Design spec §2.2](../superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md#22-pod-identity-zero-trust-by-default)

docs/k8s-execution/multi-tenant-onboarding.md

@@ -1,257 +0,0 @@
----
-title: Kubernetes Execution — Multi-Tenant Onboarding
-summary: Operator playbook for provisioning multiple company namespaces, customising per-tenant quotas, and resolving common edge cases
----
-
-This playbook covers the full lifecycle of onboarding a company onto a Kubernetes cluster: verifying cluster prerequisites, optionally customising the per-tenant policy, running `ensure-tenant`, and verifying the result. The security model behind each provisioned object is described in [security-model.md](./security-model.md).
-
-**M1 scope:** This playbook covers tenant namespace provisioning only. There is no web UI for these operations yet (M3). Agent execution lands in M2.
-
-## Step 1 — Verify cluster prerequisites
-
-Before provisioning any tenant, confirm the cluster is ready.
-
-```bash
-paperclipai cluster doctor <clusterId>
-```
-
-Check the output for:
-
-| Check | Expected result |
-|-------|----------------|
-| API server reachable | `ok` |
-| `paperclip-tenant-manager` ClusterRole exists | `ok` |
-| Default StorageClass present | `ok` — note the StorageClass name for reference |
-| Cilium detected | `ok` or `not detected` (informational only in M1) |
-
-If `doctor` reports a missing ClusterRole, apply it:
-
-```bash
-kubectl apply -f packages/adapters/kubernetes-execution/manifests/paperclip-tenant-manager-clusterrole.yaml
-```
-
-For a from-scratch cluster setup including the ServiceAccount and ClusterRoleBinding, see [quickstart.md](./quickstart.md#first-time-cluster-setup).
-
-## Step 2 — Optionally customise the per-tenant policy
-
-By default, every tenant gets the [quota and limit-range defaults](./security-model.md#resourcequota-and-limitrange). If a company needs different resource caps (for example, a larger plan), upsert a row in `cluster_tenant_policies` before running `ensure-tenant`.
-
-There is no CLI for this in M1. Use a direct database query or a DB migration script.
-
-### cluster_tenant_policies row shape
-
-```sql
-INSERT INTO cluster_tenant_policies (
-  id,
-  cluster_connection_id,
-  company_id,
-  quota_json,
-  limit_range_json,
-  network_json,
-  image_overrides_json,
-  created_at,
-  updated_at
-) VALUES (
-  gen_random_uuid(),
-  '<clusterId>',
-  '<companyId>',
-  -- quota_json: override any of the default quota fields; null = use defaults
-  '{
-    "requestsCpu":    "32",
-    "requestsMemory": "128Gi",
-    "limitsCpu":      "128",
-    "limitsMemory":   "512Gi",
-    "requestsStorage":"500Gi",
-    "countJobs":       200,
-    "countPvcs":       100,
-    "countSecrets":    400,
-    "countConfigMaps": 400
-  }'::jsonb,
-  -- limit_range_json: override container default/request/max; null = use defaults
-  '{
-    "default":        { "cpu": "2",    "memory": "4Gi"  },
-    "defaultRequest": { "cpu": "500m", "memory": "1Gi"  },
-    "max":            { "cpu": "16",   "memory": "64Gi" },
-    "pvcMaxStorage":  "50Gi"
-  }'::jsonb,
-  -- network_json: additional FQDN allowlist entries (Cilium only) and optional HTTP proxy
-  '{
-    "additionalAllowFqdns": ["npm.registry.example.com", "*.internal.example.com"],
-    "httpProxyUrl": null
-  }'::jsonb,
-  -- image_overrides_json: swap runtime images per adapter type; null = use cluster defaults
-  null,
-  now(),
-  now()
-)
-ON CONFLICT (cluster_connection_id, company_id) DO UPDATE
-  SET quota_json           = EXCLUDED.quota_json,
-      limit_range_json     = EXCLUDED.limit_range_json,
-      network_json         = EXCLUDED.network_json,
-      image_overrides_json = EXCLUDED.image_overrides_json,
-      updated_at           = now();
-```
-
-All four JSON columns are nullable. A null value means "use the global default for that field". Individual keys within each JSON object are also optional — omitting a key leaves that specific default unchanged.
-
-A CLI for managing tenant policies is planned for a future milestone. Until then, the SQL above is the canonical operator interface.
-
-## Step 3 — Provision the tenant namespace
-
-```bash
-paperclipai cluster ensure-tenant <clusterId> <companyId>
-```
-
-Expected output:
-
-```
-Provisioned namespace paperclip-<companySlug> (cilium=false)
-```
-
-Or if Cilium is detected:
-
-```
-Provisioned namespace paperclip-<companySlug> (cilium=true)
-```
-
-`ensure-tenant` is idempotent. Running it again on an already-provisioned namespace is safe and will patch any drifted objects back to their desired state. The command reads the `cluster_tenant_policies` row (if it exists) before applying quota and LimitRange objects.
-
-Objects created (in order):
-
-1. `Namespace` with PSS labels and `paperclip.ai/*` metadata labels
-2. `ServiceAccount paperclip-agent` (`automountServiceAccountToken: false`)
-3. `RoleBinding paperclip-driver` (binds `ClusterRole/paperclip-tenant-manager` to the driver SA, scoped to this namespace)
-4. `ResourceQuota paperclip-tenant-quota`
-5. `LimitRange paperclip-tenant-limits`
-6. `NetworkPolicy default-deny-ingress` and `default-deny-egress`
-7. `NetworkPolicy paperclip-agent-egress`
-8. `CiliumNetworkPolicy paperclip-agent-egress-l7` (only when `capabilities.cilium = true`)
-9. `Secret paperclip-image-pull` (only when image registry credentials are configured)
-
-## Step 4 — Verify the provisioned namespace
-
-```bash
-kubectl describe namespace paperclip-<companySlug>
-```
-
-Look for:
-
-```
-Labels:
-  paperclip.ai/company-id=<uuid>
-  paperclip.ai/company-slug=<slug>
-  paperclip.ai/managed-by=paperclip
-  pod-security.kubernetes.io/enforce=restricted
-  pod-security.kubernetes.io/audit=restricted
-  pod-security.kubernetes.io/warn=restricted
-```
-
-Verify all managed objects are present:
-
-```bash
-kubectl get sa,resourcequota,limitrange,networkpolicy \
-  -n paperclip-<companySlug> \
-  -l paperclip.ai/managed-by=paperclip
-```
-
-If Cilium is present, also check:
-
-```bash
-kubectl get ciliumnetworkpolicy -n paperclip-<companySlug>
-```
-
-## Provisioning multiple companies
-
-Loop over company IDs from your database or source of truth:
-
-```bash
-CLUSTER_ID="<clusterId>"
-
-for COMPANY_ID in \
-  "uuid-company-a" \
-  "uuid-company-b" \
-  "uuid-company-c"; do
-  echo "Provisioning $COMPANY_ID..."
-  paperclipai cluster ensure-tenant "$CLUSTER_ID" "$COMPANY_ID"
-done
-```
-
-`ensure-tenant` is safe to run in parallel; each company operates on a separate namespace.
-
-## Common edge cases
-
-### Quota exhaustion
-
-When an agent run (M2) cannot schedule because the tenant has hit a quota limit, the Kubernetes API returns a `403 Forbidden` with `reason: Forbidden` and a message referencing the quota object. In M1, this surfaces at `ensure-tenant` time only if the quota parameters themselves are invalid (e.g. a LimitRange `max` that is smaller than `default`).
-
-To inspect current quota usage for a namespace:
-
-```bash
-kubectl describe resourcequota paperclip-tenant-quota -n paperclip-<companySlug>
-```
-
-To increase quotas, upsert the `cluster_tenant_policies` row with larger values and re-run `ensure-tenant`.
-
-### DNS resolution issues
-
-If a pod cannot resolve external hostnames, verify the NetworkPolicy allows DNS egress to `kube-system/kube-dns`:
-
-```bash
-kubectl get networkpolicy paperclip-agent-egress \
-  -n paperclip-<companySlug> \
-  -o yaml
-```
-
-Look for the DNS egress rule on port 53. If it is missing (e.g. the namespace was provisioned against an older driver), re-run `ensure-tenant` to patch it in.
-
-Check that CoreDNS is running:
-
-```bash
-kubectl get pods -n kube-system -l k8s-app=kube-dns
-```
-
-### Image pull failures
-
-Three distinct failure modes:
-
-| Symptom | Likely cause | Fix |
-|---------|-------------|-----|
-| `ImagePullBackOff`, event: `no credentials` | No `imagePullSecret` in the namespace | Ensure the cluster connection has an `imageRegistry` configured and re-run `ensure-tenant` |
-| `ImagePullBackOff`, event: `401 Unauthorized` | Wrong credentials | Rotate the secret in the secret provider and re-run `ensure-tenant` |
-| `ImagePullBackOff`, event: `i/o timeout` | Registry unreachable | Check the NetworkPolicy allows egress to the registry FQDN on port 443; on Cilium, add the FQDN to `network_json.additionalAllowFqdns` in `cluster_tenant_policies` |
-
-### Privileged pod admission rejection
-
-To confirm that PSS Restricted is active and blocking privileged pods:
-
-```bash
-kubectl run test-privileged \
-  --image=nginx \
-  --overrides='{"spec":{"containers":[{"name":"test-privileged","image":"nginx","securityContext":{"privileged":true}}]}}' \
-  -n paperclip-<companySlug>
-```
-
-Expected output:
-
-```
-Error from server (Forbidden): pods "test-privileged" is forbidden:
-violates PodSecurity "restricted:latest": ...
-```
-
-This rejection proves the PodSecurityAdmission webhook is active on the namespace. If the pod is admitted instead, confirm the PSS labels are present on the namespace with `kubectl describe namespace`.
-
-### Namespace name collision
-
-If two companies have the same `companySlug`, the driver uses the fallback name `paperclip-{slug}-{base36hash}`. The `paperclip.ai/company-id` label is always the canonical identifier. To see which namespace belongs to a given company:
-
-```bash
-kubectl get ns -l paperclip.ai/company-id=<companyId>
-```
-
-## Related
-
-- [Quickstart](./quickstart.md) — initial cluster setup and first `ensure-tenant`
-- [Security model](./security-model.md) — what each provisioned object does and why
-- [Cluster RBAC](./cluster-rbac.md) — driver ClusterRole reference
-- [Design spec §2.1](../superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md#21-tenant-boundary-namespace-per-company)
-- [M1 plan](../superpowers/plans/2026-05-08-paperclip-cloud-adapter-m1-plan.md)

docs/k8s-execution/quickstart.md

@@ -1,226 +0,0 @@
----
-title: Kubernetes Execution — Quickstart
-summary: First-time setup guide for operators connecting a Kubernetes cluster to Paperclip and provisioning a tenant namespace
----
-
-This guide walks an operator through connecting a Kubernetes cluster to a Paperclip M1 deployment and provisioning the first tenant namespace. By the end you will have a verified cluster connection and a namespace that passes `kubectl describe namespace` — ready for agent execution when M2 ships.
-
-**M1 scope:** This release delivers tenant namespace provisioning only. Agent execution (running adapter pods) is an M2 feature. See [What's not in M1](#whats-not-in-m1) for the full boundary.
-
-## Prerequisites
-
-| Tool | Version | Notes |
-|------|---------|-------|
-| `kubectl` | 1.28+ | Must be on `$PATH` |
-| `kind` | 0.22+ | Only if using a local kind cluster |
-| Docker | 24+ | Required to run kind |
-| Paperclip server | M1 build | `PAPERCLIP_K8S_DRIVER=true` env var must be set |
-| `paperclipai` CLI | M1 build | `pnpm paperclipai --version` should print a version |
-
-A PostgreSQL database with the M1 migrations applied (`packages/db/src/migrations/0082_cluster_connections.sql`) is required before any cluster commands work.
-
-## First-time cluster setup
-
-### 1. Start a kind cluster (if you don't have one)
-
-```bash
-kind create cluster --name paperclip-dev
-kubectl cluster-info --context kind-paperclip-dev
-```
-
-For a production cluster, ensure it has:
-- A default `StorageClass` (used for agent PVCs in M2)
-- `NetworkPolicy` enforcement (Calico, Cilium, or compatible CNI)
-
-### 2. Apply the reference ClusterRole
-
-The Paperclip driver needs a `ClusterRole` that allows it to manage tenant namespaces and the objects inside them.
-
-```bash
-kubectl apply -f packages/adapters/kubernetes-execution/manifests/paperclip-tenant-manager-clusterrole.yaml
-```
-
-Verify it was created:
-
-```bash
-kubectl get clusterrole paperclip-tenant-manager
-```
-
-### 3. Create the driver ServiceAccount and bind the ClusterRole
-
-For an **in-cluster** topology (Paperclip server running inside the same cluster), create the ServiceAccount in the `paperclip-system` namespace:
-
-```yaml
-# paperclip-system-sa.yaml
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: paperclip-system
----
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: paperclip-driver
-  namespace: paperclip-system
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: paperclip-driver
-subjects:
-  - kind: ServiceAccount
-    name: paperclip-driver
-    namespace: paperclip-system
-roleRef:
-  kind: ClusterRole
-  name: paperclip-tenant-manager
-  apiGroup: rbac.authorization.k8s.io
-```
-
-```bash
-kubectl apply -f paperclip-system-sa.yaml
-```
-
-For a **cross-cluster** topology (Paperclip server is elsewhere), the kubeconfig user must already be bound to the same `ClusterRole` on the workload cluster. See [cluster-rbac.md](./cluster-rbac.md) for details on both topologies.
-
-### 4. Store the kubeconfig as a Paperclip secret
-
-Paperclip resolves cluster credentials through its secret provider abstraction. The `kubeconfig_secret_ref` field on a `cluster_connections` row holds a `{ provider, name }` pair. Supported providers in M1:
-
-| Provider string | Where the secret lives |
-|-----------------|----------------------|
-| `env` | Environment variable (e.g. `env:KUBECONFIG_KIND`) |
-| `aws_secrets` | AWS Secrets Manager secret ARN or name |
-| `gcp_secret` | GCP Secret Manager resource path |
-| `vault` | HashiCorp Vault path (`vault:secret/data/paperclip/kind-cfg`) |
-
-For a local kind cluster, the simplest path is the `env` provider. Export the kubeconfig and set an environment variable on the Paperclip server:
-
-```bash
-kind get kubeconfig --name paperclip-dev > /tmp/kind-cfg.yaml
-export KUBECONFIG_KIND=$(cat /tmp/kind-cfg.yaml)
-```
-
-Then reference it as `env:KUBECONFIG_KIND` in the `--kubeconfig-secret` flag below.
-
-> **Note:** `local_encrypted` (a Paperclip-managed encrypted store) is planned for M2. Until then, use one of the providers listed above.
-
-## Add a cluster connection
-
-```bash
-paperclipai cluster add \
-  --label kind \
-  --kind kubeconfig \
-  --kubeconfig-secret env:KUBECONFIG_KIND
-```
-
-The command probes the cluster for capabilities (Cilium presence, default StorageClass, node architectures) and writes a row to `cluster_connections`. The printed `id` is the `<clusterId>` used in subsequent commands.
-
-Additional flags:
-
-| Flag | Purpose |
-|------|---------|
-| `--paperclip-public-url <url>` | Override the Paperclip server URL agents use to call back (cross-cluster only) |
-| `--image-registry <url>` | Override the image registry for agent runtime images |
-
-## Verify the connection
-
-```bash
-# Check reachability, RBAC, and cluster capabilities
-paperclipai cluster doctor <id>
-
-# List all registered cluster connections
-paperclipai cluster list
-```
-
-`cluster doctor` checks:
-- API server reachability via the stored kubeconfig
-- `paperclip-tenant-manager` ClusterRole exists
-- Default StorageClass is present
-- Cilium CRD presence (informational)
-
-## Provision a tenant for a company
-
-```bash
-paperclipai cluster ensure-tenant <clusterId> <companyId>
-```
-
-Expected output:
-
-```
-Provisioned namespace paperclip-<companySlug> (cilium=false)
-```
-
-Or, if Cilium is present on the cluster:
-
-```
-Provisioned namespace paperclip-<companySlug> (cilium=true)
-```
-
-`ensure-tenant` is **idempotent** — running it twice is safe and brings any drifted objects back to the desired state. The driver refuses to touch a namespace that lacks the `paperclip.ai/managed-by=paperclip` label.
-
-## Verify the namespace with kubectl
-
-```bash
-kubectl get ns,sa,resourcequota,limitrange,networkpolicy \
-  -l paperclip.ai/managed-by=paperclip
-```
-
-You should see:
-- `Namespace` named `paperclip-<companySlug>`
-- `ServiceAccount` named `paperclip-agent`
-- `ResourceQuota` named `paperclip-tenant-quota`
-- `LimitRange` named `paperclip-tenant-limits`
-- `NetworkPolicy` objects `default-deny-ingress`, `default-deny-egress`, `paperclip-agent-egress`
-
-```bash
-kubectl describe namespace paperclip-<companySlug>
-```
-
-Check that the PSS labels are present:
-
-```
-Labels: pod-security.kubernetes.io/enforce=restricted
-        pod-security.kubernetes.io/audit=restricted
-        pod-security.kubernetes.io/warn=restricted
-        paperclip.ai/managed-by=paperclip
-        paperclip.ai/company-id=<uuid>
-```
-
-## Run your first agent
-
-After a cluster is bound to a tenant, run an agent on it:
-
-```bash
-paperclipai agent register --company acme --adapter claude_local \
-  --execution-target kubernetes:prod
-paperclipai agent run --agent <id> --prompt "say hi"
-```
-
-Expected: streamed logs from the agent pod ending with the assistant text.
-
-If logs appear empty, check that:
-1. The `agent-runtime-claude` image is reachable from the cluster (cosign verify the image, see [security-model.md](./security-model.md)).
-2. The bootstrap-token exchange route is reachable: `curl https://<paperclip-public-url>/api/agent-auth/exchange -d '{}'` should return `400 missing_token` (proves it's wired).
-3. `PAPERCLIP_RUN_JWT_SECRET` is set on the server (otherwise the routes are mounted but reject every request).
-
-For the full walkthrough of what happens between `agent run` and assistant text reaching your terminal, see [agent-execution-flow.md](./agent-execution-flow.md). For failure-mode triage, see [troubleshooting.md](./troubleshooting.md).
-
-## What's not in M1
-
-| Feature | Milestone |
-|---------|-----------|
-| Agent execution (running adapter pods as Kubernetes Jobs) | M2 |
-| Web UI for cluster management and health | M3 |
-| Per-company BYO cluster (one cluster connection per company) | V2 |
-| VolumeSnapshot-based agent workspace cloning | V2 |
-| `local_encrypted` secret provider | M2 |
-| `paperclipai cluster purge` (namespace teardown) | M2 |
-
-For the full V1/V2 scope split see the [design spec](../superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md#non-goals-v1).
-
-## Next steps
-
-- [Security model](./security-model.md) — understand the isolation primitives applied to each namespace
-- [Multi-tenant onboarding](./multi-tenant-onboarding.md) — operator playbook for provisioning multiple companies
-- [Cluster RBAC](./cluster-rbac.md) — full ClusterRole reference and binding templates

docs/k8s-execution/security-model.md

@@ -1,353 +0,0 @@
----
-title: Kubernetes Execution — Security Model
-summary: Isolation primitives applied to every tenant namespace — NetworkPolicy, PodSecurity, RBAC, ResourceQuota, and compliance posture
----
-
-Every company that runs agents on a Kubernetes cluster gets an isolated namespace with a layered set of controls. This document describes each layer, why it exists, and how to verify it. The spec section that defines these primitives is [§2 of the design spec](../superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md#2-tenancy-isolation--cluster-connection).
-
-**M1 scope:** These controls are provisioned by `cluster ensure-tenant`. Agent pods that enforce them (PodSecurity Restricted, NetworkPolicy enforcement during actual runs) are an M2 deliverable. The namespace is fully hardened at provision time; the hardening is exercised at run time.
-
-## Tenancy boundary: one Namespace per company
-
-Every Paperclip company maps to exactly one namespace per cluster connection, named `paperclip-{companySlug}`. This is the primary isolation boundary: Kubernetes RBAC, ResourceQuota, NetworkPolicy, and PodSecurityAdmission all attach at the namespace level.
-
-**Naming rules** (from [spec §2.1](../superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md#21-tenant-boundary-namespace-per-company)):
-- Primary: `paperclip-{companySlug}` (companySlug truncated to 53 chars so the total stays ≤ 63)
-- Fallback: `paperclip-{companySlug}-{base36(blake3(companyId))[:8]}` on DNS-1123 overflow or slug collision
-
-The immutable machine identifier is the `paperclip.ai/company-id=<uuid>` label on the Namespace object, not the namespace name.
-
-The driver refuses to manage any namespace that does not carry `paperclip.ai/managed-by=paperclip`. This prevents accidental mutation of pre-existing namespaces.
-
-## Pod identity: zero-trust by default
-
-Each tenant namespace contains a `ServiceAccount` named `paperclip-agent` with:
-
-```yaml
-automountServiceAccountToken: false
-```
-
-This ServiceAccount has **no RBAC bindings** by default. A pod running as `paperclip-agent` cannot call the Kubernetes API at all. The driver's own identity (the `paperclip-driver` ServiceAccount in `paperclip-system`) is separate and holds the `ClusterRole` described in [cluster-rbac.md](./cluster-rbac.md).
-
-Disabling `automountServiceAccountToken` removes the projected token from the pod filesystem, eliminating a common privilege escalation path even if the service account later gains bindings.
-
-## NetworkPolicy: default-deny + allowlist
-
-Three NetworkPolicy objects are applied to every tenant namespace.
-
-### default-deny-ingress
-
-```yaml
-podSelector: {}
-policyTypes: [Ingress]
-```
-
-Blocks all ingress to every pod in the namespace. Agent pods do not accept inbound connections.
-
-### default-deny-egress
-
-```yaml
-podSelector: {}
-policyTypes: [Egress]
-```
-
-Blocks all egress by default. Only pods that match the `paperclip-agent-egress` allowlist policy can make outbound connections.
-
-### paperclip-agent-egress
-
-Applied only to pods labeled `paperclip.ai/role: agent-runtime`. Three egress rules, in order:
-
-**1. Cluster DNS**
-
-```yaml
-to:
-  - namespaceSelector:
-      matchLabels: { kubernetes.io/metadata.name: kube-system }
-    podSelector:
-      matchLabels: { k8s-app: kube-dns }
-ports: [{ port: 53, protocol: UDP }, { port: 53, protocol: TCP }]
-```
-
-Agents need name resolution to reach the Paperclip server and external APIs.
-
-**2. In-cluster Paperclip server** (in-cluster topology only)
-
-```yaml
-to:
-  - namespaceSelector:
-      matchLabels: { paperclip.ai/role: control-plane }
-    podSelector:
-      matchLabels: { app.kubernetes.io/name: paperclip-server }
-ports: [{ port: 443, protocol: TCP }, { port: 3102, protocol: TCP }]
-```
-
-Agents call back to the Paperclip server to exchange the bootstrap token for a run JWT. This rule is omitted for cross-cluster topologies where the server is not in the same cluster.
-
-**3. Internet egress with internal ranges denied**
-
-```yaml
-to:
-  - ipBlock:
-      cidr: 0.0.0.0/0
-      except:
-        - 10.0.0.0/8
-        - 172.16.0.0/12
-        - 192.168.0.0/16
-        - 169.254.0.0/16    # link-local — cloud metadata service
-        - 100.64.0.0/10     # CGNAT
-  - ipBlock:
-      cidr: ::/0
-      except:
-        - fd00::/8          # IPv6 ULA
-ports: [{ port: 443, protocol: TCP }]
-```
-
-**Why each block matters:**
-
-| CIDR | What it blocks | Why it matters |
-|------|----------------|----------------|
-| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | RFC 1918 private ranges | Cluster-internal databases, caches, other services |
-| `169.254.0.0/16` | Link-local (incl. `169.254.169.254`) | **Cloud metadata service** — this is the primary SSRF target on AWS/GCP/Azure. A compromised pod that can reach the metadata service can obtain instance credentials and escape the tenant boundary |
-| `100.64.0.0/10` | CGNAT / shared address space | Often used by cloud providers for internal routing; blocks a secondary metadata path on some platforms |
-| `fd00::/8` | IPv6 ULA | Internal IPv6 ranges; same threat model as RFC 1918. Must be in a separate `ipBlock` entry because the Kubernetes API rejects IPv6 ranges inside an IPv4 cidr |
-
-The IPv4 and IPv6 deny blocks are intentionally separate `ipBlock` entries. The Kubernetes NetworkPolicy API requires each `except` entry to be a strict subset of its parent `cidr`; mixing IPv6 ranges inside `0.0.0.0/0` is rejected with a 422 error.
-
-## Cilium variant: FQDN allowlist (auto-detected)
-
-When `probeClusterCapabilities` detects the `cilium.io/v2` API group, the driver also applies a `CiliumNetworkPolicy` alongside the vanilla NetworkPolicy. The vanilla policy stays as defense-in-depth.
-
-```yaml
-apiVersion: cilium.io/v2
-kind: CiliumNetworkPolicy
-metadata:
-  name: paperclip-agent-egress-l7
-spec:
-  endpointSelector:
-    matchLabels: { paperclip.ai/role: agent-runtime }
-  egress:
-    - toFQDNs:
-        - matchPattern: "*.anthropic.com"
-        - matchPattern: "api.openai.com"
-        - matchPattern: "*.googleapis.com"
-        - matchPattern: "github.com"
-        - matchPattern: "*.github.com"
-        - matchPattern: "gitlab.com"
-      toPorts:
-        - ports: [{ port: "443", protocol: TCP }]
-    - toEndpoints:
-        - matchLabels: { paperclip.ai/role: control-plane }
-      toPorts:
-        - ports: [{ port: "443", protocol: TCP }]
-```
-
-The FQDN list is composed from two sources:
-- `adapter.networkRequirements.allowFqdns` (declared per adapter type in `ServerAdapterModule`)
-- `cluster_tenant_policies.network_json.additionalAllowFqdns` (per-tenant override, described in [multi-tenant-onboarding.md](./multi-tenant-onboarding.md))
-
-Cilium detection happens automatically at `cluster add` time. Re-run `cluster doctor <id>` after installing Cilium to update the stored capabilities; then re-run `cluster ensure-tenant` to apply the CNP.
-
-## PodSecurity Restricted
-
-The namespace is labeled at provision time:
-
-```yaml
-pod-security.kubernetes.io/enforce: restricted
-pod-security.kubernetes.io/audit:   restricted
-pod-security.kubernetes.io/warn:    restricted
-```
-
-Any pod admitted to the namespace must conform to the `restricted` PodSecurity Standard. Agent pods (M2) are built to satisfy it:
-
-```yaml
-securityContext:
-  runAsNonRoot: true
-  runAsUser: 1000
-  runAsGroup: 1000
-  fsGroup: 1000
-  seccompProfile: { type: RuntimeDefault }
-containers:
-  - securityContext:
-      allowPrivilegeEscalation: false
-      readOnlyRootFilesystem: true
-      capabilities: { drop: [ALL] }
-```
-
-`readOnlyRootFilesystem: true` is enforced. Writable paths are:
-- `/workspace` — agent `PersistentVolumeClaim` (M2)
-- `/tmp` — `emptyDir` volume capped at 1 Gi (M2)
-
-An attempt to `kubectl run` a privileged pod into a Paperclip namespace will be rejected by the admission controller — this is the expected behavior and confirms PSS is working. See [multi-tenant-onboarding.md](./multi-tenant-onboarding.md#common-edge-cases) for how to verify this.
-
-## ResourceQuota and LimitRange
-
-Default values (can be overridden per tenant via `cluster_tenant_policies` — see [multi-tenant-onboarding.md](./multi-tenant-onboarding.md)):
-
-### ResourceQuota `paperclip-tenant-quota`
-
-```yaml
-hard:
-  requests.cpu:                 "16"
-  requests.memory:              "64Gi"
-  limits.cpu:                   "64"
-  limits.memory:                "256Gi"
-  requests.storage:             "200Gi"
-  count/jobs.batch:             "100"
-  count/persistentvolumeclaims: "50"
-  count/secrets:                "200"
-  count/configmaps:             "200"
-```
-
-### LimitRange `paperclip-tenant-limits`
-
-```yaml
-limits:
-  - type: Container
-    default:        { cpu: "1",    memory: "2Gi" }
-    defaultRequest: { cpu: "250m", memory: "512Mi" }
-    max:            { cpu: "8",    memory: "32Gi" }
-  - type: PersistentVolumeClaim
-    max: { storage: "20Gi" }
-```
-
-The LimitRange ensures that pods without explicit resource requests/limits still get sensible defaults and cannot consume unbounded resources. Without it, a misconfigured pod could exhaust node capacity and starve other tenants.
-
-## Image pull secret model
-
-If the cluster connection has an associated image registry and the `imagePullDockerConfigJson` is resolved at provision time, the driver creates a `Secret` of type `kubernetes.io/dockerconfigjson` in the tenant namespace:
-
-```
-Secret name: paperclip-image-pull
-Secret type: kubernetes.io/dockerconfigjson
-```
-
-This secret is referenced by agent pod specs (M2) as an `imagePullSecret`. Credentials are per-namespace and are not shared across tenants. The secret value is resolved from the Paperclip secret provider at `ensure-tenant` time.
-
-## Secret-resolver M1 gap
-
-The secret provider abstraction supports `aws_secrets`, `gcp_secret`, `vault`, and `env` in M1. The `local_encrypted` provider (Paperclip-managed encrypted store) is planned for M2.
-
-Operators running a self-hosted Paperclip instance without access to a cloud secret manager should use `env:<VAR_NAME>` for the kubeconfig secret during M1.
-
-## Run-JWT lifecycle (M2)
-
-Agent containers cannot speak Kubernetes — they have no projected ServiceAccount token (see [Pod identity](#pod-identity-zero-trust-by-default)) and the agent ServiceAccount has no RBAC. To call back to the Paperclip server they use a two-step token exchange:
-
-1. **Bootstrap token mint.** The driver calls `bootstrapTokensService` (`server/src/services/bootstrap-tokens.ts`) to mint a single-use, short-lived token bound to `(agentId, companyId, runId)`. The token is sealed into the per-Job Secret as `BOOTSTRAP_TOKEN` before the Job is created.
-2. **Exchange.** Inside the pod, `paperclip-agent-shim` sends `POST /api/agent-auth/exchange` with the bootstrap token. The server validates one-time use, atomically marks the token consumed, and returns a **run JWT** signed with `PAPERCLIP_RUN_JWT_SECRET` (`server/src/services/run-jwt.ts`).
-3. **Run JWT.** The run JWT carries `runId`, `agentId`, `companyId`, and the Job UID. It expires after the run's `activeDeadlineSeconds` ceiling. Every subsequent agent → server call (`POST /api/runs/:runId/events`, `POST /api/workspace/git-credentials`) presents the run JWT and the server validates the claims against the live run.
-
-If `PAPERCLIP_RUN_JWT_SECRET` is unset on the server, the callback routes are skipped during app boot. The driver still mints bootstrap tokens, but every exchange request is rejected — verify the env var is set if agents log `401 invalid_token` during bootstrap.
-
-## TokenReview disposition (V1)
-
-The full Kubernetes-native `TokenReview` flow (where the server validates a projected ServiceAccount token straight from the cluster's API) is **deferred to V2**. M2 ships the bootstrap-token + run-JWT model above. Trade-off:
-
-- **What we lose:** the run JWT is signed by the Paperclip server, not by the cluster's API server, so revocation is per-tenant policy (rotate `PAPERCLIP_RUN_JWT_SECRET`) rather than per-Pod TokenRequest revocation.
-- **What we keep:** bootstrap tokens are single-use and short-lived; run JWTs are scoped to `(runId, agentId, companyId, jobUid)` so a stolen JWT cannot be replayed against a different run. Cross-cluster TokenReview tracking lives in [ROADMAP.md](../../ROADMAP.md) under M3 (Risk #5).
-
-## Per-Job Secret with OwnerReferences
-
-Run-time credentials (bootstrap token, redacted adapter env, optional git credentials) are sealed into a per-Job `Secret` of type `Opaque`. The driver's two-phase commit:
-
-1. **Create Secret first.** `POST /api/v1/namespaces/<ns>/secrets` with the Secret body but no owner. The Secret is mounted as a read-only `secret` volume on the Job's pod template.
-2. **Create Job.** `POST /apis/batch/v1/namespaces/<ns>/jobs` with the Pod template that references the Secret by name.
-3. **Patch ownerReferences onto the Secret.** A `kubectl patch` equivalent rewrites the Secret's `metadata.ownerReferences` to point at the Job UID returned in step 2.
-
-After step 3, when the Job's `ttlSecondsAfterFinished` expires, Kubernetes garbage-collects the Job and cascades the deletion to the Secret. There is no manual cleanup path for orphaned Secrets.
-
-**Why not CSI Secrets Store?** CSI Secrets Store would inject credentials directly from a cloud secret manager into the pod, but:
-- It requires the CSI driver be installed on every workload cluster (operator burden in a BYO-cluster product).
-- It doesn't support the "credential exists only for the lifetime of one Job" model — secrets are per-`SecretProviderClass`, not per-Job.
-- It cannot redact adapter env at materialization time, which is a hard requirement (see `packages/adapters/kubernetes-execution/src/redaction.ts`).
-
-The two-phase commit is V1's shippable answer. CSI Secrets Store is on the roadmap for M3+ as an opt-in alternative.
-
-## Secret resolver providers
-
-The secret-resolver contract (`provider`, `name` → secret value) ships in M2 with the following providers:
-
-| Provider | Wired in | Use case |
-|----------|----------|----------|
-| `env` | M1 | Read from process env. Lab and self-hosted setups. |
-| `aws_secrets` | M1 | AWS Secrets Manager ARN or secret name. |
-| `gcp_secret` | M1 | GCP Secret Manager resource path. |
-| `vault` | M1 | HashiCorp Vault path. |
-| `local_encrypted` | M1 | Paperclip-managed encrypted store, server local. |
-| `aws_secrets_manager` | **M3** | Higher-level AWS provider with caching + IAM-role assumption. |
-| `gcp_secret_manager` | **M3** | Higher-level GCP provider with workload-identity binding. |
-
-M2 does not change the M1 provider list. The contract is stable; M3 adds higher-level providers without breaking existing rows.
-
-## Compliance bookkeeping
-
-The M1 provisioning pipeline is aligned with:
-
-- **NSA/CISA Kubernetes Hardening Guidance** — Restricted PSS, NetworkPolicy default-deny, no privilege escalation, no host network/PID/IPC, drop ALL capabilities, RuntimeDefault seccomp
-- **CIS Kubernetes Benchmark** — namespace isolation, ResourceQuota enforcement, no automounted ServiceAccount tokens
-
-The CI release pipeline runs `kube-audit-kit` and `polaris` against a freshly provisioned tenant namespace on every build. PSS Restricted violations or NSA Hardening regressions block the release.
-
-## Related
-
-- [Quickstart](./quickstart.md) — set up a cluster connection and run `ensure-tenant`
-- [Cluster RBAC](./cluster-rbac.md) — the driver ClusterRole and binding templates
-- [Multi-tenant onboarding](./multi-tenant-onboarding.md) — playbook for provisioning multiple companies and handling edge cases
-- [Design spec §2](../superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md#2-tenancy-isolation--cluster-connection)
-
-## Git credentials in V1
-
-V1 issues git credentials by resolving a per-company secret stored in
-`company_secrets` and exposing it to the workspace-init container as a
-`{username, password}` pair via the `/api/workspace/git-credentials` endpoint.
-
-### Trust model
-
-- The secret is owned by the company. Operators set it via `paperclip cluster set-git-credentials`.
-- The secret is decrypted only on the server — the agent's pod never sees the wrapping ciphertext, only the resolved `{username, password}` JSON.
-- The `/api/workspace/git-credentials` route requires a valid run-JWT (minted from a one-shot bootstrap token); the agent cannot exchange a JWT for credentials belonging to a different company.
-- The route logs `repoUrl` for audit but does not gate on it. Any clone path the workspace-init opens uses the same credential pair.
-
-### Limitations
-
-- **One credential per company.** Tenants with multiple repos pointing at different orgs/hosts must use a single PAT broad enough to cover all of them, OR pick the most-restrictive shared PAT.
-- **TTL is informational.** The exposed `expiresAt` is `now + 1h`, but the underlying `companySecret` is long-lived. The contract is stable so V2 (GitHub App installation tokens) can swap in a real TTL transparently.
-- **No per-repo scoping.** A compromised PAT exposes every repo it has access to. Operators who need scoping must wait for V2 or use deploy keys with a separate `companySecret` per repo.
-
-### V2 plan
-
-V2 replaces the static PAT with a GitHub App installation token minted on-demand for the specific repo the agent is about to clone. The `/api/workspace/git-credentials` contract stays unchanged.
-
-## Production rate limiting
-
-The `/api/agent-auth/exchange`, `/api/runs/:runId/events`, and
-`/api/workspace/git-credentials` endpoints carry sliding-window rate limits.
-The limit budgets are:
-
-| Endpoint                            | Window | Max  | Keyed by              |
-|-------------------------------------|--------|------|-----------------------|
-| `/api/agent-auth/exchange`          | 60s    | 10   | client IP             |
-| `/api/runs/:runId/events`           | 60s    | 1000 | run id (`run:<id>`)   |
-| `/api/workspace/git-credentials`    | 60s    | 30   | run id, IP fallback   |
-
-### Backing store
-
-By default the limits use a per-process in-memory sliding-window. **In a
-multi-replica deployment this is insufficient**: a client distributing
-requests across replicas evades the limit because each process sees a
-fraction of the volume.
-
-For production, set `PAPERCLIP_REDIS_URL` to a Redis 6+ instance reachable
-from every replica. Format: `redis://[:password@]host:port[/db]` or
-`rediss://...` for TLS.
-
-When `PAPERCLIP_REDIS_URL` is set, the server uses an atomic Lua-script
-based limiter against Redis sorted sets. Keys are namespaced
-`paperclip:rl:<limiter>:<consume-key>` and expire `windowMs * 2` after the
-last hit, so abandoned keys do not accumulate.
-
-### Failure mode
-
-Redis errors during `consume()` fail open: the request is admitted, the
-error is logged. This protects availability when Redis blips at the cost of
-admitting a request that should have been throttled.

docs/k8s-execution/sizing.md

@@ -1,71 +0,0 @@
-# Kubernetes execution target — agent sizing
-
-## Workload
-
-- Image: `paperclipai/agent-runtime-claude:test-m3a` (claude-code from `@anthropic-ai/claude-code`)
-- Prompt: `"Read README.md in /workspace and tell me the project name in one word."`
-- Workspace: PVC seeded with a 2-file repo (README.md + .gitignore)
-- Runs: 5 sequential, fresh PVC each run
-- Cluster: kind v0.24.0 (Kubernetes v1.31.x), single node, on a CI runner
-
-## Observations
-
-| Metric    | Peak | Median | p95   |
-|-----------|------|--------|-------|
-| CPU (m)   | TBD  | TBD    | TBD   |
-| Memory (Mi) | TBD | TBD  | TBD   |
-
-(Numbers populated when the test is actually run. See "How we measured" below.)
-
-## Recommended defaults
-
-```yaml
-resources:
-  requests:
-    cpu:    200m
-    memory: 256Mi
-  limits:
-    cpu:    2
-    memory: 1Gi
-```
-
-(M1 defaults retained until measurement justifies a bump — see "Decision".)
-
-## Recommended ResourceQuota for a 50-agent tenant
-
-```yaml
-spec:
-  hard:
-    requests.cpu:    "10"
-    requests.memory: "12Gi"
-    limits.cpu:      "100"
-    limits.memory:   "50Gi"
-    count/jobs.batch: "50"
-    count/persistentvolumeclaims: "50"
-    count/secrets:   "200"
-    count/configmaps: "100"
-```
-
-## Decision
-
-Threshold for raising defaults:
-- Memory: peak > 0.6 × current limit (614 Mi)
-- CPU: peak > 0.5 × current limit (1000 m)
-
-Decision: KEEP M1 defaults. Re-evaluate after first production runs surface real multi-turn workload data.
-
-## Caveats
-
-- This is a single-turn prompt. Multi-turn sessions (real agent loops) will use more memory due to accumulated context. Operators running multi-turn workloads should monitor actual usage and raise quotas accordingly.
-- Numbers from the empirical-measurement test are taken on a CI runner; production hardware may show different baselines.
-
-## How we measured
-
-`packages/adapters/kubernetes-execution/test/integration/empirical-measurement-claude.test.ts` provisions kind + metrics-server, runs the workload 5 times under measurement, and writes the table above. Re-run with:
-
-```bash
-ANTHROPIC_API_KEY=... K8S_INTEGRATION=1 \
-  pnpm --filter @paperclipai/execution-target-kubernetes exec vitest run test/integration/empirical-measurement-claude.test.ts
-```
-
-Cost: ~$0.05–0.20 per full run.

docs/k8s-execution/troubleshooting.md

@@ -1,132 +0,0 @@
----
-title: Kubernetes Execution — Troubleshooting
-summary: Operator-facing playbook for the common failure modes that show up when running agents on Kubernetes-bound tenants
----
-
-This document maps each failure mode to a concrete `kubectl` recipe that diagnoses it. Set the namespace and run ID once and reuse them:
-
-```bash
-NS=paperclip-<companySlug>
-RUN=<runUlid>
-```
-
-For the full happy-path walkthrough see [agent-execution-flow.md](./agent-execution-flow.md).
-
-## Pod stuck in `Pending`
-
-Symptom: the run never starts; `kubectl get pods` shows `Pending` for many seconds.
-
-The two usual causes are `ResourceQuota` rejection (the namespace is at its CPU/memory ceiling) and PodSecurity admission (the spec is not Restricted-compliant).
-
-```bash
-kubectl -n "$NS" describe pod -l "paperclip.ai/run-id=$RUN"
-```
-
-Check the `Events:` section at the bottom. Specific patterns:
-
-- `exceeded quota: paperclip-tenant-quota, requested: ..., used: ..., limited: ...` — the tenant quota is full. List currently active runs in the namespace:
-
-  ```bash
-  kubectl -n "$NS" get jobs -l paperclip.ai/managed-by=paperclip
-  ```
-
-  Either wait for inflight runs to drain or raise the per-tenant quota via the `cluster_tenant_policies` row.
-
-- `violates PodSecurity "restricted:..."` — the runtime image or pod spec violates the Restricted profile. The driver always emits Restricted-compliant specs, so this points to a customized agent image. Re-pull `agent-runtime-base` / `agent-runtime-claude` from `ghcr.io/paperclipai/` to confirm.
-
-## ImagePullBackOff
-
-Symptom: `kubectl get pods` shows `ImagePullBackOff` or `ErrImagePull`.
-
-Cause: the agent runtime image cannot be pulled from the cluster. The two paths to check:
-
-1. The namespace has the `paperclip-image-pull` `Secret`:
-
-   ```bash
-   kubectl -n "$NS" get secret | grep paperclip-image-pull
-   ```
-
-   If absent, re-run `paperclipai cluster ensure-tenant <clusterId> <companyId>` after confirming the cluster connection has `imagePullDockerConfigJson` resolved.
-
-2. The Pod actually references that Secret as an `imagePullSecret`:
-
-   ```bash
-   kubectl -n "$NS" get pod -l "paperclip.ai/run-id=$RUN" \
-     -o jsonpath='{.items[*].spec.imagePullSecrets}'
-   ```
-
-   Expected: `[{"name":"paperclip-image-pull"}]`. If empty, the cluster connection lacks an image registry binding — see [quickstart.md](./quickstart.md).
-
-For private registries that require cosign verification, see [security-model.md](./security-model.md).
-
-## Job failed but logs are empty
-
-Symptom: `kubectl get job` shows `Failed`; `kubectl logs <pod> -c agent` returns nothing.
-
-Cause: the `workspace-init` init container failed before the `agent` container ever started. Init logs are a different stream:
-
-```bash
-kubectl -n "$NS" logs -l "paperclip.ai/run-id=$RUN" -c workspace-init
-```
-
-Common init failures:
-
-- `git clone failed: authentication required` — the workspace strategy referenced a private repo but the bootstrap-exchange flow returned no usable git credentials. Confirm the agent's company has a configured git provider and that `POST /api/workspace/git-credentials` is reachable from the cluster.
-- `unsupported workspace strategy kind: ...` — the strategy JSON was not understood by `@paperclipai/workspace-strategy`. Look at `PAPERCLIP_WORKSPACE_STRATEGY` on the init container:
-
-  ```bash
-  kubectl -n "$NS" get pod -l "paperclip.ai/run-id=$RUN" \
-    -o jsonpath='{.items[*].spec.initContainers[?(@.name=="workspace-init")].env}'
-  ```
-
-## Bootstrap exchange returns 401
-
-Symptom: agent logs include `bootstrap exchange failed: 401 invalid_token` shortly after the agent container starts.
-
-Two likely causes:
-
-1. **`PAPERCLIP_PUBLIC_URL` misconfigured on the Job.** Confirm the value the pod was started with:
-
-   ```bash
-   kubectl -n "$NS" get pod -l "paperclip.ai/run-id=$RUN" \
-     -o yaml | grep -A1 PAPERCLIP_PUBLIC_URL
-   ```
-
-   The URL must be reachable from inside the cluster. For an in-cluster Paperclip server use the in-cluster Service DNS; for cross-cluster use the externally reachable HTTPS URL.
-
-2. **Clock skew.** Bootstrap tokens are short-lived. If the pod's clock is more than a few minutes off the server's clock the JWT expiry check fails. This is rare on managed clusters but appears on lab clusters using laptop nodes that suspend.
-
-3. **Server is missing `PAPERCLIP_RUN_JWT_SECRET`.** When the env var is absent, the callback routes are skipped during app boot (see `server/src/app.ts`). Confirm the server log line `mounted k8s callback routes` was emitted at startup. If not, set `PAPERCLIP_RUN_JWT_SECRET` on the server and restart.
-
-## Run was killed mid-flight
-
-Symptom: agent log ends abruptly with no exit message; `kubectl get pod` shows `Terminating` or the pod is gone.
-
-Inspect the Job's terminal state and recent events:
-
-```bash
-kubectl -n "$NS" describe job -l "paperclip.ai/run-id=$RUN"
-kubectl -n "$NS" get events --sort-by=.lastTimestamp | grep "$RUN"
-```
-
-Look for:
-
-- `BackoffLimitExceeded` — the agent crashed and Kubernetes gave up retrying.
-- `DeadlineExceeded` — `activeDeadlineSeconds` was hit. Look at the agent's runtime command to see whether the job was expected to take longer than the configured budget.
-- `OOMKilled` (in pod events) — the main container exceeded its memory limit. Adjust the per-tenant resource defaults in `cluster_tenant_policies` or pick a less memory-hungry adapter.
-
-## Correlate every resource for one run
-
-Every persisted resource carries `paperclip.ai/run-id=<runUlid>`:
-
-```bash
-kubectl get all,pvc,secrets -n "$NS" -l "paperclip.ai/run-id=$RUN"
-```
-
-Use this when forensics involves more than one object kind.
-
-## Related
-
-- [Agent execution flow](./agent-execution-flow.md) — the happy path this document mirrors
-- [Security model](./security-model.md) — what each isolation control is supposed to enforce
-- [Quickstart](./quickstart.md) — first-time setup and `cluster doctor`

docs/superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md

@@ -1,953 +0,0 @@
-# Paperclip Cloud Adapter — Multi-Tenant Kubernetes Execution
-
-**Date:** 2026-05-08
-**Status:** Spec — pending implementation plan
-**Owner:** Jannes Stubbemann (brainstorming session)
-
----
-
-## Executive Summary
-
-Add Kubernetes as a first-class execution target for Paperclip agent runs, with multi-tenant isolation as a design property of the orchestrator (not bolted on later). Every existing adapter (`claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `acpx_local`, `pi_local`, `hermes_local`) gains the ability to run inside a Kubernetes pod by selecting a `kubernetes` execution target — no per-adapter rewrites. Tenancy is enforced via namespace-per-company with the standard k8s-native isolation primitives (RBAC, ResourceQuota, NetworkPolicy, PodSecurity Restricted, per-namespace image pull credentials, ephemeral per-Job Secrets). Each agent gets a persistent `PersistentVolumeClaim` for warm workspaces; each run is an ephemeral `Job`. The orchestrator runs as library code inside the Paperclip server using `@kubernetes/client-node` — no separate operator binary, no CRDs, in V1.
-
-Cluster topology is hybrid by design: the same code path serves an in-cluster Paperclip (workloads in adjacent namespaces) and a cross-cluster Paperclip (control plane elsewhere; workload cluster reached via stored kubeconfig). Cross-cluster auth reuses the bootstrap-token → run-JWT exchange pattern already specified for the Cursor Cloud adapter.
-
-The Helm chart for the Paperclip control plane itself is **out of scope for this spec** — it's tracked separately and gated to ship after the cloud adapter lands.
-
----
-
-## Goals
-
-1. Run Paperclip agents on Kubernetes with strong tenant isolation suitable for multi-tenant SaaS.
-2. Keep adapters unchanged — extension via the existing `executionTarget` seam, not new adapter types.
-3. Single shared orchestration package; no per-adapter k8s code.
-4. Match k8s-native idioms: `Job`, `PVC`, `Namespace`, `NetworkPolicy`, `ResourceQuota`, `LimitRange`, `PodSecurity` Restricted.
-5. Reuse the bootstrap-token → run-JWT auth flow already shipped for the Cursor Cloud adapter — one server-side route, two callers.
-6. Support both same-cluster and cross-cluster topologies behind one configuration model.
-7. Security baseline aligned with NSA/CISA Kubernetes Hardening and CIS Kubernetes Benchmark.
-8. Operator-debuggable via standard tools: `kubectl get jobs -n paperclip-acme-corp`, audit log entries, structured run-level events.
-
-## Non-Goals (V1)
-
-- Helm chart for the Paperclip control plane (separate spec, gated to follow).
-- Per-company BYO cluster (one or more cluster connections at the *instance* level only).
-- Pod-per-agent mode (StatefulSet + KEDA scale-to-zero) — designed-for, not built.
-- External Secrets Operator integration — abstraction in place, no driver in V1.
-- VolumeSnapshot-based agent cloning.
-- `PaperclipAgentRun` CRD + reconciliation operator — not built unless reconciliation needs justify it.
-- Fine-grained image attestation enforcement (we sign; we don't enforce verify in admission).
-- IPv6 dual-stack pods.
-
----
-
-## Architectural Decisions
-
-| # | Decision | Rationale |
-|---|---|---|
-| 1 | Add a new `kubernetes` kind to the existing `AdapterExecutionTarget` rather than creating a `kubernetes_pod` adapter. | Every adapter inherits k8s execution for free. Single shared orchestrator. Matches the pattern already used for `ssh` and `sandbox`. |
-| 2 | Tenant boundary = `Namespace` per Paperclip company. | K8s-native isolation primitive. RBAC, ResourceQuota, NetworkPolicy, PSS labels all attach naturally. Free, mature, widely understood. |
-| 3 | Workload granularity inside a tenant = pod-per-run as a `Job`, with PVC-per-agent for warm workspaces. | Strict isolation per run; PVC reuse keeps workspaces warm without coupling pod lifetimes. Pod-per-company was rejected (poor isolation, doesn't actually save cluster cost). |
-| 4 | Hybrid topology with bootstrap-token auth. | One auth path serves SaaS (Paperclip on control-plane cluster, agents on workload cluster) and self-hosted single-cluster. Reuses cursor-cloud's exchange route. |
-| 5 | Imperative orchestration via `@kubernetes/client-node` from the Paperclip server. No CRDs, no operator binary. | Smallest moving parts. Reconciliation is delegated to k8s primitives (Job `backoffLimit`, `TTLAfterFinished`, `OwnerReferences`, `PodFailurePolicy`). Easy to test against `kind`. |
-| 6 | Workspace bootstrap = init container running the existing Paperclip workspace strategy. | Reuses existing strategy logic; agents see identical filesystem layout to local. Cold = full clone, warm = fetch+reset. |
-| 7 | Namespace naming = `paperclip-{companySlug}` (operator-friendly), with `-{shortHash}` fallback on collision or DNS-1123 overflow. | Slug already exists in Paperclip (URL `:companyPrefix`). `kubectl` users get human-readable names. Immutable `paperclip.ai/company-id` label is the canonical machine identifier. |
-| 8 | The platform-module surface is extended (in spec, not yet existing) with `registerExecutionTargetDriver()` to keep parity with `registerAgentAdapter()` / `registerStorageProvider()`. The k8s driver is the first registered driver. | Keeps the door open for third-party drivers (Nomad, ECS, Modal-style) without core changes later. Honors the user's "leverage the plugin system" intent within the actual extension model. |
-
----
-
-## 1. Architecture & Code Layout
-
-### 1.1 The seam
-
-The codebase already has `AdapterExecutionTarget` in `packages/adapter-utils/src/execution-target.ts` (today: `local`, `ssh`, `sandbox`). Add one new kind:
-
-```ts
-type AdapterExecutionTarget =
-  | LocalExecutionTarget
-  | SshExecutionTarget
-  | SandboxExecutionTarget
-  | KubernetesExecutionTarget;        // NEW
-
-interface KubernetesExecutionTarget {
-  kind: "kubernetes";
-  clusterConnectionId: string;
-  namespaceOverride?: string;          // rare; defaults to companySlug-derived name
-  imageOverride?: string;              // gated by per-cluster policy
-  resources?: {                        // overrides LimitRange defaults
-    requests?: { cpu?: string; memory?: string };
-    limits?:   { cpu?: string; memory?: string };
-  };
-  storage?: {
-    sizeGi?: number;                   // defaults to per-tenant policy
-    storageClass?: string;             // overrides ClusterConnection default
-  };
-  envOverrides?: Record<string, string>;  // resolved as secret_refs at materialization
-}
-```
-
-### 1.2 Code layout
-
-```
-packages/
-  adapters/
-    kubernetes-execution/                # NEW package: @paperclipai/execution-target-kubernetes
-      package.json
-      tsconfig.json
-      src/
-        index.ts                         # createKubernetesExecutionDriver()
-        driver.ts                        # one Job per run, streams stdout, returns AdapterExecutionResult
-        client.ts                        # @kubernetes/client-node thin wrapper
-        types.ts
-        orchestrator/
-          job.ts                         # Job spec builder
-          pvc.ts                         # PVC spec builder
-          secret.ts                      # ephemeral per-Job Secret materializer (interface + native impl)
-          namespace.ts                   # company → namespace ensure-and-tag
-          rbac.ts                        # ServiceAccount + Role + RoleBinding for the namespace
-          network-policy.ts              # default-deny + allowlist (vanilla + Cilium variants)
-          resource-quota.ts              # ResourceQuota + LimitRange from tenant policy
-          pod-security.ts                # restricted PSS context defaults
-          log-stream.ts                  # k8s log watch → onLog
-          event-watch.ts                 # Job/Pod Event watch → run log "[k8s]" prefix
-        bootstrap/
-          init-container.ts              # workspace-init container spec
-          callback-token.ts              # bootstrap-token issuance (calls server)
-        redaction.ts                     # secret value redaction layer
-      test/
-        unit/                            # spec builders, RBAC, NetworkPolicy, redaction
-        integration/                     # kind/k3d cluster, full lifecycle
-
-  adapter-utils/
-    src/
-      execution-target.ts                # MODIFIED — add KubernetesExecutionTarget kind
-
-server/
-  src/
-    adapters/
-      execution-target-registry.ts       # NEW — platform-module registry for drivers
-      execution-targets/
-        kubernetes.ts                    # registers @paperclipai/execution-target-kubernetes
-    routes/
-      agent-callback.ts                  # /api/agent-auth/exchange + /api/runs/:runId/events
-      agent-callback.test.ts             # (extend cursor-cloud's existing route)
-      workspace-git-credentials.ts       # NEW — /api/workspace/git-credentials
-    services/
-      cluster-connections.ts             # NEW — stored cluster connections (kubeconfig refs)
-      cluster-tenant-policies.ts         # NEW — quota/limit/image-override policies per tenant
-      workspace-strategy/                # REFACTORED — extracted shared library used by init container
-
-ui/
-  src/
-    adapters/
-      execution-target/
-        kubernetes-fields.tsx            # NEW — exec-target form for "kubernetes"
-    pages/
-      ClusterConnections.tsx             # NEW — operator UI: list, add, health
-      ClusterConnectionDetail.tsx        # NEW — per-cluster: namespaces, quotas, runs
-
-docker/
-  agent-runtime/                         # NEW — Paperclip-maintained runtime images
-    Dockerfile.base                      # distroless or ubuntu-slim + node + git + tini + nonroot
-    Dockerfile.claude                    # base + claude-code CLI
-    Dockerfile.codex
-    Dockerfile.gemini
-    Dockerfile.opencode
-    Dockerfile.acpx
-    Dockerfile.pi
-    Dockerfile.hermes
-```
-
-### 1.3 Data flow for one agent run
-
-```
-Paperclip server (control plane)
-
-  Heartbeat fires for agent A in company C
-       │
-       ▼
-  Adapter.execute(ctx) — ctx.executionTarget.kind === "kubernetes"
-       │
-       ▼
-  KubernetesExecutionDriver.run(ctx):
-   1. resolve cluster connection (from ctx.executionTarget.clusterConnectionId)
-   2. ensure namespace `paperclip-{companySlug}` (idempotent)
-   3. ensure RBAC, ResourceQuota, LimitRange, NetworkPolicies, image pull secret
-   4. ensure PVC `agent-{agentSlug}-workspace` (RWO, default StorageClass)
-   5. mint bootstrap token + run JWT scope
-   6. resolve secret_refs → materialize per-Job Secret (OwnerRef → Job)
-   7. submit Job:
-        initContainer  paperclip-workspace-init  → /workspace via existing strategy
-        container      agent-runtime-{adapterType}  → exec adapter CLI in /workspace
-   8. open k8s pods/log watch → forward chunks to ctx.onLog("stdout", chunk)
-   9. open k8s Events watch (Job + Pod) → forward warnings to onLog with [k8s] prefix
-  10. await Job completion or cancellation
-  11. read terminal status + map to AdapterExecutionResult (codes per §7.2)
-  12. TTLAfterFinished cleans up Job + Secret; PVC retained
-       ▲
-       │ Pod callbacks via /api/agent-auth/exchange + run JWT
-       │
-  Cluster (in-cluster or remote via stored kubeconfig)
-    Namespace: paperclip-{companySlug}
-      Job: agent-{agentSlug}-run-{ulid}
-        Pod
-          initContainer: paperclip-workspace-init  (resolves project_workspaces strategy)
-          container:     agent-runtime             (runs adapter CLI; logs via API)
-        volumes:
-          workspace  ← PVC agent-{agentSlug}-workspace (retained between runs)
-          tmp        ← emptyDir 1Gi
-          env        ← Secret agent-{agentSlug}-run-{ulid}-env (OwnerRef: Job)
-      NetworkPolicy: deny-all + paperclip-agent-egress
-      ResourceQuota / LimitRange (per-tenant policy)
-```
-
-### 1.4 Why this shape
-
-- **Reuses the existing executionTarget seam** — adapters do not change.
-- **Single trust boundary** — the namespace.
-- **No long-running daemon** — orchestrator is library code; no operator, no CRDs in V1.
-- **Built on k8s primitives** — `Job`, `OwnerReference`, `ResourceQuota`, `NetworkPolicy`, `PodSecurityAdmission`. Less code we own.
-- **Cross-cluster-ready from day one** — cluster connection is a stored kubeconfig ref; in-cluster is one connection type among many.
-
----
-
-## 2. Tenancy, Isolation & Cluster Connection
-
-### 2.1 Tenant boundary: `Namespace` per company
-
-**Naming.** `paperclip-{companySlug}` primary. Fallback `paperclip-{companySlug}-{base36(blake3(companyId))[:8]}` when:
-- slug overflows 63 chars after the `paperclip-` prefix (so slug ≤ 53 chars), or
-- a different company already owns that name in the same cluster (collision).
-
-The `paperclip.ai/company-id=<uuid>` label is the immutable machine identifier; the namespace name can change in edge cases without breaking identity.
-
-**Provisioning.** First time an agent in company C runs against cluster K, the driver runs an idempotent ensure-namespace path that creates (or upserts):
-
-| Object | Purpose |
-|---|---|
-| `Namespace` with labels `paperclip.ai/company-id`, `paperclip.ai/managed-by=paperclip`, PSS labels (`pod-security.kubernetes.io/enforce: restricted`, `audit: restricted`, `warn: restricted`) | Tenant root + admission profile |
-| `ServiceAccount paperclip-agent` with `automountServiceAccountToken: false` | Pod identity (zero RBAC by default) |
-| `ResourceQuota paperclip-tenant-quota` | Compute/storage/pod caps |
-| `LimitRange paperclip-tenant-limits` | Default + max per-pod requests/limits |
-| `NetworkPolicy default-deny-ingress` + `default-deny-egress` | Zero-trust baseline |
-| `NetworkPolicy paperclip-agent-egress` (vanilla) | L3/L4 allowlist |
-| `CiliumNetworkPolicy paperclip-agent-egress-l7` (when Cilium present) | L7/FQDN allowlist |
-| Optional `Secret paperclip-image-pull` | Per-tenant registry credentials |
-
-All objects carry `paperclip.ai/managed-by=paperclip` and `paperclip.ai/company-id=<id>`. The driver refuses to mutate any namespace lacking `paperclip.ai/managed-by=paperclip`.
-
-**Lifecycle.** Company archive → namespace labeled `paperclip.ai/archived=true`, quotas zeroed, retained for the standard data-retention grace period (default 30 days, matches plugin spec § 25.1). Operator purge via `paperclipai cluster purge --company <id>`.
-
-### 2.2 Pod identity: zero-trust by default
-
-The pod's ServiceAccount has **no RBAC**. `automountServiceAccountToken: false` is set on the pod spec. The driver's k8s identity (server-side) is a separate ServiceAccount (in-cluster) or kubeconfig user (cross-cluster) bound only to namespaces matching `paperclip-*`.
-
-### 2.3 NetworkPolicy: default-deny + allowlist (L3/L4)
-
-```yaml
-# default-deny-ingress
-podSelector: {}
-policyTypes: [Ingress]
-
----
-# default-deny-egress
-podSelector: {}
-policyTypes: [Egress]
-
----
-# paperclip-agent-egress (only the agent role)
-podSelector: { matchLabels: { paperclip.ai/role: agent-runtime } }
-policyTypes: [Egress]
-egress:
-  - to: # cluster DNS
-      - namespaceSelector: { matchLabels: { kubernetes.io/metadata.name: kube-system } }
-        podSelector:       { matchLabels: { k8s-app: kube-dns } }
-    ports: [{ port: 53, protocol: UDP }, { port: 53, protocol: TCP }]
-  - to: # in-cluster Paperclip control plane (when topology = same-cluster)
-      - namespaceSelector: { matchLabels: { paperclip.ai/role: control-plane } }
-        podSelector:       { matchLabels: { app.kubernetes.io/name: paperclip-server } }
-    ports: [{ port: 443, protocol: TCP }, { port: 3102, protocol: TCP }]
-  - to: # internet egress with internal ranges denied
-      - ipBlock:
-          cidr: 0.0.0.0/0
-          except:
-            - 10.0.0.0/8
-            - 172.16.0.0/12
-            - 192.168.0.0/16
-            - 169.254.0.0/16   # link-local incl. cloud metadata
-            - 100.64.0.0/10    # CGNAT
-            - fd00::/8         # IPv6 ULA
-    ports: [{ port: 443, protocol: TCP }]
-```
-
-The `except` blocks are the load-bearing security control: a compromised pod cannot reach cloud metadata, in-cluster databases, or internal services.
-
-### 2.4 Cilium variant (auto-detected, additive)
-
-When the cluster has `CiliumNetworkPolicy` available, the orchestrator generates a CNP **alongside** the vanilla NetworkPolicy. Vanilla stays as defense-in-depth.
-
-```yaml
-apiVersion: cilium.io/v2
-kind: CiliumNetworkPolicy
-metadata:
-  name: paperclip-agent-egress-l7
-spec:
-  endpointSelector: { matchLabels: { paperclip.ai/role: agent-runtime } }
-  egress:
-    - toFQDNs:
-        - matchPattern: "*.anthropic.com"
-        - matchPattern: "api.openai.com"
-        - matchPattern: "*.googleapis.com"
-        - matchPattern: "github.com"
-        - matchPattern: "*.github.com"
-        - matchPattern: "gitlab.com"
-        # ...composed from adapter.networkRequirements + tenantPolicy.additionalAllowFqdns
-      toPorts: [{ ports: [{ port: "443", protocol: TCP }] }]
-    - toEndpoints: [{ matchLabels: { paperclip.ai/role: control-plane } }]
-      toPorts: [{ ports: [{ port: "443", protocol: TCP }] }]
-```
-
-### 2.5 Pod Security Admission: `restricted`
-
-Namespace labeled `pod-security.kubernetes.io/enforce|audit|warn: restricted`. Every pod spec sets:
-
-```yaml
-securityContext:
-  runAsNonRoot: true
-  runAsUser: 1000
-  runAsGroup: 1000
-  fsGroup: 1000
-  seccompProfile: { type: RuntimeDefault }
-containers:
-  - securityContext:
-      allowPrivilegeEscalation: false
-      readOnlyRootFilesystem: true     # tmpfs at /tmp; PVC at /workspace
-      capabilities: { drop: [ALL] }
-```
-
-Satisfies NSA/CISA Kubernetes Hardening Guidance and CIS Kubernetes Benchmark.
-
-### 2.6 ResourceQuota & LimitRange
-
-Defaults (overridable per company plan in `cluster_tenant_policies`):
-
-```yaml
-# ResourceQuota
-hard:
-  requests.cpu:                    "16"
-  requests.memory:                 "64Gi"
-  limits.cpu:                      "64"
-  limits.memory:                   "256Gi"
-  requests.storage:                "200Gi"
-  count/jobs.batch:                "100"
-  count/persistentvolumeclaims:    "50"
-  count/secrets:                   "200"
-  count/configmaps:                "200"
-
-# LimitRange
-limits:
-  - type: Container
-    default:        { cpu: "1",    memory: "2Gi" }
-    defaultRequest: { cpu: "250m", memory: "512Mi" }
-    max:            { cpu: "8",    memory: "32Gi" }
-  - type: PersistentVolumeClaim
-    max: { storage: "20Gi" }
-```
-
-When a billing tier change happens, the driver re-applies the new quota.
-
-### 2.7 Cluster connection storage
-
-```ts
-interface ClusterConnection {
-  id: string;
-  label: string;
-  kind: "in-cluster" | "kubeconfig";
-  kubeconfigSecretRef?: SecretRef;     // resolved via Paperclip secret provider
-  apiServerUrl?: string;               // for display only
-  defaultNamespacePrefix: string;      // default "paperclip-"
-  capabilities: {
-    cilium: boolean;                   // auto-detected at connect time
-    storageClass: string;              // e.g. "gp3", "longhorn"
-    architectures: ("amd64" | "arm64")[];
-  };
-  paperclipPublicUrl?: string;          // override for cross-cluster topology
-  imageRegistry?: string;               // override for ghcr.io/paperclipai/*
-  createdAt: string;
-  createdBy: string;
-}
-```
-
-V1: instance-level operator-managed cluster connections (`pnpm paperclipai cluster add`). V2: per-company BYO cluster.
-
-### 2.8 Compliance bookkeeping
-
-- ✅ NSA/CISA Kubernetes Hardening Guidance — Restricted PSS, NetworkPolicy default-deny, no privilege escalation, no host network/PID/IPC, drop ALL caps, RuntimeDefault seccomp.
-- ✅ CIS Kubernetes Benchmark — namespace isolation, ResourceQuota, no auto-mounted SA tokens.
-- ✅ Internal blast-radius isolation — RFC1918 + link-local egress blocked, no shared SA across tenants.
-
-The release pipeline runs `kube-audit-kit` and `polaris` against a freshly provisioned tenant namespace; PSS Restricted violations or NSA Hardening regressions block release.
-
----
-
-## 3. Pod Lifecycle
-
-### 3.1 Job spec
-
-```yaml
-apiVersion: batch/v1
-kind: Job
-metadata:
-  name: agent-{agentSlug}-run-{ulid}
-  namespace: paperclip-{companySlug}
-  labels:
-    paperclip.ai/managed-by: paperclip
-    paperclip.ai/company-id: <uuid>
-    paperclip.ai/agent-id:   <uuid>
-    paperclip.ai/run-id:     <uuid>
-    paperclip.ai/role:       agent-runtime
-spec:
-  backoffLimit: 0                        # Paperclip owns retry semantics
-  ttlSecondsAfterFinished: 300           # log harvest, then GC
-  activeDeadlineSeconds: <min(adapterConfig.timeoutSec, namespaceQuota.maxRunSeconds)>
-  completions: 1
-  parallelism: 1
-  podFailurePolicy:
-    rules:
-      - action: FailJob
-        onPodConditions: [{ type: PodHasNetwork, status: "False" }]
-      - action: FailJob
-        onExitCodes: { containerName: agent, operator: In, values: [137] }   # OOM
-  template:
-    metadata:
-      labels:
-        paperclip.ai/role: agent-runtime
-        paperclip.ai/agent-id: <uuid>
-        paperclip.ai/run-id:   <uuid>
-      annotations:
-        paperclip.ai/job-spec-version: "v1"
-    spec:
-      automountServiceAccountToken: false
-      serviceAccountName: paperclip-agent
-      restartPolicy: Never
-      enableServiceLinks: false
-      terminationGracePeriodSeconds: 30
-      securityContext: { ... restricted PSS ... }
-      initContainers: [ workspace-init ]
-      containers:    [ agent ]
-      volumes:
-        - name: workspace
-          persistentVolumeClaim: { claimName: agent-{agentSlug}-workspace }
-        - name: tmp
-          emptyDir: { sizeLimit: 1Gi }
-        - name: env
-          secret: { secretName: agent-{agentSlug}-run-{ulid}-env, defaultMode: 0400 }
-        - name: skills-pointer
-          configMap: { name: paperclip-skills-pointer }
-```
-
-Key choices:
-- `backoffLimit: 0` — Paperclip owns retry semantics (`AdapterExecutionErrorFamily`, `retryNotBefore`). K8s never retries.
-- `ttlSecondsAfterFinished: 300` — gives log-watch time to drain final stdout, then GC removes Job + Pod + per-run Secret via `OwnerReferences`.
-- `activeDeadlineSeconds` — clamped to `min(adapterConfig.timeoutSec, namespaceQuota.maxRunSeconds)`.
-- `podFailurePolicy` — surfaces image-pull and OOM as terminal failures rather than consuming retry budget.
-- `automountServiceAccountToken: false` — agent has no business calling the k8s API.
-- `enableServiceLinks: false` — avoids env-var noise and minor info leak.
-
-### 3.2 Init container: workspace bootstrap
-
-```yaml
-initContainers:
-  - name: workspace-init
-    image: ghcr.io/paperclipai/agent-runtime-base:{paperclipVersion}
-    command: ["/usr/local/bin/paperclip-workspace-init"]
-    env:
-      - name: PAPERCLIP_WORKSPACE_STRATEGY
-        value: <serialized strategy from project_workspaces>
-      - name: PAPERCLIP_WORKSPACE_ROOT
-        value: /workspace
-      - name: PAPERCLIP_RUN_ID
-        value: <run-id>
-      - name: PAPERCLIP_BOOTSTRAP_TOKEN
-        valueFrom: { secretKeyRef: { name: agent-{agentSlug}-run-{ulid}-env, key: BOOTSTRAP_TOKEN } }
-    volumeMounts:
-      - { name: workspace, mountPath: /workspace }
-      - { name: tmp,       mountPath: /tmp }
-    securityContext: { ... restricted ... }
-    resources:
-      requests: { cpu: 200m, memory: 256Mi }
-      limits:   { cpu: "2",  memory: 1Gi }
-```
-
-`paperclip-workspace-init` behavior:
-
-1. Reads `PAPERCLIP_WORKSPACE_STRATEGY` (existing strategy types: `git-clone`, `git-worktree`, `existing-path` (rejected at validation), `none`).
-2. Cold PVC → full strategy. Git creds obtained via bootstrap-token → run-JWT exchange → `/api/workspace/git-credentials`. Creds written to init container's tmpfs only.
-3. Warm PVC → `git fetch && git reset --hard {ref}` (configurable; matches local adapter semantics).
-4. Writes `.paperclip-workspace-state.json` marker.
-5. Non-zero exit → Job fails with `errorCode: workspace_init_failed`.
-
-Init container shares the PVC with the main container but **not** the env Secret mount — credentials never leak forward.
-
-### 3.3 Main container: agent runtime
-
-```yaml
-containers:
-  - name: agent
-    image: <resolved per §5.2>
-    imagePullPolicy: IfNotPresent
-    workingDir: /workspace
-    command: ["/usr/local/bin/tini", "--"]
-    args:    ["/usr/local/bin/paperclip-agent-shim", "--adapter", "<type>"]
-    env:
-      - name: PAPERCLIP_RUN_ID
-        value: <run-id>
-      - name: PAPERCLIP_PUBLIC_URL
-        value: <resolved per §6.5>
-      - name: PAPERCLIP_BOOTSTRAP_TOKEN
-        valueFrom: { secretKeyRef: { name: ...env, key: BOOTSTRAP_TOKEN } }
-      - name: TRACEPARENT
-        value: <propagated from server span>
-      # ...adapter-specific keys (LLM keys, etc.) from the per-Job Secret
-    volumeMounts:
-      - { name: workspace,       mountPath: /workspace }
-      - { name: tmp,             mountPath: /tmp }
-      - { name: env,             mountPath: /run/paperclip/env, readOnly: true }
-      - { name: skills-pointer,  mountPath: /run/paperclip/skills, readOnly: true }
-    resources:
-      requests: { cpu: <from adapter or LimitRange default>, memory: ... }
-      limits:   { cpu: ...,                                  memory: ... }
-    securityContext:
-      runAsNonRoot: true
-      readOnlyRootFilesystem: true
-      allowPrivilegeEscalation: false
-      capabilities: { drop: [ALL] }
-      seccompProfile: { type: RuntimeDefault }
-```
-
-`tini` as PID 1 ensures SIGTERM forwarding. `paperclip-agent-shim`:
-1. Reads `AdapterRuntimeCommandSpec` from a config file projected by the orchestrator.
-2. Detects the adapter CLI (`installCommand` if missing).
-3. Reads the prerendered prompt (orchestrator-rendered).
-4. Exec-replaces itself into the actual adapter CLI so signals propagate.
-5. Frames structured stdout events compatible with existing UI parsers.
-
-No sidecars in V1. Logs flow via `pods/log` watch + structured-events callback (§3.4).
-
-### 3.4 Output streaming
-
-Two parallel streams merged by timestamp:
-
-| Source | Mechanism |
-|---|---|
-| stdout/stderr | `pods/log` watch with `sinceTime` reconnect → `ctx.onLog("stdout", chunk)` |
-| Structured events | `POST /api/runs/:runId/events` from agent shim with run JWT |
-| K8s `Event`s on Job/Pod | Events watch → `ctx.onLog("stdout", "[k8s] " + event)` |
-
-If the structured-events callback is unreachable (NetworkPolicy misconfig), events fall back to stdout framing — degraded but not broken.
-
-### 3.5 Cancellation
-
-User cancels run → registered cancellation handler:
-1. `kubectl delete job <name> --propagation-policy=Foreground --grace-period=30`
-2. K8s sends SIGTERM to PID 1 → `tini` → adapter CLI. 30s drain.
-3. After grace, SIGKILL.
-4. Pod terminates → log watch sees stream end → `AdapterExecutionResult { exitCode: null, signal: "SIGTERM", errorCode: "cancelled" }`.
-
-Foreground propagation ensures the Pod is gone before the API call returns; per-Job Secret GC'd via `OwnerReferences`. PVC untouched.
-
-### 3.6 Concurrent runs on the same agent
-
-PVC is `ReadWriteOnce` — only one pod can mount at a time.
-- Paperclip's heartbeat-level locking already prevents overlapping runs per agent.
-- Defensive: orchestrator checks for a live Job with the same `paperclip.ai/agent-id` label and returns `errorCode: "concurrent_run_blocked"` immediately rather than queueing.
-- For agents that legitimately need concurrent runs, switch the agent's storage class to ReadWriteMany (e.g. EFS, Azure Files, Longhorn) with the perf tradeoff documented.
-
----
-
-## 4. Workspace Persistence
-
-### 4.1 PVC lifetime is bound to the agent, not the run
-
-```yaml
-apiVersion: v1
-kind: PersistentVolumeClaim
-metadata:
-  name: agent-{agentSlug}-workspace
-  namespace: paperclip-{companySlug}
-  labels:
-    paperclip.ai/managed-by: paperclip
-    paperclip.ai/company-id: <uuid>
-    paperclip.ai/agent-id:   <uuid>
-    paperclip.ai/role:       agent-workspace
-  annotations:
-    paperclip.ai/workspace-strategy: <strategy-key>
-    paperclip.ai/created-at:         <iso>
-spec:
-  accessModes: [ReadWriteOnce]
-  storageClassName: <from ClusterConnection.capabilities.storageClass>
-  resources: { requests: { storage: <perAgentDefault, e.g. 10Gi> } }
-```
-
-Created on first run, reused for subsequent runs. Never auto-deleted on Job completion.
-
-### 4.2 Zonal pinning
-
-`ReadWriteOnce` cloud disks (EBS, PD-Standard, Azure Disk) are zone-bound. After first bind, the orchestrator reads the bound `PersistentVolume.spec.nodeAffinity` and adds matching `nodeAffinity` to subsequent pods so they land in the same zone. Operators who want multi-zone resilience choose a regional StorageClass (e.g. `pd-balanced` regional, EFS, Longhorn) — purely a StorageClass decision, no orchestrator code change.
-
-### 4.3 Reclaim & GC
-
-- PVC `persistentVolumeReclaimPolicy: Delete` (default for dynamic provisioning).
-- Agent archive → PVC labeled `paperclip.ai/archived=true`, retained for grace period (default 30 days).
-- Operator `paperclipai cluster purge --agent <id>` → immediate delete.
-- Company purge → namespace deletion cascades to all PVCs.
-- Daily stale PVC sweep flags PVCs with no matching `agents` row older than 7 days; surfaced in cluster-health UI; never auto-deleted.
-
-### 4.4 Quota interaction
-
-PVC storage counts against `requests.storage` and `count/persistentvolumeclaims` in the namespace `ResourceQuota`. Quota exhaustion → new agents cannot run; orchestrator returns `errorCode: "tenant_storage_quota_exhausted"` with remediation hint.
-
-### 4.5 Workspace strategy → init container interaction
-
-| Strategy | Init container behavior |
-|---|---|
-| `git-clone` | Cold: `git clone <url> --branch <ref> .`. Warm: `git fetch && git reset --hard origin/<ref>`. |
-| `git-worktree` | Cold: `git clone --bare` into `/workspace/.bare` then `git worktree add` per agent slot. Warm: `git fetch` + worktree update. |
-| `existing-path` | Rejected at execution-target config validation; not a runtime failure. |
-| `none` | Empty `/workspace`. |
-
-Strategy code is **shared** between local adapter and init container by extracting existing logic from `server/src/services/workspace-strategy/` (or wherever it currently lives) into a small library that the init container's binary links against. This is a planned refactor in the implementation plan.
-
-### 4.6 Snapshots & backup (V2, designed-for)
-
-- PVCs labeled and annotated for Velero/Kasten K10 selectors out of the box.
-- VolumeSnapshot CRDs reserved for V2 — `paperclipai cluster snapshot agent <id>` would create a `VolumeSnapshot` and a Paperclip record.
-- V2 use case: cloning an agent's workspace as the seed for a new agent (`PVC.dataSource: VolumeSnapshot`).
-
-### 4.7 Edge cases
-
-- Init container wedge → `activeDeadlineSeconds` catches.
-- Disk full mid-run → `errorCode: workspace_disk_full` with `df` snapshot from `kubectl exec`.
-- Corrupt workspace → init container detects `git status` non-clean and falls back to full reset; configurable per agent for agents that want dirty state preserved.
-- PVC orphan after stuck `Terminating` namespace → surfaced in cluster-health UI; explicit operator cleanup, never auto-resolved.
-
----
-
-## 5. Images & Secrets
-
-### 5.1 Image strategy: Paperclip-maintained, adapter-aligned
-
-Family of small images, not one fat image:
-
-| Image | Base | Contains |
-|---|---|---|
-| `ghcr.io/paperclipai/agent-runtime-base:{paperclipVersion}` | distroless or ubuntu-slim | `tini`, `git`, `paperclip-workspace-init`, `paperclip-agent-shim`, CA bundle, non-root uid/gid 1000 |
-| `agent-runtime-claude:{paperclipVersion}` | base | + `@anthropic-ai/claude-code` CLI |
-| `agent-runtime-codex:{paperclipVersion}` | base | + Codex CLI |
-| `agent-runtime-gemini:{paperclipVersion}` | base | + Gemini CLI |
-| `agent-runtime-opencode:{paperclipVersion}` | base | + OpenCode CLI |
-| `agent-runtime-acpx:{paperclipVersion}` | base | + ACPX CLI |
-| `agent-runtime-pi:{paperclipVersion}` | base | + Pi CLI |
-| `agent-runtime-hermes:{paperclipVersion}` | base | + Hermes CLI |
-
-Reasoning:
-- Per-adapter images are smaller (~150–250 MB) than a fat kitchen sink image.
-- Independent CLI version pinning per adapter.
-- Clear failure surface: "Codex CLI not found in image" is impossible because Codex isn't in the Claude image.
-
-`{paperclipVersion}` ties image **tags** to Paperclip release tags so `agent-runtime-claude:v2026.5.8` is unambiguous. The image *contents* (notably the bundled adapter CLI version) follow each adapter's own pinning cadence — a Paperclip release that doesn't bump the Claude CLI ships an `agent-runtime-claude:v2026.5.8` whose layered content is identical to the previous release. This keeps tag→content mapping deterministic without forcing a CLI rebuild on every Paperclip release.
-
-**Multi-arch.** Every image ships `amd64` + `arm64` via `docker buildx`.
-
-**Provenance.** `cosign` keyless OIDC signing in CI; SBOMs (`syft` → SPDX) attached as cosign attestations; `trivy` CVE scanning gates release.
-
-### 5.2 Image resolution: three levels of override
-
-```
-Effective image =
-  per-agent override     (adapterConfig.kubernetes.image; gated by per-cluster policy)
-  ?? per-tenant override (cluster_tenant_policies.imageOverrides[adapterType])
-  ?? cluster default     (ClusterConnection.imageRegistry + adapterType)
-  ?? Paperclip default   (ghcr.io/paperclipai/agent-runtime-{adapterType}:{paperclipVersion})
-```
-
-Per-agent override is gated by `ClusterConnection.allowAgentImageOverride: false` (default false). Even when enabled, the image must satisfy `imagePullPolicy: IfNotPresent` and an admission check that the namespace is not labeled `paperclip.ai/role: control-plane`.
-
-### 5.3 Per-namespace image pull credentials
-
-Per-namespace `kubernetes.io/dockerconfigjson` Secret resolved from the Paperclip secret store at namespace-ensure time. Not auto-rotated (rotation can break in-flight pulls); operator command `paperclipai cluster rotate-pull-secret --connection <id>` for explicit rotation.
-
-### 5.4 Per-Job ephemeral Secret for run credentials
-
-```yaml
-apiVersion: v1
-kind: Secret
-type: Opaque
-metadata:
-  name: agent-{agentSlug}-run-{ulid}-env
-  namespace: paperclip-{companySlug}
-  labels:
-    paperclip.ai/managed-by: paperclip
-    paperclip.ai/run-id: <uuid>
-  ownerReferences:
-    - apiVersion: batch/v1
-      kind: Job
-      name: agent-{agentSlug}-run-{ulid}
-      uid: <jobUid>
-      controller: true
-      blockOwnerDeletion: true
-data:
-  BOOTSTRAP_TOKEN:    <base64>
-  ANTHROPIC_API_KEY:  <base64>      # resolved from secret_ref
-  GIT_CREDENTIAL_KEY: <base64>      # short-lived handle, exchanged at runtime
-  # ...adapter-required keys, all from secret_refs
-```
-
-Properties:
-- Lifetime tied to the Job via `OwnerReferences` — TTL cleanup of the Job removes the Secret.
-- Mounted as **files** at `/run/paperclip/env` (mode 0400, uid 1000), and projected as env vars only for the keys the adapter CLI explicitly needs.
-- Materialized at Job-create time (resolve `secret_ref`s, build Secret, submit Job in a single transaction). On Job-create failure, Secret is explicitly deleted (no owner yet to GC it).
-- Secret values never written to logs, audit entries, error messages, or `resultJson`. Enforced by a redaction layer keyed by the materialized Secret's value set.
-
-### 5.5 Bootstrap token → run JWT exchange (shared with cursor-cloud)
-
-Same shape as the existing cursor-cloud route at `/api/agent-auth/exchange`:
-1. Pod has `BOOTSTRAP_TOKEN` (10 min TTL, run-scoped, single-use, bound to Job UID).
-2. `POST /api/agent-auth/exchange { bootstrapToken }` → `{ runJwt, expiresAt }`.
-3. Pod uses `runJwt` for `/api/runs/:runId/events`, `/api/skills/*`, `/api/workspace/git-credentials`.
-
-V1.5 second factor: bind the exchange request to the calling Pod's projected ServiceAccount token (`audience: paperclip-runtime`); server's `TokenReview` confirms the caller before issuing the run JWT. Cross-cluster topology defers this to V2 (needs identity federation).
-
-### 5.6 External Secrets Operator (V2, designed-for)
-
-V1 abstracts the per-Job Secret materialization behind a `SecretMaterializer` interface. V2 adds an `ExternalSecretMaterializer` that creates an `ExternalSecret` CR pointing at the customer's Vault/AWS SM/GCP SM and waits for ESO to materialize the underlying Secret before submitting the Job.
-
-### 5.7 Not in V1
-
-- Per-pod kubelet credential provider plugins.
-- Paperclip-managed cosign verification policy (we sign; we trust customers' admission controllers to verify).
-- Image rebuild on every Paperclip release for every adapter CLI version (CLI bumps follow their own cadence).
-
----
-
-## 6. Networking & Callback
-
-### 6.1 Three layers of egress control
-
-```
-Pod (agent-runtime)
-   ↓ ① NetworkPolicy (L3/L4 IP/port)            ← always on
-   ↓ ② Cilium L7 / FQDN policy                  ← if cluster supports it (auto-detected)
-   ↓ ③ Egress proxy (squid/Envoy)               ← optional, customer-managed
-   ↓
-external network
-```
-
-V1 ships ① and ②. ③ is documented; the runtime image honors `HTTP_PROXY`/`HTTPS_PROXY` env so customers can wire one in via tenant policy.
-
-### 6.2 Layer ① — vanilla NetworkPolicy
-
-See §2.3 for the full policies. The control-plane match-labels are a parameter of the cluster connection: in-cluster topology fills them with the Paperclip server's labels; cross-cluster omits the in-cluster rule entirely.
-
-### 6.3 Layer ② — Cilium variant
-
-See §2.4. The FQDN allowlist is per-tenant + per-adapter:
-- `adapter.networkRequirements.allowFqdns` (declared by the adapter package)
-- `tenantPolicy.additionalAllowFqdns` (operator-set per company)
-- Deny-by-default everywhere else.
-
-### 6.4 Layer ③ — egress proxy
-
-Tenant policy can set `httpProxyUrl: http://proxy.acme-corp.svc.cluster.local:3128`. Orchestrator injects `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`; `NO_PROXY` is auto-populated with kube-dns, the Paperclip Service, and pod/service CIDRs.
-
-### 6.5 Paperclip public URL resolution
-
-Resolution order:
-1. **In-cluster topology** → `https://paperclip-server.<paperclipNamespace>.svc.cluster.local:443`. Default when `ClusterConnection.kind === "in-cluster"` and the orchestrator can resolve the server's Service.
-2. **Cross-cluster topology** → `ClusterConnection.paperclipPublicUrl`, fallback `process.env.PAPERCLIP_PUBLIC_URL`. Validated reachable from the cluster at connection-add time via a one-shot Job that curls `/api/health`.
-3. **Per-agent override** — `adapterConfig.paperclipPublicUrl`. Rare; for agents crossing VPN boundaries.
-
-The resolved URL is injected as a literal `PAPERCLIP_PUBLIC_URL` env var in the pod spec (not in the per-Job Secret — it's not sensitive). The agent shim refuses to start if it's missing.
-
-### 6.6 Callback API surface
-
-| Endpoint | Auth | Used by | Source |
-|---|---|---|---|
-| `POST /api/agent-auth/exchange` | bootstrap token | first call from pod | shared with cursor-cloud |
-| `POST /api/runs/:runId/events` | run JWT | structured events | shared |
-| `POST /api/workspace/git-credentials` | run JWT | init container | k8s-specific |
-
-Rate limits on `/api/agent-auth/exchange`: 10/min/companyId, 1000/day/companyId. Bootstrap tokens are single-use; replay → `400 token_already_consumed`. Run JWT bearer-auth on subsequent calls; per-run rate limits 1000 events/min, 100MB/run total.
-
-### 6.7 Failure modes
-
-- DNS down inside cluster → `errorCode: dns_unreachable` with CoreDNS pod status in metadata.
-- Cilium policy denies a new domain → drop logs (Hubble) tee'd into run log when available; `errorCode: network_policy_denied`.
-- Paperclip server unreachable → bounded backoff (5 attempts, exponential, capped at 30s); after that `errorCode: control_plane_unreachable`, `errorFamily: transient_upstream`.
-- Token replay → orchestrator-internal retry once with fresh token, then fail.
-
----
-
-## 7. Observability, Failure Modes, Testing
-
-### 7.1 Logs
-
-Three tiers feeding the Paperclip run log buffer:
-
-| Source | Mechanism | Latency |
-|---|---|---|
-| Agent stdout/stderr | `pods/log` watch | live (~100ms) |
-| Structured events | `POST /api/runs/:runId/events` from agent shim | live |
-| Orchestrator + K8s `Event`s | server-local logs + `heartbeat_run_events` rows + `[k8s]`-prefixed lines | sync |
-
-Tier 3 catches things teams forget: a Job sitting Pending for 90s due to `ImagePullBackOff` shows up in the run log without `kubectl describe`.
-
-### 7.2 Metrics (Prometheus, exposed at server `/metrics`)
-
-```
-paperclip_k8s_runs_total{cluster, namespace, adapter_type, outcome}
-paperclip_k8s_run_duration_seconds{cluster, namespace, adapter_type}
-paperclip_k8s_pod_pending_seconds{cluster, namespace}
-paperclip_k8s_pvc_bytes{cluster, namespace, agent_id}
-paperclip_k8s_namespace_quota_used_ratio{cluster, namespace, resource}
-paperclip_k8s_orchestrator_api_errors_total{cluster, verb, code}
-paperclip_k8s_callback_requests_total{endpoint, status_code}
-```
-
-Customers worried about cardinality can drop the `namespace` label via Helm values.
-
-### 7.3 Tracing (OpenTelemetry)
-
-Server starts a span on `Adapter.execute`, propagates context as `TRACEPARENT` env into the per-Job Secret. Agent shim continues the trace. One trace per run with spans for orchestrator phases (ensure-namespace, materialize-secret, submit-job, await-completion) plus agent-side spans for prompt rendering and CLI invocation.
-
-### 7.4 Audit
-
-Every orchestrator mutation writes a Paperclip activity log entry with:
-- `actorType: "platform_module"`
-- `sourceModule: "kubernetes-execution-target"`
-- `targetCluster`, `targetNamespace`, `verb`, `outcome`
-
-Sufficient for SOC2-style audit trails.
-
-### 7.5 Failure mode catalog
-
-| Symptom | `errorCode` | Family | Retryable? |
-|---|---|---|---|
-| Image pull fails | `image_pull_failed` | `transient_upstream` | No (operator must fix image/pull-secret) |
-| OOM kill | `oom_killed` | — | No (resize agent's resource request) |
-| `activeDeadlineSeconds` hit | `timeout` | — | Per Paperclip's existing timeout policy |
-| Init container fails | `workspace_init_failed` | varies | Yes if `transient_upstream` (e.g. git server 503) |
-| Disk full | `workspace_disk_full` | — | No (PVC resize or workspace cleanup) |
-| Storage quota | `tenant_storage_quota_exhausted` | — | No (billing event) |
-| Compute quota | `tenant_compute_quota_exhausted` | — | No (billing event) |
-| Cluster unreachable from server | `cluster_unreachable` | `transient_upstream` | Yes |
-| Pod can't reach Paperclip | `control_plane_unreachable` | `transient_upstream` | Yes (with backoff) |
-| Cilium FQDN denied | `network_policy_denied` | — | No (operator must update policy) |
-| Concurrent run blocked | `concurrent_run_blocked` | — | Yes after current run completes |
-| Bootstrap token replay | `token_replay` | — | No (orchestrator retries once internally, then fails) |
-| Pod stuck `Pending` >5min | `pod_scheduling_failed` | `transient_upstream` | Yes (autoscaler may catch up) |
-| Workspace strategy unsupported on this target | `execution_target_unsupported_strategy` | — | No (config-validation-time error) |
-| DNS unreachable | `dns_unreachable` | `transient_upstream` | Yes |
-| User-initiated cancellation | `cancelled` | — | No (terminal by user intent) |
-
-Every code is documented with an inline UI remediation hint.
-
-### 7.6 Testing strategy
-
-**Unit (no cluster).** Bulk of suite. Pure builders:
-- Job spec builder → expected YAML (golden snapshots).
-- NetworkPolicy generator (vanilla + Cilium).
-- ResourceQuota / LimitRange builder per plan tier.
-- RBAC binding generator.
-- Secret materialization → no plaintext leakage in any return value.
-- ClusterConnection validation, namespace-name derivation, slug truncation.
-- Redaction layer on log lines, error messages, `resultJson`.
-
-**Integration (real cluster).** `kind`/`k3d` cluster spun up in CI via `testcontainers-node`:
-- Full run lifecycle for `claude_local` against a fake LLM endpoint.
-- Cancellation mid-run — Job deleted within grace, no orphan PVC/Secret.
-- Quota enforcement — submit 11 Jobs with quota of 10; 11th rejected with the right error code.
-- Multi-tenant isolation — two namespaces, concurrent agents, probe pod that tries cross-namespace traffic must fail.
-- PSS Restricted compliance — privileged Pod rejected at admission.
-- Image pull failure path → `errorCode: image_pull_failed` within 60s.
-- Workspace warm vs cold — second run faster, PVC reused.
-
-**Contract.** Every public type the driver exports has a contract test; the execution-target driver registry interface is the most important.
-
-**Security review gate.** `kube-audit-kit` and `polaris` run against a freshly provisioned tenant namespace in CI. PSS Restricted violations or NSA Hardening regressions block release.
-
-**Load.** Synthetic 100-concurrent-run test against `kind` to validate the orchestrator's k8s API call rate stays under default `--max-requests-inflight`. The orchestrator uses a shared informer + workqueue pattern, not raw `watch` per Job.
-
----
-
-## V1 Scope (Ships)
-
-- ✅ `KubernetesExecutionTarget` kind in `executionTarget`
-- ✅ `@paperclipai/execution-target-kubernetes` package — orchestrator + driver
-- ✅ `ClusterConnection` model + storage + UI form
-- ✅ Namespace-per-company provisioning with all isolation primitives (RBAC, ResourceQuota, NetworkPolicy, PSS labels, image pull secret)
-- ✅ Job-per-run with PVC-per-agent + init container workspace strategy
-- ✅ Per-Job ephemeral Secret materialization with redaction layer
-- ✅ Bootstrap-token → run-JWT auth path (extends cursor-cloud-shared route)
-- ✅ K8s log watch + structured events callback + K8s Events forwarding
-- ✅ Cancellation, TTL cleanup, OwnerReference GC
-- ✅ Cilium auto-detection + CNP variant
-- ✅ Paperclip-maintained agent runtime image family (multi-arch, signed)
-- ✅ Per-namespace image pull credentials
-- ✅ Operator UI: cluster connection list, per-cluster health, per-tenant quota dashboard
-- ✅ Failure-mode error codes with remediation hints
-- ✅ Audit log integration
-- ✅ Test suite (unit + kind integration + security gate)
-- ✅ Documentation: quickstart, security model, multi-tenant onboarding playbook
-- ✅ Workspace-strategy refactor: extract shared library used by init container
-
-## V2 (Designed-for, Deferred)
-
-- 🟡 BYO cluster per company (today: per-instance only).
-- 🟡 Pod-per-agent mode (StatefulSet + KEDA scale-to-zero) as a per-adapter knob.
-- 🟡 External Secrets Operator integration via `SecretMaterializer` interface.
-- 🟡 VolumeSnapshot-based agent cloning.
-- 🟡 `PaperclipAgentRun` CRD + reconciliation operator (only if needed).
-- 🟡 Helm chart for the Paperclip control plane itself.
-- 🟡 Fine-grained image attestation (cosign verify in admission).
-- 🟡 IPv6 dual-stack pod support (V1 deny-list is IPv4-shaped).
-- 🟡 Cross-cluster TokenReview second-factor (needs identity federation).
-
----
-
-## Risks & Open Questions
-
-1. **Workspace strategy refactor scope.** Lifting workspace-strategy code out of `server/` into a shared library is a real refactor. The implementation plan must scope it precisely to avoid creep.
-2. **PVC zonal pinning UX.** First-zone-binds-forever is correct but surprising. Cluster-connection setup must explicitly call this out, with regional StorageClass guidance front-and-center.
-3. **`executionTarget` plumbing audit.** This spec assumes every existing adapter (`claude_local`, `codex_local`, etc.) plumbs `executionTarget` correctly through to its execute path. The implementation plan must include an audit and any plumbing fixes.
-4. **Resource defaults for `claude_local` in a Pod.** Long sessions can spike memory significantly. Need empirical numbers (50 representative agents in `kind`, capture p99 memory) before locking LimitRange defaults. Defaults in this spec are a starting point. **RESOLVED in M3a (sizing.md scaffold + measurement test in place; operator runs the test out-of-band)**
-5. **Cross-cluster TokenReview.** The V1.5 second-factor on `/api/agent-auth/exchange` needs identity federation between clusters. Documented as V2.
-6. **`registerExecutionTargetDriver()` doesn't exist yet.** The platform-module registry surface is extended in this spec; the implementation plan should add the registry as a small explicit step before plugging in the k8s driver.
-7. **Adapter `networkRequirements` field doesn't exist on `ServerAdapterModule` yet.** Adding `networkRequirements?: { allowFqdns?: string[] }` to the adapter contract is a small addition the implementation plan must include.
-8. **Agent shim binary.** `paperclip-agent-shim` is new code. Scope, language (Go for static binary preferred), and packaging into the runtime image must be designed in the implementation plan.
-
----
-
-## Appendix: Decision Log
-
-| Decision | Chosen | Rejected alternative(s) | Reason |
-|---|---|---|---|
-| Extension shape | New `kubernetes` kind on `AdapterExecutionTarget` | New `kubernetes_pod` adapter; CRD/operator | Highest leverage; every adapter inherits k8s; smallest blast radius |
-| Tenant boundary | Namespace per company | Cluster per company; label-based isolation | K8s-native; free isolation primitives; cluster-per-company doesn't scale |
-| Workload granularity | Job-per-run + PVC-per-agent | Pod-per-company (shared); pod-per-agent (default); pod-per-run (ephemeral PVC) | Strict isolation per run + warm workspaces; pod-per-company has poor isolation and doesn't actually save cluster cost |
-| Topology | Hybrid (in-cluster + cross-cluster) with bootstrap auth | Same-cluster only; cross-cluster only | One auth path serves both deployments |
-| Orchestration runtime | Imperative `@kubernetes/client-node` from server | CRD + Go operator; CRD + TS operator | Smallest moving parts; reuse k8s primitives; runs are ephemeral |
-| Workspace bootstrap | Init container running existing strategy | Server pre-populates via `kubectl cp`; one-shot prepare Job | Reuses strategy code; same FS layout as local; scales cross-cluster |
-| Namespace naming | `paperclip-{companySlug}` (operator-friendly) | `paperclip-{shortHash}` (collision-safe by construction) | kubectl debuggability; immutable label remains canonical |
-| FQDN egress control | Cilium auto-detected; vanilla NetworkPolicy as floor | FQDN-required (Cilium hard dep); egress proxy required | Works with any CNI; tightens when Cilium is present; floor blocks RFC1918 + link-local |
-| Secret injection | Native k8s Secret per Job, OwnerRef-GC'd, mounted as files | ExternalSecrets Operator (V2); CSI Secret Store (V2) | Simplest correct V1; abstraction in place for V2 drivers |
-| Retry semantics | Owned by Paperclip (`backoffLimit: 0`) | Owned by k8s (`backoffLimit: 6`); shared | Paperclip already has `AdapterExecutionErrorFamily` + `retryNotBefore`; double-retry breaks billing/audit |
-
----
-
-## M3a status (as of 2026-05-09)
-
-Risk #4 (empirical resource defaults) is RESOLVED — `docs/k8s-execution/sizing.md` and `packages/adapters/kubernetes-execution/test/integration/empirical-measurement-claude.test.ts` together provide the measurement infrastructure; defaults retain M1's values pending operator measurement runs.
-
-M3a addendum at `docs/superpowers/specs/2026-05-09-paperclip-cloud-adapter-m3a-addendum.md` covers the four §1-§4 items: real claude-code test, real issueGitCredentials, empirical sizing, per-tenant Cilium DSL.
-
-*Spec ends.*

docs/superpowers/specs/2026-05-09-paperclip-cloud-adapter-m3a-addendum.md

@@ -1,300 +0,0 @@
-# Paperclip Cloud Adapter — M3a Addendum: Make M2 Production-Usable
-
-**Status**: Approved 2026-05-09. Implementation plan to follow.
-
-**Parent spec**: [2026-05-08-paperclip-cloud-adapter-design.md](./2026-05-08-paperclip-cloud-adapter-design.md)
-**M1 plan (shipped)**: [2026-05-08-paperclip-cloud-adapter-m1-plan.md](../plans/2026-05-08-paperclip-cloud-adapter-m1-plan.md)
-**M2 plan (shipped)**: [2026-05-09-paperclip-cloud-adapter-m2-plan.md](../plans/2026-05-09-paperclip-cloud-adapter-m2-plan.md)
-
-## Why this exists
-
-M2 shipped the full driver path with two stubs that block real production use:
-
-1. The end-to-end integration test uses a busybox+wget fake-agent because real `claude-code` requires an Anthropic key and a workspace with content. Until a real claude-code run succeeds, M2's "the agent works" claim has a gap.
-2. `issueGitCredentials` always returns `{ ok: false, reason: "not_configured" }`. Until it returns real credentials, the workspace-init container can't clone private repos.
-
-M2 also left two known TODOs:
-
-3. Resource defaults are M1's hand-picked values (Risk #4 in the parent spec, partially resolved in M2 with measurement infrastructure but the busybox workload isn't representative).
-4. Per-tenant Cilium policies are scaffolded but not wired through; every tenant gets the M1 default policy regardless of `cluster_tenant_policies` content.
-
-M3a closes all four gaps in one tactical PR, ~1 week of work. Operator UI, GitHub App credential issuance, multi-adapter coverage, cross-replica rate-limiting, and image allow-lists are explicitly **not** in M3a — they're M3b.
-
----
-
-## 1. Real claude-code end-to-end test
-
-### What changes
-
-- New integration test `test/integration/claude-code-real.test.ts` running real `claude-code` against real Anthropic, gated by `ANTHROPIC_API_KEY` env.
-- The M2 fake-agent test (`claude-end-to-end.test.ts`) stays as a cheap smoke — it doesn't need Anthropic and runs in every CI build.
-- The fake-agent Dockerfile + script (`_helpers/fake-agent.{Dockerfile,sh}`) are kept for the smoke test.
-
-### Test shape
-
-```ts
-describe.skipIf(!process.env.K8S_INTEGRATION || !process.env.ANTHROPIC_API_KEY)("real claude-code on kind", () => {
-  // beforeAll: spin kind, build agent-runtime-claude image, load into kind,
-  //            seed workspace PVC with a small repo via initContainer git-clone,
-  //            inject ANTHROPIC_API_KEY into the per-Job Secret.
-  it("reads README.md via tool-use and surfaces the project name", async () => {
-    const result = await driver.run({ ctx: { ...ctx, prompt: "Read README.md in /workspace and tell me the project name in one word." }, target });
-    expect(result.exitCode).toBe(0);
-    expect(capturedLogs.toLowerCase()).toContain("paperclip-claude-test");
-  });
-});
-```
-
-### Test seed repo
-
-A new fixture at `test/integration/_fixtures/test-repo/` containing:
-- `README.md` with `# paperclip-claude-test\n\nA small test repo for claude-code integration.\n`
-- `.gitignore` (empty, just to look like a real repo)
-
-The test creates the workspace by directly populating the PVC via a setup Pod that runs `git init && cp -r /fixtures/* . && git add . && git commit -m "init"`. This avoids needing the workspace-init container to call back to a server (workspace-init flows are exercised by M2's fake-agent test; this test focuses on the agent-side flow).
-
-### Cost
-
-~$0.01–0.05 per test run on Anthropic's API. The test is opt-in via `ANTHROPIC_API_KEY`; CI gates it on a designated key in repo secrets and skips on PRs from forks (no key access). Document in `docs/k8s-execution/CHANGELOG.md`.
-
-### Output
-
-- 1 new test file (~120 lines) + 1 fixture directory.
-- No production code changes. The `agent-runtime-claude` image was already built in M2; this just exercises it.
-
----
-
-## 2. Real `issueGitCredentials`
-
-### Architecture
-
-The existing `companySecrets` table + `SecretProvider` system already handles arbitrary per-company secrets resolved at runtime. M3a wires a specific use of it for git credentials.
-
-### Schema change
-
-Add to `cluster_tenant_policies`:
-
-```ts
-gitCredentialsSecretId: uuid("git_credentials_secret_id"),  // FK -> company_secrets.id, nullable
-```
-
-The secret holds a JSON-encoded `{ username: string, password: string }` (plaintext after decryption). Examples:
-
-- GitHub PAT: `{ "username": "x-access-token", "password": "ghp_xxxxxxxxxxxx" }`
-- GitLab deploy token: `{ "username": "deploy-paperclip", "password": "glpat-xxxxx" }`
-- Bitbucket app password: `{ "username": "user@email", "password": "ATBBxxxxx" }`
-
-The username/password format mirrors what the workspace-init container already injects into git via `GIT_USERNAME` / `GIT_PASSWORD` env vars. No protocol change.
-
-### Service implementation
-
-`server/src/services/git-credentials.ts`:
-
-```ts
-export interface IssueGitCredentialsInput {
-  companyId: string;
-  repoUrl: string;  // for logging/audit; we don't filter by URL in M3a
-}
-
-export async function issueGitCredentials(deps: { db: Db; secretService: SecretService; clusterTenantPolicies: ClusterTenantPoliciesService }, input: IssueGitCredentialsInput): Promise<IssueGitCredentialsResult> {
-  const policy = await deps.clusterTenantPolicies.resolveForCompany(input.companyId);
-  if (!policy?.gitCredentialsSecretId) return { ok: false, reason: "not_configured" };
-  const resolved = await deps.secretService.resolve(policy.gitCredentialsSecretId);
-  let parsed: { username?: unknown; password?: unknown };
-  try { parsed = JSON.parse(resolved.plaintext); } catch { return { ok: false, reason: "internal_error" }; }
-  if (typeof parsed.username !== "string" || typeof parsed.password !== "string") return { ok: false, reason: "internal_error" };
-  // 1h TTL is informational — the secret itself is long-lived; we surface
-  // a stable expiry to keep workspace-init's contract identical to a future
-  // GitHub App implementation.
-  const expiresAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();
-  return { ok: true, username: parsed.username, password: parsed.password, expiresAt };
-}
-```
-
-The route from M2 (`POST /api/workspace/git-credentials`) wires through this service instead of the M2 stub.
-
-### CLI helper
-
-```bash
-paperclip cluster set-git-credentials --company <id> --secret-id <secretUuid>
-```
-
-Updates the tenant policy row. The secret itself is created via the existing `paperclip secrets create` flow (or whatever the current secret-management UX is — verify in implementation). M3a does not add a new secret-creation path.
-
-### Limitations (acknowledged)
-
-- One credential per company. Tenants with multiple repos pointing at different orgs/hosts must use a single PAT that covers all of them, OR pick the most-restrictive shared PAT.
-- 1h TTL is fictional — the underlying secret is long-lived. The contract is stable for V2 (GitHub App) where TTL becomes real.
-- No per-repo scoping. A compromised PAT exposes every repo it has access to. Operators who need scoping must wait for V2 or use deploy keys.
-
-These are documented in `docs/k8s-execution/security-model.md` under a new "Git credentials in V1" section.
-
-### Output
-
-- Schema: 1 column on `cluster_tenant_policies` (combined with §4 in a single migration).
-- 1 new service (`git-credentials.ts`, ~50 lines + tests).
-- M2 route's stub replaced.
-- 1 new CLI subcommand.
-- ~3 new unit tests (configured/not-configured/malformed-secret).
-
----
-
-## 3. Empirical resource numbers
-
-### Workload
-
-Re-run M2's `empirical-measurement.test.ts` infrastructure with:
-
-- `agent-runtime-claude` image (real claude-code).
-- Same prompt as item 1: `"Read README.md and tell me the project name in one word."`
-- 5 sequential runs (one PVC, one Job per run, fresh Secret each).
-- `metrics-server` polling every 5s (M2 already wires this).
-
-This workload exercises the heaviest path of a typical agent run: prompt construction + tool use + Anthropic round-trip + response framing. It's still a single-turn run, which understates multi-turn workloads — but multi-turn varies wildly with task complexity, and a measured single-turn upper bound is enough to set sensible defaults.
-
-### Defaults update
-
-If measured peaks (across 5 runs) fit comfortably under M1's defaults (`requests: cpu=200m memory=256Mi`, `limits: cpu=2 memory=1Gi`), keep them. If peaks approach the limits, raise them with ~3× headroom on memory and ~2× on CPU.
-
-The threshold for "approach" is `peakMemoryMi > 0.6 * limitMi` or `peakCpuM > 0.5 * limitM`. Decision recorded in the commit message.
-
-### Doc update
-
-Replace `docs/k8s-execution/sizing-fake-agent.md` with `sizing.md` carrying:
-
-- Workload description (real claude-code, single-turn, README-summarize prompt)
-- Sample size (5 runs)
-- Peak / median / p95 of CPU and memory
-- Recommended defaults (the values in the new `defaultTenantLimits`)
-- Recommended `ResourceQuota` for a 50-agent tenant
-- "How we measured this" section pointing at the test file
-- Caveats: single-turn workload, not representative of long multi-turn tasks; operators should monitor actual usage and adjust quotas
-
-Resolves Risk #4 fully.
-
-### Output
-
-- ~30 lines changed in `resource-quota.ts` (constant updates).
-- ~1 file rewritten (`sizing.md`).
-- M2's `empirical-measurement.test.ts` updated to use the real image; ~20 lines changed.
-
----
-
-## 4. Per-tenant Cilium policies (DSL)
-
-### Schema
-
-Add two columns to `cluster_tenant_policies`:
-
-```ts
-ciliumDnsAllowlist:    text("cilium_dns_allowlist").array().notNull().default(sql`ARRAY[]::text[]`),
-ciliumEgressCidrs:     text("cilium_egress_cidrs").array().notNull().default(sql`ARRAY[]::text[]`),
-```
-
-Empty arrays = no override; the M1 default policy (default-deny + RFC1918/CGNAT/IPv6-ULA except) applies unchanged.
-
-### Semantics: additional CNP, intersection with M1
-
-The M1 CiliumNetworkPolicy defines a permissive egress allowlist (default-deny + kube-dns + non-RFC1918). M3a does **not** mutate M1's CNP. Instead, when `ciliumDnsAllowlist` or `ciliumEgressCidrs` is non-empty, a **second** CiliumNetworkPolicy is applied alongside the M1 baseline.
-
-Cilium evaluates multiple CNPs as an **intersection** for a given direction: traffic must be allowed by every selecting policy. So an M3a CNP that only permits `toFQDNs: [api.anthropic.com]` combines with the M1 CNP to produce an effective egress of "M1 baseline AND api.anthropic.com only" — i.e., locked down beyond the default.
-
-When both arrays are empty, no second CNP is created and the M1 baseline applies unchanged.
-
-### Builder
-
-New function `buildTenantCiliumPolicy(input)` returns either `null` (both arrays empty) or a CNP object:
-
-```ts
-function buildTenantCiliumPolicy(input: { namespace: string; companySlug: string; dnsAllowlist: string[]; egressCidrs: string[] }): CiliumNetworkPolicy | null {
-  if (input.dnsAllowlist.length === 0 && input.egressCidrs.length === 0) return null;
-  const egress: CnpEgressRule[] = [
-    // Always preserve kube-dns access — locking it out breaks every other rule
-    { toEndpoints: [{ matchLabels: { "k8s:io.kubernetes.pod.namespace": "kube-system", "k8s:k8s-app": "kube-dns" } }], toPorts: [{ ports: [{ port: "53", protocol: "ANY" }], rules: { dns: [{ matchPattern: "*" }] } }] },
-  ];
-  if (input.dnsAllowlist.length > 0) {
-    egress.push({ toFQDNs: input.dnsAllowlist.map((dns) => ({ matchName: dns })) });
-  }
-  if (input.egressCidrs.length > 0) {
-    egress.push({ toCIDR: input.egressCidrs });
-  }
-  return {
-    apiVersion: "cilium.io/v2",
-    kind: "CiliumNetworkPolicy",
-    metadata: { name: `paperclip-tenant-${input.companySlug}-restrict`, namespace: input.namespace },
-    spec: { endpointSelector: { matchLabels: { "paperclip.ai/managed-by": "paperclip" } }, egress },
-  };
-}
-```
-
-The "always preserve kube-dns" rule prevents the easy footgun where an operator sets `dnsAllowlist: ["api.anthropic.com"]` and accidentally blocks DNS resolution for `api.anthropic.com` itself.
-
-### `ensureTenantNamespace` wiring
-
-The orchestrator already takes a `tenantPolicy` parameter (M1). M3a calls `buildTenantCiliumPolicy(input)` after the M1 CNP is applied; if the result is non-null, it's applied as a second CNP. The existing M1 Cilium CRD client (added in M1 with `client.request`) handles the apply. Idempotency: the second CNP's name is deterministic per tenant, so repeat calls upsert.
-
-### Test
-
-- Unit test for the translator: empty arrays → identical to M1 output; populated → correct CNP rules.
-- Integration test against kind+Cilium (M1 already has this harness): apply policy with `ciliumDnsAllowlist: ["api.anthropic.com"]`, verify a blocked egress (e.g., a curl to `github.com`) is actually blocked.
-
-### Common operator recipes (documented)
-
-`docs/k8s-execution/cilium-recipes.md`:
-
-```
-Recipe 1: Anthropic-only tenant
-  ciliumDnsAllowlist: ["api.anthropic.com", "github.com"]
-  ciliumEgressCidrs: []   # no extra CIDR allowlist beyond M1 default
-
-Recipe 2: Self-hosted git tenant
-  ciliumDnsAllowlist: ["api.anthropic.com"]
-  ciliumEgressCidrs: ["10.42.0.0/16"]   # allow internal git host
-```
-
-### Output
-
-- Schema: 2 columns on `cluster_tenant_policies` (combined with §2 in a single migration).
-- New `buildTenantCiliumPolicy` function in `cilium-network-policy.ts` (~40 lines).
-- 2 new tests (1 unit + 1 integration on kind+Cilium).
-- 1 new doc file (`cilium-recipes.md`).
-
----
-
-## Out of scope for M3a
-
-- Operator UI for cluster connections, namespace bindings, tenant policies — M3b.
-- GitHub App for git credentials — V2 / on-demand.
-- Cross-replica rate limit store (Redis) — M3b.
-- Operator-controlled image allow-lists per cluster — M3b.
-- Multi-adapter k8s coverage (codex, gemini, opencode, acpx, pi, hermes) — M3b/M4.
-- Live run dashboard (log tail, event timeline) — M3b.
-
-## Risks / open questions
-
-| # | Risk | Disposition |
-|---|------|---|
-| A | `ANTHROPIC_API_KEY` exposure in CI | Use repo-secrets, never run real-Anthropic test on PRs from forks. Document. |
-| B | Single PAT covers multiple repos with too-broad scope | Acknowledged limitation; documented in security-model.md. V2 GitHub App resolves it. |
-| C | Empirical workload (single-turn README summarize) underestimates real usage | Defaults sized with 3× memory / 2× CPU headroom; sizing.md documents the limitation; operators advised to monitor actual usage. |
-| D | Tenant accidentally locks itself out by setting `ciliumDnsAllowlist` without including its git host | Documentation calls out the requirement; integration test asserts the behavior. No automated guardrail in M3a. |
-
-## Output summary
-
-- **One PR**, ~12-15 commits, targeting `master` after both M1 (#5556) and M2 (#5558) land.
-- **No new package** — all changes are in existing packages (server, kubernetes-execution, db).
-- **One schema migration** (3 new columns: `cluster_tenant_policies.git_credentials_secret_id`, `cluster_tenant_policies.cilium_dns_allowlist`, `cluster_tenant_policies.cilium_egress_cidrs`).
-- **No new spec doc** beyond this addendum.
-
-## Estimated work
-
-| Item | Days |
-|------|------|
-| 1. Real claude-code test | 1.5 |
-| 2. Real `issueGitCredentials` | 1.5 |
-| 3. Empirical numbers | 1.0 |
-| 4. Per-tenant Cilium DSL | 2.0 |
-| Cross-cutting (CHANGELOG, docs polish) | 0.5 |
-| **Total** | **6.5** |
-
-Roughly one focused week.

docs/superpowers/specs/2026-05-09-paperclip-cloud-adapter-m3b-spec.md

@@ -1,306 +0,0 @@
-# Paperclip Cloud Adapter — M3b Spec: Hardening + Multi-Adapter Coverage
-
-**Status:** Approved 2026-05-09. Implementation plan to follow.
-
-**Parent spec:** [2026-05-08-paperclip-cloud-adapter-design.md](./2026-05-08-paperclip-cloud-adapter-design.md)
-**M3a addendum (currently in PR #5565):** [2026-05-09-paperclip-cloud-adapter-m3a-addendum.md](./2026-05-09-paperclip-cloud-adapter-m3a-addendum.md)
-
-## Why this exists
-
-M3a closed the four production-readiness gaps the M2 design left (real claude-code test, real `issueGitCredentials`, empirical sizing scaffolding, per-tenant Cilium DSL). Three classes of work remain before the cloud adapter is a complete production-grade feature:
-
-1. **Multi-replica server scaling.** M2's in-memory rate limiter evades cross-replica enforcement. Multi-replica deployments hit different processes and bypass the bootstrap-token-exchange and runs-events throttling.
-
-2. **Per-cluster image governance.** `cluster_connections.allowAgentImageOverride` is a coarse on/off boolean. Operators can't restrict image overrides to specific registries — they get all-or-nothing.
-
-3. **Adapter breadth.** M2/M3a only run `claude_local`. The other adapters Paperclip supports locally (codex, gemini, opencode, acpx, pi, hermes) need cloud runtime images.
-
-M3b ships all three in one tactical PR. **Operator UI and live run dashboard are deferred to M3c** — they add UX/frontend work that needs separate scoping.
-
----
-
-## 1. Cross-replica Redis rate limit store
-
-### Problem
-
-`server/src/routes/k8s-callback.ts` defines `createSlidingWindowLimiter(opts)` returning a `SlidingWindowLimiter` with `consume(key)` and `stop()`. The implementation tracks hits in a `Map<string, number[]>` per process. Three limiters exist:
-
-- `exchangeLimiter` — 10 req/min per client IP, gates `/agent-auth/exchange`
-- `eventsLimiter` — 1000 req/min per `run:<runId>`, gates `/runs/:runId/events`
-- `gitCredsLimiter` — 30 req/min per `run:<runId>` (or IP fallback), gates `/workspace/git-credentials`
-
-In a multi-replica deployment (e.g. K8s Deployment with `replicas: 3`), an attacker — or even a normal client behind a load balancer — distributes their requests across processes and each process sees a fraction of the volume. Effective limit becomes `replicas × configured-limit`.
-
-### Design
-
-Add a Redis-backed implementation that satisfies the existing `SlidingWindowLimiter` interface. Selection happens once at server startup based on `PAPERCLIP_REDIS_URL`:
-
-```ts
-function createLimiter(opts: { name: string; windowMs: number; max: number }): SlidingWindowLimiter {
-  const url = process.env.PAPERCLIP_REDIS_URL?.trim();
-  if (url) return createRedisSlidingWindowLimiter({ url, ...opts });
-  logger.warn("PAPERCLIP_REDIS_URL not set; using in-memory rate limiter (single-replica only)");
-  return createSlidingWindowLimiter(opts);
-}
-```
-
-The factory takes a `name` (e.g. `"exchange"`) so Redis keys are namespaced per limiter.
-
-### Storage
-
-One Redis sorted set per (limiter, key) pair:
-
-- Key: `paperclip:rl:<limiter-name>:<consume-key>`
-- Member: a unique nonce (timestamp + random suffix) to support concurrent ZADDs
-- Score: timestamp in ms
-
-`consume(key)` runs (in a single Lua script for atomicity):
-
-```lua
-local now = tonumber(ARGV[1])
-local windowMs = tonumber(ARGV[2])
-local max = tonumber(ARGV[3])
-redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now - windowMs)
-local count = redis.call('ZCARD', KEYS[1])
-if count >= max then
-  local oldest = redis.call('ZRANGE', KEYS[1], 0, 0, 'WITHSCORES')
-  return { 0, tonumber(oldest[2]) + windowMs - now }
-end
-redis.call('ZADD', KEYS[1], now, ARGV[4])  -- ARGV[4] = unique nonce
-redis.call('PEXPIRE', KEYS[1], windowMs * 2)
-return { 1, 0 }
-```
-
-Returns `{1, 0}` for allowed, `{0, retryAfterMs}` for rate-limited. The `PEXPIRE` bounds key lifetime so abandoned keys don't accumulate.
-
-### Connection management
-
-The Redis client is created once at server startup and shared across limiters. Connection failures during `consume()` fail open — log a warning and allow the request. Better to admit a request that should have been throttled than to 500 the entire endpoint when Redis blips.
-
-### Configuration
-
-- `PAPERCLIP_REDIS_URL` — required for production multi-replica deployments. Format `redis://[:password@]host:port[/db]` or `rediss://...` for TLS.
-- Documented in `docs/k8s-execution/security-model.md` (new section "Production rate limiting").
-
-### Files
-
-- New: `server/src/routes/_limiter-redis.ts` (~120 lines including the Lua script as a string + the unit tests against an embedded Redis or `redis-mock`)
-- Modify: `server/src/routes/k8s-callback.ts` — `createLimiter` factory, replace direct `createSlidingWindowLimiter` calls
-- Modify: `server/package.json` — add `redis: ^4.7.0`
-- Modify: `docs/k8s-execution/security-model.md` — append "Production rate limiting" section
-
-### Tests
-
-- Unit test the Redis impl against `ioredis-mock` or `redis-mock` covering: allow-under-limit, deny-at-limit, deny-with-correct-retry-after, eviction-after-window.
-- Integration test against a real Redis container (only runs with `K8S_INTEGRATION=1` and a Redis URL).
-
-### Output
-
-- ~120 lines of new code + tests
-- One new dep
-- One docs section
-
-**Estimated work: 2 days.**
-
----
-
-## 2. Per-cluster image allow-list
-
-### Problem
-
-`cluster_connections.allowAgentImageOverride` is a coarse `boolean` (stored as `text` "true"/"false" per the existing schema). Today's behavior:
-
-- `false` → driver ignores `target.imageOverride`
-- `true` → driver accepts any `target.imageOverride`
-
-Operators who want "allow overrides only to my private registry" or "only `paperclipai/*` and `internal-registry.acme.com/agents/*`" have no path. The boolean is too coarse for any real security posture.
-
-### Design
-
-Add a `text[]` column `image_allowlist` on `cluster_connections`. Semantics:
-
-- **Empty array** (default) → preserves M2 behavior: respect `allowAgentImageOverride` boolean alone
-- **Non-empty array** → both the default adapter image AND `target.imageOverride` (if any) must string-start-with one of the prefixes
-
-The two-mode shape is a deliberate transition aid. M3b doesn't drop `allowAgentImageOverride`; M4 does, after operators have migrated.
-
-### Enforcement
-
-In `driver.run()`, **before** `createAgentJob(client, job)`:
-
-```ts
-const allowlist = connection.imageAllowlist ?? [];
-if (allowlist.length > 0) {
-  const baseImage = runContext.image;  // resolved adapter image
-  const overrideImage = target.imageOverride;
-  const baseAllowed = allowlist.some(p => baseImage.startsWith(p));
-  if (!baseAllowed) {
-    return { exitCode: null, errorCode: "image_not_allowed",
-             errorMessage: `Adapter image ${baseImage} not in cluster allow-list` };
-  }
-  if (overrideImage !== undefined && !allowlist.some(p => overrideImage.startsWith(p))) {
-    return { exitCode: null, errorCode: "image_not_allowed",
-             errorMessage: `Override image ${overrideImage} not in cluster allow-list` };
-  }
-}
-// fall through to existing allowAgentImageOverride boolean check
-```
-
-### Schema
-
-Migration `0085_cluster_image_allowlist.sql`:
-
-```sql
-ALTER TABLE "cluster_connections"
-  ADD COLUMN "image_allowlist" text[] NOT NULL DEFAULT ARRAY[]::text[];
-```
-
-Drizzle schema gets:
-
-```ts
-imageAllowlist: text("image_allowlist").array().notNull().default(sql`ARRAY[]::text[]`),
-```
-
-The `ResolvedClusterConnection` type in `packages/adapters/kubernetes-execution/src/types.ts` gains `imageAllowlist: string[]`. The `cluster-connections.ts` server service surfaces it on read and accepts it on `update()`.
-
-### CLI
-
-New subcommand:
-
-```bash
-paperclip cluster set-image-allowlist --cluster <id> --prefixes "ghcr.io/paperclipai/,internal.acme.com/agents/"
-```
-
-- `--prefixes ""` (empty) clears the list
-- Comma-separated, trimmed, empty entries dropped (mirrors `set-cilium-policy` from M3a)
-
-The CLI dispatcher gets one new case `set-image-allowlist`. The handler updates the `cluster_connections` row directly (this is per-cluster config, not per-tenant).
-
-### Image-name semantics
-
-Prefix matching is the only check. Tag pinning, signature verification, and vulnerability scanning are out of scope. The prefix check is sufficient to enforce "only my registry" — operators who want stronger guarantees use admission controllers (e.g. cosign-policy-controller) at the cluster level.
-
-### Files
-
-- Migration `packages/db/src/migrations/0085_cluster_image_allowlist.sql` + snapshot meta
-- Drizzle schema update at `packages/db/src/schema/cluster_connections.ts`
-- Server service update at `server/src/services/cluster-connections.ts`
-- Type extension at `packages/adapters/kubernetes-execution/src/types.ts`
-- Driver enforcement at `packages/adapters/kubernetes-execution/src/driver.ts` (~10 lines)
-- New CLI subcommand at `cli/src/commands/cluster.ts`
-- Tests for builder, enforcement, CLI
-
-### Tests
-
-- Unit: driver returns `image_not_allowed` for a non-matching override; allows the matching one; empty allow-list preserves M2 behavior.
-- CLI: parses `--prefixes`, calls `update()` with the right shape; clears on empty string.
-
-### Output
-
-- 1 migration column + Drizzle schema snapshot
-- ~30 lines of driver enforcement
-- ~50 lines CLI subcommand + tests
-- Type extension propagated through 3 files
-
-**Estimated work: 3 days.**
-
----
-
-## 3. Multi-adapter Kubernetes coverage — all 6
-
-### Problem
-
-M2 and M3a exercise only `claude_local` (the `agent-runtime-claude` image). Customers asking for codex, gemini, opencode, acpx, pi, or hermes on the cloud adapter currently can't use it.
-
-### Pattern (per adapter)
-
-Each adapter follows the M2 precedent set by `claude_local`:
-
-1. **Runtime image** at `docker/agent-runtime/Dockerfile.<adapter>` extending `paperclipai/agent-runtime-base`. Installs the adapter's CLI globally (e.g. `npm i -g @anthropic-ai/claude-code` for `claude_local`; the equivalent for each other adapter).
-
-2. **Per-adapter env mapping** in `driver.ts`: which keys from the per-Job env Secret get materialized for the agent-shim. Today the agent-shim reads `claude_local`'s `ANTHROPIC_API_KEY`. Each new adapter gets a small `Record<adapterType, string[]>` mapping.
-
-3. **Per-adapter `adapterAllowFqdns` defaults** injected into `ensureTenantNamespace` so the M1 baseline NetworkPolicy + Cilium CNP allow the adapter to reach its API:
-
-   - `codex` → `api.openai.com`
-   - `gemini` → `generativelanguage.googleapis.com`
-   - `opencode` → verify the actual host before commit
-   - `acpx` → `api.anthropic.com` (acpx wraps Anthropic)
-   - `pi` → verify against the local adapter's config
-   - `hermes` → verify against the local adapter's config
-
-   These defaults live as a TypeScript constant in `driver.ts`, easy to update.
-
-4. **Smoke test** at `test/integration/<adapter>-smoke.test.ts` mirroring `claude-end-to-end.test.ts`'s busybox-fake pattern. Builds the per-adapter image, loads it into kind, runs a fake-Anthropic-style stub, asserts the pod boots and the agent-shim invokes the right CLI.
-
-### Real-LLM tests
-
-Out of scope for M3b. The `claude-code-real.test.ts` template (M3a Task 13) is the precedent; operators who want real-LLM tests for new adapters add their own equivalents. The cost-and-key-management story doesn't justify burning a CI budget on six real-LLM tests.
-
-### Image tags
-
-All 6 follow `paperclipai/agent-runtime-<adapter>:vX.Y.Z`, parallel to `agent-runtime-claude`. The `imagesByAdapter` map in `KubernetesDriverDeps` (M2) becomes the single configuration point.
-
-### Sequencing within M3b
-
-The first new adapter (recommend `codex` — most likely customer ask) shakes out the pattern. ~2 days. Once shaken out:
-
-- `gemini`, `opencode`, `acpx`, `pi`, `hermes` each ~1 day = 5 days
-
-Each adapter ships as a separate commit (or stack of commits) within the M3b branch. If adapter #6 hits friction, we land 5/6 in M3b and split the last to a follow-up PR — the milestone isn't blocked by one stuck adapter.
-
-### Files per adapter
-
-- `docker/agent-runtime/Dockerfile.<adapter>`
-- Diff to `packages/adapters/kubernetes-execution/src/driver.ts` (env mapping + FQDN defaults entry)
-- New `packages/adapters/kubernetes-execution/test/integration/<adapter>-smoke.test.ts`
-
-### Cross-cutting
-
-- New `docs/k8s-execution/adapters.md` table listing each adapter with its image tag, env keys, and FQDNs.
-
-### Output
-
-- 6 Dockerfiles
-- 6 smoke tests
-- ~12 lines per adapter in `driver.ts` (env + FQDN entries)
-- 1 new docs page
-
-**Estimated work: 12 days (2 + 5 × 1 = 7 best-case; 12 with friction buffer).**
-
----
-
-## Out of scope for M3b → M3c
-
-- Operator UI for cluster connections, namespace bindings, tenant policies
-- Live run dashboard (log tail + event timeline)
-- Helm chart packaging
-- Image signing / cosign / sigstore verification
-- GitHub App for git credentials (V2 / on-demand, regardless of milestone)
-- New adapter additions beyond the existing six (e.g. third-party adapters customers ship themselves)
-
-## Risks
-
-| # | Risk | Mitigation |
-|---|------|------------|
-| A | Multi-adapter scope balloons; one or two adapters hit friction (FQDN unknown, CLI quirks) | Each adapter ships as a separate commit/PR within M3b. Land what works; split blockers to a follow-up. M3b PR isn't gated by adapter #6. |
-| B | Redis adds operational dependency operators don't have | In-memory fallback + warn log preserves dev/single-replica UX. Documented in `security-model.md`. Helm chart in M3c (or M4) may bundle Redis. |
-| C | Image allow-list schema migration on hot table | Additive column with default = no behavior change for existing rows. Reversible via `DROP COLUMN`. |
-| D | Adapter FQDNs drift over time as upstream APIs add domains | Constants are easy to update; smoke tests don't hit real APIs so they don't break on drift. Operators can override per-tenant via the existing `additionalAllowFqdns` mechanism. |
-
-## Estimated work
-
-| Item | Days |
-|------|------|
-| 1. Redis rate limit | 2 |
-| 2. Image allow-list | 3 |
-| 3. 6 adapter runtimes | 12 |
-| Cross-cutting (CHANGELOG, docs, integration plumbing) | 1 |
-| **Total** | **18 = ~3.5 weeks** |
-
-## Output summary
-
-- **One PR**, ~30–40 commits, layered on master after M3a (#5565) merges
-- **One schema migration** (`0085`), single column on `cluster_connections`
-- **No new package** — all changes in existing packages
-- **One new dep** (`redis`), one new docs page (`adapters.md`), one new docs section (Production rate limiting in `security-model.md`)

packages/adapter-utils/src/contract-kubernetes-rejection.test.ts

@@ -1,117 +0,0 @@
-/**
- * Contract test: every existing local adapter must return a structured error
- * (errorCode: "execution_target_not_yet_supported") when given a kubernetes
- * execution target, rather than throwing or crashing.
- *
- * This is the M1 spec Risk #3 guard: adapters must fail-fast with a clear
- * message so users who configure a kubernetes target see a helpful response
- * instead of an unhandled exception.
- *
- * Imports use relative paths that cross package boundaries — this works under
- * vitest (which uses vite transforms) but is intentionally outside the
- * TypeScript rootDir. The paths below resolve relative to this file's location
- * at packages/adapter-utils/src/.
- */
-
-import { describe, it, expect } from "vitest";
-import type { AdapterExecutionContext, AdapterExecutionResult } from "./types.js";
-import type { AdapterKubernetesExecutionTarget } from "./execution-target.js";
-
-const k8sTarget: AdapterKubernetesExecutionTarget = {
-  kind: "kubernetes",
-  clusterConnectionId: "test-cluster-connection-1",
-};
-
-function makeCtx(): AdapterExecutionContext {
-  return {
-    runId: "r-contract-test-1",
-    agent: {
-      id: "a-1",
-      companyId: "c-1",
-      name: "contract-test-agent",
-      adapterType: "test",
-      adapterConfig: {},
-    },
-    runtime: {
-      sessionId: null,
-      sessionParams: null,
-      sessionDisplayId: null,
-      taskKey: null,
-    },
-    config: {},
-    context: {},
-    onLog: async () => {},
-    executionTarget: k8sTarget,
-  };
-}
-
-/**
- * Each entry: [display name, relative path from this file to the adapter's execute.ts].
- * Relative paths cross package boundaries; vitest resolves them correctly at
- * runtime even though tsc would reject them (rootDir constraint).
- */
-const adapterModules: ReadonlyArray<readonly [string, () => Promise<{ execute: (ctx: AdapterExecutionContext) => Promise<AdapterExecutionResult> }>]> = [
-  [
-    "claude_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/claude-local/src/server/execute.js"),
-  ],
-  [
-    "codex_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/codex-local/src/server/execute.js"),
-  ],
-  [
-    "gemini_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/gemini-local/src/server/execute.js"),
-  ],
-  [
-    "opencode_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/opencode-local/src/server/execute.js"),
-  ],
-  [
-    "acpx_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/acpx-local/src/server/execute.js"),
-  ],
-  [
-    "pi_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/pi-local/src/server/execute.js"),
-  ],
-  [
-    "cursor_local",
-    // @ts-expect-error — cross-package relative import; valid at vitest runtime
-    () => import("../../adapters/cursor-local/src/server/execute.js"),
-  ],
-];
-
-describe("adapter contract: kubernetes execution target is rejected in M1", () => {
-  for (const [name, doImport] of adapterModules) {
-    it(`${name}: returns errorCode="execution_target_not_yet_supported" instead of throwing`, async () => {
-      let mod: { execute: (ctx: AdapterExecutionContext) => Promise<AdapterExecutionResult> };
-      try {
-        mod = await doImport();
-      } catch (e) {
-        console.warn(
-          `[contract] Could not import adapter "${name}": ${(e as Error).message} — skipping`,
-        );
-        return;
-      }
-
-      if (typeof mod.execute !== "function") {
-        throw new Error(`Adapter "${name}" does not export an \`execute\` function`);
-      }
-
-      const result = await mod.execute(makeCtx());
-
-      // Must not throw — must return a structured result
-      expect(result).toBeDefined();
-      expect(result.exitCode).toBeNull();
-      expect(result.errorCode).toMatch(/kubernetes|execution_target/i);
-      expect(result.errorMessage ?? "").toContain("Kubernetes");
-    });
-  }
-});

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

@@ -7,26 +7,8 @@ import {
   resolveAdapterExecutionTargetCwd,
   runAdapterExecutionTargetProcess,
   runAdapterExecutionTargetShellCommand,
-  describeAdapterExecutionTarget,
-  ensureAdapterExecutionTargetCommandResolvable,
-  readAdapterExecutionTargetHomeDir,
-  adapterExecutionTargetSessionMatches,
-  adapterExecutionTargetSessionIdentity,
-  parseAdapterExecutionTarget,
-  resolveAdapterExecutionTargetCommandForLogs,
 } from "./execution-target.js";
 
-describe("describeAdapterExecutionTarget — kubernetes kind", () => {
-  it("returns a human-readable description for a kubernetes target", () => {
-    const desc = describeAdapterExecutionTarget({
-      kind: "kubernetes",
-      clusterConnectionId: "c-123",
-    });
-    expect(desc).toContain("kubernetes");
-    expect(desc).toContain("c-123");
-  });
-});
-
 describe("runAdapterExecutionTargetShellCommand", () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -419,134 +401,3 @@ describe("resolveAdapterExecutionTargetCwd", () => {
     );
   });
 });
-
-describe("kubernetes kind: runtime helpers explicitly throw M1-not-implemented", () => {
-  const target = { kind: "kubernetes" as const, clusterConnectionId: "c-1" };
-
-  it("resolveAdapterExecutionTargetCwd throws", () => {
-    expect(() => resolveAdapterExecutionTargetCwd(target, null, "/fallback")).toThrow(/not implemented/i);
-  });
-
-  it("ensureAdapterExecutionTargetCommandResolvable throws", async () => {
-    await expect(
-      ensureAdapterExecutionTargetCommandResolvable("node", target, "/cwd", process.env),
-    ).rejects.toThrow(/not implemented/i);
-  });
-
-  it("runAdapterExecutionTargetProcess throws", async () => {
-    await expect(
-      runAdapterExecutionTargetProcess("r-1", target, "node", [], {
-        cwd: "/",
-        env: {},
-        timeoutSec: 1,
-        graceSec: 1,
-        onLog: async () => {},
-      }),
-    ).rejects.toThrow(/not implemented/i);
-  });
-
-  it("runAdapterExecutionTargetShellCommand throws", async () => {
-    await expect(
-      runAdapterExecutionTargetShellCommand("r-1", target, "echo hi", { cwd: "/", env: {} }),
-    ).rejects.toThrow(/not implemented/i);
-  });
-
-  it("readAdapterExecutionTargetHomeDir throws", async () => {
-    await expect(
-      readAdapterExecutionTargetHomeDir("r-1", target, { cwd: "/", env: {} }),
-    ).rejects.toThrow(/not implemented/i);
-  });
-
-  it("resolveAdapterExecutionTargetCommandForLogs throws", async () => {
-    await expect(
-      resolveAdapterExecutionTargetCommandForLogs("node", target, "/cwd", process.env),
-    ).rejects.toThrow(/not implemented/i);
-  });
-});
-
-describe("adapterExecutionTargetSessionMatches — kubernetes namespaceOverride", () => {
-  it("returns false when saved namespaceOverride differs from current", () => {
-    const saved = adapterExecutionTargetSessionIdentity({
-      kind: "kubernetes",
-      clusterConnectionId: "c-123",
-      namespaceOverride: "ns-a",
-    });
-    expect(
-      adapterExecutionTargetSessionMatches(saved, {
-        kind: "kubernetes",
-        clusterConnectionId: "c-123",
-        namespaceOverride: "ns-b",
-      }),
-    ).toBe(false);
-  });
-
-  it("returns true when saved namespaceOverride matches current", () => {
-    const saved = adapterExecutionTargetSessionIdentity({
-      kind: "kubernetes",
-      clusterConnectionId: "c-123",
-      namespaceOverride: "ns-a",
-    });
-    expect(
-      adapterExecutionTargetSessionMatches(saved, {
-        kind: "kubernetes",
-        clusterConnectionId: "c-123",
-        namespaceOverride: "ns-a",
-      }),
-    ).toBe(true);
-  });
-
-  it("returns true when neither saved nor current has a namespaceOverride", () => {
-    const saved = adapterExecutionTargetSessionIdentity({
-      kind: "kubernetes",
-      clusterConnectionId: "c-123",
-    });
-    expect(
-      adapterExecutionTargetSessionMatches(saved, {
-        kind: "kubernetes",
-        clusterConnectionId: "c-123",
-      }),
-    ).toBe(true);
-  });
-});
-
-describe("parseAdapterExecutionTarget — kubernetes round-trip", () => {
-  it("round-trips all five non-id fields without data loss", () => {
-    const input = {
-      kind: "kubernetes" as const,
-      clusterConnectionId: "c-456",
-      namespaceOverride: "my-ns",
-      imageOverride: "my-registry/agent:v2",
-      resources: {
-        requests: { cpu: "500m", memory: "512Mi" },
-        limits: { cpu: "1000m", memory: "1Gi" },
-      },
-      storage: { sizeGi: 10, storageClass: "fast-ssd" },
-      envOverrides: { MY_VAR: "hello", ANOTHER: "world" },
-    };
-
-    const result = parseAdapterExecutionTarget(input);
-
-    expect(result).not.toBeNull();
-    expect(result?.kind).toBe("kubernetes");
-    if (result?.kind !== "kubernetes") return;
-
-    expect(result.clusterConnectionId).toBe("c-456");
-    expect(result.namespaceOverride).toBe("my-ns");
-    expect(result.imageOverride).toBe("my-registry/agent:v2");
-    expect(result.resources).toEqual(input.resources);
-    expect(result.storage).toEqual(input.storage);
-    expect(result.envOverrides).toEqual(input.envOverrides);
-  });
-});
-
-describe("describeAdapterExecutionTarget — kubernetes namespaceOverride", () => {
-  it("includes both clusterConnectionId and namespaceOverride in description", () => {
-    const desc = describeAdapterExecutionTarget({
-      kind: "kubernetes",
-      clusterConnectionId: "c-123",
-      namespaceOverride: "my-ns",
-    });
-    expect(desc).toContain("c-123");
-    expect(desc).toContain("my-ns");
-  });
-});

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

@@ -56,29 +56,10 @@ export interface AdapterSandboxExecutionTarget {
   runner?: CommandManagedRuntimeRunner;
 }
 
-export interface AdapterKubernetesExecutionTarget {
-  kind: "kubernetes";
-  clusterConnectionId: string;
-  /** Override the auto-derived `paperclip-{companySlug}` namespace name. Rare. */
-  namespaceOverride?: string | null;
-  /** Override the resolved agent runtime image. Gated by per-cluster policy. */
-  imageOverride?: string | null;
-  resources?: {
-    requests?: { cpu?: string; memory?: string };
-    limits?:   { cpu?: string; memory?: string };
-  } | null;
-  storage?: {
-    sizeGi?: number;
-    storageClass?: string;
-  } | null;
-  envOverrides?: Record<string, string> | null;
-}
-
 export type AdapterExecutionTarget =
   | AdapterLocalExecutionTarget
   | AdapterSshExecutionTarget
-  | AdapterSandboxExecutionTarget
-  | AdapterKubernetesExecutionTarget;
+  | AdapterSandboxExecutionTarget;
 
 export type AdapterRemoteExecutionSpec = SshRemoteExecutionSpec;
 
@@ -158,7 +139,6 @@ function isBridgeDebugEnabled(env: NodeJS.ProcessEnv): boolean {
 function isAdapterExecutionTargetInstance(value: unknown): value is AdapterExecutionTarget {
   const parsed = parseObject(value);
   if (parsed.kind === "local") return true;
-  if (parsed.kind === "kubernetes") return readStringMeta(parsed, "clusterConnectionId") !== null;
   if (parsed.kind !== "remote") return false;
   if (parsed.transport === "ssh") return parseSshRemoteExecutionSpec(parseObject(parsed.spec)) !== null;
   if (parsed.transport !== "sandbox") return false;
@@ -222,11 +202,6 @@ export function resolveAdapterExecutionTargetCwd(
   configuredCwd: string | null | undefined,
   localFallbackCwd: string,
 ): string {
-  if (target?.kind === "kubernetes") {
-    throw new Error(
-      "Kubernetes execution target runtime helpers are not implemented yet (M1 covers tenant provisioning only; agent execution lands in M2).",
-    );
-  }
   if (typeof configuredCwd === "string" && configuredCwd.trim().length > 0) {
     return configuredCwd;
   }
@@ -243,9 +218,6 @@ export function describeAdapterExecutionTarget(
   target: AdapterExecutionTarget | null | undefined,
 ): string {
   if (!target || target.kind === "local") return "local environment";
-  if (target.kind === "kubernetes") {
-    return `kubernetes(connection=${target.clusterConnectionId}${target.namespaceOverride ? `, namespace=${target.namespaceOverride}` : ""})`;
-  }
   if (target.transport === "ssh") {
     return `SSH environment ${target.spec.username}@${target.spec.host}:${target.spec.port}`;
   }
@@ -313,11 +285,6 @@ export async function ensureAdapterExecutionTargetCommandResolvable(
   env: NodeJS.ProcessEnv,
   options: { installCommand?: string | null; timeoutSec?: number | null } = {},
 ) {
-  if (target?.kind === "kubernetes") {
-    throw new Error(
-      "Kubernetes execution target runtime helpers are not implemented yet (M1 covers tenant provisioning only; agent execution lands in M2).",
-    );
-  }
   if (target?.kind === "remote" && target.transport === "sandbox") {
     await ensureSandboxCommandResolvable(
       command,
@@ -419,11 +386,6 @@ export async function resolveAdapterExecutionTargetCommandForLogs(
   cwd: string,
   env: NodeJS.ProcessEnv,
 ): Promise<string> {
-  if (target?.kind === "kubernetes") {
-    throw new Error(
-      "Kubernetes execution target runtime helpers are not implemented yet (M1 covers tenant provisioning only; agent execution lands in M2).",
-    );
-  }
   if (target?.kind === "remote" && target.transport === "sandbox") {
     return `sandbox://${target.providerKey ?? "provider"}/${target.leaseId ?? "lease"}/${target.remoteCwd} :: ${command}`;
   }
@@ -439,11 +401,6 @@ export async function runAdapterExecutionTargetProcess(
   args: string[],
   options: AdapterExecutionTargetProcessOptions,
 ): Promise<RunProcessResult> {
-  if (target?.kind === "kubernetes") {
-    throw new Error(
-      "Kubernetes execution target runtime helpers are not implemented yet (M1 covers tenant provisioning only; agent execution lands in M2).",
-    );
-  }
   if (target?.kind === "remote" && target.transport === "sandbox") {
     const runner = requireSandboxRunner(target);
     const env = sanitizeRemoteExecutionEnv(options.env);
@@ -485,11 +442,6 @@ export async function runAdapterExecutionTargetShellCommand(
   command: string,
   options: AdapterExecutionTargetShellOptions,
 ): Promise<RunProcessResult> {
-  if (target?.kind === "kubernetes") {
-    throw new Error(
-      "Kubernetes execution target runtime helpers are not implemented yet (M1 covers tenant provisioning only; agent execution lands in M2).",
-    );
-  }
   const onLog = options.onLog ?? (async () => {});
   if (target?.kind === "remote") {
     const startedAt = new Date().toISOString();
@@ -861,13 +813,6 @@ export function adapterExecutionTargetSessionIdentity(
   target: AdapterExecutionTarget | null | undefined,
 ): Record<string, unknown> | null {
   if (!target || target.kind === "local") return null;
-  if (target.kind === "kubernetes") {
-    return {
-      kind: "kubernetes",
-      clusterConnectionId: target.clusterConnectionId,
-      namespaceOverride: target.namespaceOverride ?? null,
-    };
-  }
   if (target.transport === "ssh") return buildRemoteExecutionSessionIdentity(target.spec);
   return {
     transport: "sandbox",
@@ -885,15 +830,6 @@ export function adapterExecutionTargetSessionMatches(
   if (!target || target.kind === "local") {
     return Object.keys(parseObject(saved)).length === 0;
   }
-  if (target.kind === "kubernetes") {
-    const current = adapterExecutionTargetSessionIdentity(target);
-    const parsedSaved = parseObject(saved);
-    return (
-      readStringMeta(parsedSaved, "kind") === current?.kind &&
-      readStringMeta(parsedSaved, "clusterConnectionId") === current?.clusterConnectionId &&
-      readStringMeta(parsedSaved, "namespaceOverride") === (current?.namespaceOverride ?? null)
-    );
-  }
   if (target.transport === "ssh") return remoteExecutionSessionMatches(saved, target.spec);
   const current = adapterExecutionTargetSessionIdentity(target);
   const parsedSaved = parseObject(saved);
@@ -945,26 +881,6 @@ export function parseAdapterExecutionTarget(value: unknown): AdapterExecutionTar
     };
   }
 
-  if (kind === "kubernetes") {
-    const clusterConnectionId = readStringMeta(parsed, "clusterConnectionId");
-    if (!clusterConnectionId) return null;
-    return {
-      kind: "kubernetes",
-      clusterConnectionId,
-      namespaceOverride: readStringMeta(parsed, "namespaceOverride"),
-      imageOverride: readStringMeta(parsed, "imageOverride"),
-      resources: parsed.resources && typeof parsed.resources === "object"
-        ? parsed.resources as AdapterKubernetesExecutionTarget["resources"]
-        : null,
-      storage: parsed.storage && typeof parsed.storage === "object"
-        ? parsed.storage as AdapterKubernetesExecutionTarget["storage"]
-        : null,
-      envOverrides: parsed.envOverrides && typeof parsed.envOverrides === "object"
-        ? parsed.envOverrides as AdapterKubernetesExecutionTarget["envOverrides"]
-        : null,
-    };
-  }
-
   return null;
 }
 
@@ -1026,12 +942,6 @@ export async function prepareAdapterExecutionTargetRuntime(input: {
     };
   }
 
-  if (target.kind === "kubernetes") {
-    throw new Error(
-      "Kubernetes execution target runtime helpers are not implemented yet (M1 covers tenant provisioning only; agent execution lands in M2).",
-    );
-  }
-
   if (target.transport === "ssh") {
     const prepared = await prepareRemoteManagedRuntime({
       spec: target.spec,

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

@@ -1,13 +0,0 @@
-import { describe, it, expectTypeOf } from "vitest";
-import type { ServerAdapterModule } from "./types.js";
-
-describe("ServerAdapterModule.networkRequirements", () => {
-  it("accepts an allowFqdns array on a module shape", () => {
-    const m: Pick<ServerAdapterModule, "type" | "networkRequirements"> = {
-      type: "test",
-      networkRequirements: { allowFqdns: ["api.anthropic.com"] },
-    };
-    // networkRequirements is assignable
-    expectTypeOf(m.networkRequirements).toMatchTypeOf<{ allowFqdns?: string[] } | undefined>();
-  });
-});

packages/adapter-utils/src/types.ts

@@ -429,16 +429,6 @@ export interface ServerAdapterModule {
    * and provisioned in fresh remote environments such as sandboxes.
    */
   getRuntimeCommandSpec?: (config: Record<string, unknown>) => AdapterRuntimeCommandSpec | null;
-
-  /**
-   * Optional declaration of outbound network endpoints this adapter requires
-   * at runtime. Used by the kubernetes execution target to compose Cilium
-   * FQDN allowlists. Empty/omitted means "no adapter-specific FQDN allowlist
-   * contribution"; the cluster's default allowlist still applies.
-   */
-  networkRequirements?: {
-    allowFqdns?: string[];
-  };
 }
 
 // ---------------------------------------------------------------------------

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

@@ -1,4 +1,5 @@
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -58,4 +59,26 @@ describe("workspace restore merge", () => {
       readFile(path.join(targetDir, "manual-qa", "environment-matrix", "ssh", "codex_local.md"), "utf8"),
     ).resolves.toBe("ssh codex\n");
   });
+
+  it("ignores non-file entries when capturing snapshots", async () => {
+    if (process.platform === "win32") return;
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-restore-merge-"));
+    cleanupDirs.push(rootDir);
+    const socketPath = path.join(rootDir, "runtime.sock");
+    const server = net.createServer();
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socketPath, resolve);
+      });
+
+      const snapshot = await captureDirectorySnapshot(rootDir, { exclude: [] });
+
+      expect(snapshot.entries.has("runtime.sock")).toBe(false);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
 });

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

@@ -47,6 +47,10 @@ async function walkDirectory(
 
     const fullPath = path.join(root, nextRelative);
     const stats = await fs.lstat(fullPath);
+    if (!stats.isDirectory() && !stats.isSymbolicLink() && !stats.isFile()) {
+      continue;
+    }
+
     if (stats.isDirectory()) {
       out.set(nextRelative, { kind: "dir" });
       await walkDirectory(root, exclude, nextRelative, out);
@@ -87,6 +91,8 @@ async function readSnapshotEntry(root: string, relative: string): Promise<Snapsh
       target: await fs.readlink(fullPath),
     };
   }
+  if (!stats.isFile()) return null;
+
   return {
     kind: "file",
     mode: stats.mode,

packages/adapter-utils/tsconfig.json

@@ -4,6 +4,5 @@
     "outDir": "dist",
     "rootDir": "src"
   },
-  "include": ["src"],
-  "exclude": ["src/contract-kubernetes-rejection.test.ts"]
+  "include": ["src"]
 }

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

@@ -1121,17 +1121,6 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
   const warmHandles = deps.warmHandles ?? defaultWarmHandles;
 
   return async function executeAcpxLocal(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-    if (ctx.executionTarget?.kind === "kubernetes") {
-      return {
-        exitCode: null,
-        signal: null,
-        timedOut: false,
-        errorCode: "execution_target_not_yet_supported",
-        errorMessage:
-          "Kubernetes execution target is not implemented yet for this adapter. " +
-          "Tenant provisioning is available in M1; agent execution lands in M2.",
-      };
-    }
     const prepared = await buildRuntime({ ctx });
     const warmIdleMs = asNumber(ctx.config.warmHandleIdleMs, DEFAULT_ACPX_LOCAL_WARM_HANDLE_IDLE_MS);
     await cleanupIdleHandles({ handles: warmHandles, now: now(), idleMs: warmIdleMs });

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

@@ -61,7 +61,6 @@ import { isBedrockModelId } from "./models.js";
 import { prepareClaudePromptBundle } from "./prompt-cache.js";
 import { buildClaudeExecutionPermissionArgs } from "./permissions.js";
 import { SANDBOX_INSTALL_COMMAND } from "../index.js";
-import { getKubernetesExecutionDispatcher } from "./k8s-dispatcher.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
@@ -90,6 +89,15 @@ interface ClaudeRuntimeConfig {
   extraArgs: string[];
 }
 
+export function claudeSessionCwdMatchesExecutionTarget(input: {
+  runtimeSessionCwd: string;
+  effectiveExecutionCwd: string;
+  executionTargetIsRemote: boolean;
+}): boolean {
+  if (input.executionTargetIsRemote || input.runtimeSessionCwd.length === 0) return true;
+  return path.resolve(input.runtimeSessionCwd) === path.resolve(input.effectiveExecutionCwd);
+}
+
 function buildLoginResult(input: {
   proc: RunProcessResult;
   loginUrl: string | null;
@@ -357,25 +365,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     executionTarget: ctx.executionTarget,
     legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
   });
-  if (executionTarget?.kind === "kubernetes") {
-    // M2 — when the server registered a Kubernetes execution dispatcher at
-    // startup, route the run through the k8s driver. Falls back to the M1
-    // NOT_YET_SUPPORTED rejection when no dispatcher is wired (test
-    // environments, CLI-only flows that never call setKubernetesExecutionDispatcher).
-    const dispatcher = getKubernetesExecutionDispatcher();
-    if (dispatcher) {
-      return dispatcher({ ctx, target: executionTarget });
-    }
-    return {
-      exitCode: null,
-      signal: null,
-      timedOut: false,
-      errorCode: "execution_target_not_yet_supported",
-      errorMessage:
-        "Kubernetes execution target requires the server-side execution dispatcher to be registered. " +
-        "This typically means the adapter is being invoked outside the Paperclip server process.",
-    };
-  }
   const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
   const executionTargetIsSandbox = executionTarget?.kind === "remote" && executionTarget.transport === "sandbox";
 
@@ -611,7 +600,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const canResumeSession =
     runtimeSessionId.length > 0 &&
     hasMatchingPromptBundle &&
-    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
+    claudeSessionCwdMatchesExecutionTarget({
+      runtimeSessionCwd,
+      effectiveExecutionCwd,
+      executionTargetIsRemote,
+    }) &&
     adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
   const sessionId = canResumeSession ? runtimeSessionId : null;
   if (
@@ -873,7 +866,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     const resolvedSessionParams = resolvedSessionId
       ? ({
         sessionId: resolvedSessionId,
-        cwd: effectiveExecutionCwd,
+        cwd,
         promptBundleKey: promptBundle.bundleKey,
         ...(executionTargetIsRemote
           ? {

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

@@ -1,9 +1,4 @@
-export { execute, runClaudeLogin } from "./execute.js";
-export {
-  setKubernetesExecutionDispatcher,
-  getKubernetesExecutionDispatcher,
-  type KubernetesExecutionDispatcher,
-} from "./k8s-dispatcher.js";
+export { claudeSessionCwdMatchesExecutionTarget, execute, runClaudeLogin } from "./execute.js";
 export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
 export { listClaudeModels } from "./models.js";
 export { testEnvironment } from "./test.js";

packages/adapters/claude-local/src/server/k8s-dispatcher.ts

@@ -1,36 +0,0 @@
-import type {
-  AdapterExecutionContext,
-  AdapterExecutionResult,
-} from "@paperclipai/adapter-utils";
-import type { AdapterKubernetesExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
-
-/**
- * Dispatcher signature: given an AdapterExecutionContext whose
- * `executionTarget.kind === "kubernetes"` and the resolved target itself,
- * run the agent in the cluster and return an AdapterExecutionResult.
- *
- * Registered at server startup (see server/src/adapters/execution-targets/kubernetes.ts);
- * adapters call `getKubernetesExecutionDispatcher()` to look it up. When the
- * dispatcher is missing (test environments, CLI-only flows) the adapter falls
- * back to the M1 NOT_YET_SUPPORTED rejection so callers still see a structured
- * response instead of a crash.
- */
-export type KubernetesExecutionDispatcher = (input: {
-  ctx: AdapterExecutionContext;
-  target: AdapterKubernetesExecutionTarget;
-}) => Promise<AdapterExecutionResult>;
-
-let registered: KubernetesExecutionDispatcher | null = null;
-
-/**
- * Install the dispatcher. The server calls this exactly once at startup with
- * a closure that walks through the execution-target registry and invokes the
- * kubernetes driver's run() method.
- */
-export function setKubernetesExecutionDispatcher(dispatcher: KubernetesExecutionDispatcher | null): void {
-  registered = dispatcher;
-}
-
-export function getKubernetesExecutionDispatcher(): KubernetesExecutionDispatcher | null {
-  return registered;
-}

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

@@ -285,18 +285,6 @@ export async function ensureCodexSkillsInjected(
 export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
   const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
 
-  if (ctx.executionTarget?.kind === "kubernetes") {
-    return {
-      exitCode: null,
-      signal: null,
-      timedOut: false,
-      errorCode: "execution_target_not_yet_supported",
-      errorMessage:
-        "Kubernetes execution target is not implemented yet for this adapter. " +
-        "Tenant provisioning is available in M1; agent execution lands in M2.",
-    };
-  }
-
   const promptTemplate = asString(
     config.promptTemplate,
     DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,

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

@@ -199,17 +199,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     executionTarget: ctx.executionTarget,
     legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
   });
-  if (executionTarget?.kind === "kubernetes") {
-    return {
-      exitCode: null,
-      signal: null,
-      timedOut: false,
-      errorCode: "execution_target_not_yet_supported",
-      errorMessage:
-        "Kubernetes execution target is not implemented yet for this adapter. " +
-        "Tenant provisioning is available in M1; agent execution lands in M2.",
-    };
-  }
   const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
 
   const promptTemplate = asString(

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

@@ -177,17 +177,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     executionTarget: ctx.executionTarget,
     legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
   });
-  if (executionTarget?.kind === "kubernetes") {
-    return {
-      exitCode: null,
-      signal: null,
-      timedOut: false,
-      errorCode: "execution_target_not_yet_supported",
-      errorMessage:
-        "Kubernetes execution target is not implemented yet for this adapter. " +
-        "Tenant provisioning is available in M1; agent execution lands in M2.",
-    };
-  }
   const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
 
   const promptTemplate = asString(

packages/adapters/kubernetes-execution/README.md

@@ -1,5 +0,0 @@
-# @paperclipai/execution-target-kubernetes
-
-Kubernetes execution-target driver for Paperclip agents. See
-[the design spec](../../../docs/superpowers/specs/2026-05-08-paperclip-cloud-adapter-design.md)
-and [the M1 implementation plan](../../../docs/superpowers/plans/2026-05-08-paperclip-cloud-adapter-m1-plan.md).

packages/adapters/kubernetes-execution/manifests/paperclip-tenant-manager-clusterrole.yaml

@@ -1,20 +0,0 @@
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: paperclip-tenant-manager
-rules:
-  - apiGroups: [""]
-    resources: ["namespaces", "resourcequotas", "limitranges", "secrets", "serviceaccounts", "configmaps", "persistentvolumeclaims", "pods", "pods/log", "pods/exec"]
-    verbs: ["get", "list", "create", "update", "patch", "delete", "watch"]
-  - apiGroups: ["batch"]
-    resources: ["jobs"]
-    verbs: ["get", "list", "create", "update", "patch", "delete", "watch"]
-  - apiGroups: ["networking.k8s.io"]
-    resources: ["networkpolicies"]
-    verbs: ["get", "list", "create", "update", "patch", "delete"]
-  - apiGroups: ["rbac.authorization.k8s.io"]
-    resources: ["roles", "rolebindings"]
-    verbs: ["get", "list", "create", "update", "patch", "delete"]
-  - apiGroups: ["cilium.io"]
-    resources: ["ciliumnetworkpolicies"]
-    verbs: ["get", "list", "create", "update", "patch", "delete"]

packages/adapters/kubernetes-execution/package.json

@@ -1,34 +0,0 @@
-{
-  "name": "@paperclipai/execution-target-kubernetes",
-  "version": "0.0.0",
-  "license": "MIT",
-  "type": "module",
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "publishConfig": {
-    "access": "public",
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "import": "./dist/index.js"
-      }
-    }
-  },
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "test:integration": "vitest run --config vitest.integration.config.ts"
-  },
-  "dependencies": {
-    "@kubernetes/client-node": "^0.21.0",
-    "@paperclipai/adapter-utils": "workspace:*",
-    "yaml": "^2.5.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.6.0",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
-  }
-}

packages/adapters/kubernetes-execution/src/bootstrap/token.ts

@@ -1,35 +0,0 @@
-/**
- * BootstrapTokenMinter — narrow port the driver depends on for short-TTL,
- * single-use bootstrap tokens that the agent shim exchanges for a run JWT
- * via POST /api/agent-auth/exchange.
- *
- * The concrete implementation lives in `server/` (calls bootstrapTokensService);
- * this package can never import it directly because the driver intentionally
- * has no server dependency. The server-side registry wiring injects an
- * adapter that fulfils this interface.
- */
-
-export interface BootstrapTokenMintRequest {
-  agentId: string;
-  companyId: string;
-  runId: string;
-  /**
-   * The Kubernetes Job UID this token is bound to. Empty string is allowed
-   * for the V1 minter shape — the M2 driver mints tokens BEFORE the Job is
-   * created (so the Secret can carry an OwnerReference to the Job from the
-   * start), at which point the Job UID is not yet known. Job-UID enforcement
-   * at exchange time is tracked as a deferred V2 hardening (Risk #5).
-   */
-  jobUid: string;
-  /** Defaults to 600s (10 minutes) when omitted. */
-  ttlSeconds?: number;
-}
-
-export interface BootstrapTokenMintResult {
-  token: string;
-  expiresAt: Date;
-}
-
-export interface BootstrapTokenMinter {
-  mint(req: BootstrapTokenMintRequest): Promise<BootstrapTokenMintResult>;
-}

packages/adapters/kubernetes-execution/src/client.ts

@@ -1,226 +0,0 @@
-import {
-  KubeConfig,
-  CoreV1Api,
-  BatchV1Api,
-  NetworkingV1Api,
-  RbacAuthorizationV1Api,
-  ApiextensionsV1Api,
-} from "@kubernetes/client-node";
-import { Agent, request as httpsRequest, type RequestOptions as HttpsRequestOptions } from "node:https";
-import type { IncomingMessage } from "node:http";
-import { URL } from "node:url";
-import type { ResolvedClusterConnection, KubernetesApiClient } from "./types.js";
-
-export function createKubernetesApiClient(connection: ResolvedClusterConnection): KubernetesApiClient {
-  const kc = new KubeConfig();
-
-  if (connection.kind === "in-cluster") {
-    // Detect whether we're actually running inside a Kubernetes pod by checking
-    // the standard in-cluster env vars. loadFromCluster() does not throw when
-    // these are absent — it just builds a cluster with an invalid server URL.
-    if (!process.env["KUBERNETES_SERVICE_HOST"] || !process.env["KUBERNETES_SERVICE_PORT"]) {
-      throw new Error(
-        `Cluster connection ${connection.id} is in-cluster but Paperclip is not running inside a Kubernetes pod ` +
-          `(KUBERNETES_SERVICE_HOST / KUBERNETES_SERVICE_PORT are not set)`,
-      );
-    }
-    try {
-      kc.loadFromCluster();
-    } catch (err) {
-      throw new Error(
-        `Cluster connection ${connection.id} is in-cluster but Paperclip is not running inside a Kubernetes pod: ${(err as Error).message}`,
-      );
-    }
-    if (!kc.getCurrentCluster()) {
-      throw new Error(
-        `Cluster connection ${connection.id} is in-cluster but no cluster could be loaded — is Paperclip running inside a Kubernetes pod?`,
-      );
-    }
-  } else {
-    if (!connection.kubeconfigYaml) {
-      throw new Error(`Cluster connection ${connection.id} is kind=kubeconfig but kubeconfigYaml is empty`);
-    }
-    kc.loadFromString(connection.kubeconfigYaml);
-  }
-
-  const core = kc.makeApiClient(CoreV1Api);
-  const batch = kc.makeApiClient(BatchV1Api);
-  const networking = kc.makeApiClient(NetworkingV1Api);
-  const rbac = kc.makeApiClient(RbacAuthorizationV1Api);
-  const apiext = kc.makeApiClient(ApiextensionsV1Api);
-
-  const ctx = kc.getCurrentContext();
-
-  // Build an https.Agent once per client carrying the kubeconfig's TLS material
-  // (CA bundle + optional client cert/key). Required for kind/EKS-style
-  // kubeconfigs that authenticate via mTLS rather than a bearer token.
-  // @kubernetes/client-node@0.21 exposes applyHTTPSOptions which writes
-  // ca/cert/key/rejectUnauthorized onto a plain object; we hand that object to
-  // https.Agent. Lazily materialised so in-cluster paths without TLS material
-  // still work.
-  type HttpsOpts = {
-    ca?: Buffer | string;
-    cert?: Buffer | string;
-    key?: Buffer | string;
-    rejectUnauthorized?: boolean;
-  };
-  let httpsAgent: Agent | null | undefined;
-  function getHttpsAgent(): Agent | null {
-    if (httpsAgent !== undefined) return httpsAgent;
-    const kcAny = kc as unknown as { applyHTTPSOptions?: (opts: HttpsOpts) => void };
-    if (typeof kcAny.applyHTTPSOptions !== "function") {
-      httpsAgent = null;
-      return null;
-    }
-    const opts: HttpsOpts = {};
-    kcAny.applyHTTPSOptions(opts);
-    if (opts.ca || opts.cert || opts.key || opts.rejectUnauthorized === false) {
-      httpsAgent = new Agent({
-        ca: opts.ca,
-        cert: opts.cert,
-        key: opts.key,
-        rejectUnauthorized: opts.rejectUnauthorized !== false,
-      });
-    } else {
-      httpsAgent = null;
-    }
-    return httpsAgent;
-  }
-
-  // Build https.RequestOptions for an arbitrary k8s API path. Centralised so
-  // `request` and `requestStream` share the exact same auth path.
-  async function buildAuthedRequest(
-    method: string,
-    path: string,
-    body?: unknown,
-  ): Promise<{ options: HttpsRequestOptions; payload: string | undefined }> {
-    const cluster = kc.getCurrentCluster();
-    if (!cluster) throw new Error(`No current cluster in kubeconfig`);
-    const url = new URL(path, cluster.server);
-
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-      Accept: "application/json",
-    };
-    const payload = body !== undefined ? JSON.stringify(body) : undefined;
-    if (payload !== undefined) {
-      headers["Content-Length"] = Buffer.byteLength(payload).toString();
-    }
-
-    // Authorization header: for token-based and exec-credential users, the SDK
-    // exposes applyAuthorizationHeader which writes Authorization onto a plain
-    // headers object. For cert-based users it's a no-op — the auth is the mTLS
-    // handshake itself, not a header — and the https.Agent above carries the
-    // cert/key.
-    const kcAny = kc as unknown as {
-      applyAuthorizationHeader?: (opts: { headers: Record<string, string> }) => Promise<void>;
-    };
-    if (typeof kcAny.applyAuthorizationHeader === "function") {
-      await kcAny.applyAuthorizationHeader({ headers });
-    } else {
-      const user = kc.getCurrentUser();
-      if (user?.token) headers["Authorization"] = `Bearer ${user.token}`;
-    }
-
-    const agent = getHttpsAgent();
-    const options: HttpsRequestOptions = {
-      method,
-      hostname: url.hostname,
-      port: url.port || (url.protocol === "https:" ? 443 : 80),
-      path: `${url.pathname}${url.search}`,
-      headers,
-    };
-    if (agent) options.agent = agent;
-    return { options, payload };
-  }
-
-  function sendHttps(
-    options: HttpsRequestOptions,
-    payload: string | undefined,
-    timeoutMs?: number,
-    label?: string,
-  ): Promise<IncomingMessage> {
-    const reqOptions = timeoutMs !== undefined ? { ...options, timeout: timeoutMs } : options;
-    return new Promise((resolve, reject) => {
-      const req = httpsRequest(reqOptions, (res) => resolve(res));
-      req.once("error", reject);
-      if (timeoutMs !== undefined) {
-        req.once("timeout", () => {
-          req.destroy(new Error(`${label ?? "k8s API request"} timed out after ${timeoutMs}ms`));
-        });
-      }
-      if (payload !== undefined) req.write(payload);
-      req.end();
-    });
-  }
-
-  return {
-    core,
-    batch,
-    networking,
-    rbac,
-    apiext,
-    describe: () => `${connection.label} (context=${ctx})`,
-    async request<T = unknown>(method: string, path: string, body?: unknown): Promise<T> {
-      const { options, payload } = await buildAuthedRequest(method, path, body);
-      // 30s socket timeout. Without this the request could hang for tens of
-      // minutes if the API server stops responding mid-handshake (Node's
-      // default keep-alive socket has no upper bound). 30s is well above
-      // realistic API server tail latency but short enough that ensureTenant
-      // surfaces an actionable error rather than appearing to stall.
-      const REQUEST_TIMEOUT_MS = 30_000;
-      const res = await sendHttps(options, payload, REQUEST_TIMEOUT_MS, `k8s API ${method} ${path}`);
-      const status = res.statusCode ?? 0;
-      const chunks: Buffer[] = [];
-      for await (const chunk of res) {
-        chunks.push(chunk as Buffer);
-      }
-      const text = Buffer.concat(chunks).toString("utf-8");
-      if (status < 200 || status >= 300) {
-        throw new Error(`k8s API ${method} ${path} failed ${status}: ${text}`);
-      }
-      if (status === 204 || text.length === 0) return undefined as T;
-      return JSON.parse(text) as T;
-    },
-    async requestStream(method: string, path: string, body?: unknown): Promise<Response> {
-      const { options, payload } = await buildAuthedRequest(method, path, body);
-      // No socket timeout: pod-log streams and event watches are intentionally
-      // long-lived. The caller drives reconnect / cancellation via the
-      // returned Response.body.getReader().
-      const incoming = await sendHttps(options, payload);
-      // Adapt the Node IncomingMessage into a Web Response so log-stream and
-      // event-watch consumers (which call response.body.getReader()) work
-      // uniformly.
-      const stream = new ReadableStream<Uint8Array>({
-        start(controller) {
-          incoming.on("data", (chunk: Buffer) => {
-            try {
-              controller.enqueue(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
-            } catch {
-              /* controller already closed */
-            }
-          });
-          incoming.on("end", () => {
-            try { controller.close(); } catch { /* already closed */ }
-          });
-          incoming.on("error", (err) => {
-            try { controller.error(err); } catch { /* already errored */ }
-          });
-        },
-        cancel() {
-          incoming.destroy();
-        },
-      });
-      const headers = new Headers();
-      for (const [k, v] of Object.entries(incoming.headers)) {
-        if (Array.isArray(v)) for (const item of v) headers.append(k, item);
-        else if (v !== undefined) headers.set(k, v);
-      }
-      return new Response(stream, {
-        status: incoming.statusCode ?? 0,
-        statusText: incoming.statusMessage ?? "",
-        headers,
-      });
-    },
-  };
-}

packages/adapters/kubernetes-execution/src/driver.ts

@@ -1,654 +0,0 @@
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
-import type { AdapterKubernetesExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
-import type { V1Job, V1Pod } from "@kubernetes/client-node";
-import { ensureTenantNamespace, type EnsureTenantInput } from "./orchestrator/ensure-tenant.js";
-import { createKubernetesApiClient } from "./client.js";
-import { deriveNamespaceName } from "./orchestrator/naming.js";
-import { getAdapterDefaults } from "./orchestrator/adapter-defaults.js";
-import { buildAgentWorkspacePvc, applyAgentWorkspacePvc } from "./orchestrator/pvc.js";
-import {
-  buildEphemeralSecret, applyEphemeralSecret, deleteEphemeralSecret,
-  patchEphemeralSecretOwnerReference,
-} from "./orchestrator/secret.js";
-import { buildAgentJob, createAgentJob } from "./orchestrator/job.js";
-import { startLogStream } from "./orchestrator/log-stream.js";
-import { startEventWatch } from "./orchestrator/event-watch.js";
-import { cancelJob } from "./orchestrator/cancellation.js";
-import { mapTerminalState } from "./orchestrator/failure-mapping.js";
-import { newRunUlidDns } from "./orchestrator/run-id.js";
-import { PAPERCLIP_RUN_ID } from "./orchestrator/labels.js";
-import { createRedactor, noopRedactor, type Redactor } from "./redaction.js";
-import type { BootstrapTokenMinter } from "./bootstrap/token.js";
-import type { KubernetesApiClient, ResolvedClusterConnection } from "./types.js";
-
-export interface KubernetesDriverDeps {
-  resolveConnection: (id: string) => Promise<ResolvedClusterConnection | null>;
-  /**
-   * Mints a single-use bootstrap token bound to (agentId, companyId, runId).
-   * The driver injects the resulting token value into the per-Job Secret so
-   * the agent shim can exchange it for a run-scoped JWT inside the pod.
-   *
-   * In M1 this is allowed to be omitted; run() will return an
-   * `execution_target_not_yet_supported` error in that case so server tests
-   * keep working without DB plumbing.
-   */
-  bootstrapTokenMinter?: BootstrapTokenMinter;
-  /**
-   * Resolves the runtime context the driver needs to call ensureTenant
-   * (companySlug, controlPlane topology, adapterAllowFqdns, image
-   * pull secret JSON, optional tenantPolicy). Server-side wiring fills this
-   * in; M1 callers that only test ensureTenant can pass through
-   * `ensureTenant()` directly with the older `clusterConnectionId` shape.
-   *
-   * Optional in M1 — when omitted, `run()` falls back to a stub error.
-   */
-  resolveRunContext?: (input: ResolveRunContextInput) => Promise<ResolvedRunContext | null>;
-  /** Wall-clock for tests. Defaults to Date.now / new Date(). */
-  now?: () => Date;
-  /**
-   * Override the polling interval in ms. Defaults to 1000ms. Tests inject
-   * smaller values to keep run-loop tests fast.
-   */
-  pollIntervalMs?: number;
-}
-
-export interface ResolveRunContextInput {
-  agent: AdapterExecutionContext["agent"];
-  target: AdapterKubernetesExecutionTarget;
-  connection: ResolvedClusterConnection;
-  /**
-   * The runtime-resolved adapter config for this run (`ctx.config`). The
-   * server has already passed the persisted `agents.adapter_config` through
-   * `secretService.resolveAdapterConfigForRuntime`, so `config.env` (when
-   * present) is a flat `Record<string, string>` of provider env vars. The
-   * server uses this to populate `ResolvedRunContext.adapterEnv`; the driver
-   * then narrows that map to `getAdapterDefaults(adapterType).envKeys` before
-   * writing the per-Job Secret.
-   */
-  config: AdapterExecutionContext["config"];
-}
-
-export interface ResolvedRunContext {
-  /** Sanitized company slug for namespace + label derivation. */
-  companySlug: string;
-  /** Resolved namespace; defaults to deriveNamespaceName(...) when omitted. */
-  namespaceOverride?: string | null;
-  /** Image to run for the main agent container. */
-  image: string;
-  /** Init container image (always agent-runtime-base). */
-  initImage: string;
-  /** Optional list of imagePullSecret names to attach to the pod. */
-  imagePullSecrets?: string[];
-  /** Hard ceiling for the run; defaults to 1800s. */
-  activeDeadlineSeconds?: number;
-  /** Job TTL after completion; defaults to 300s. */
-  ttlSecondsAfterFinished?: number;
-  /** Workspace strategy serialized as JSON for the init container. */
-  workspaceStrategyJson: string;
-  /** Trace context propagated into the pod. */
-  traceparent?: string;
-  /** Public URL of the Paperclip control plane (where the shim exchanges its bootstrap token). */
-  paperclipPublicUrl: string;
-  /** Adapter-supplied env that the shim should expose via the env Secret. */
-  adapterEnv?: Record<string, string>;
-  /** PVC sizeGi override; defaults to 10. */
-  storageSizeGi?: number;
-  /** Storage class override; defaults to connection.capabilities.storageClass. */
-  storageClassName?: string;
-  /** Strategy key tag for the PVC annotation. Free-form. */
-  workspaceStrategyKey: string;
-}
-
-export type EnsureTenantDriverInput = Omit<EnsureTenantInput, "connection"> & {
-  clusterConnectionId: string;
-  /**
-   * Optional adapter type. When provided, the driver merges
-   * `getAdapterDefaults(adapterType).allowFqdns` into the forwarded
-   * `adapterAllowFqdns`. Omit for backwards-compat callers that prefer
-   * to compute the merged list upstream themselves.
-   */
-  adapterType?: string;
-};
-
-export interface KubernetesExecutionDriver {
-  type: "kubernetes";
-  validateTarget(target: unknown): Promise<void>;
-  ensureTenant(input: EnsureTenantDriverInput): Promise<{ namespace: string; ciliumApplied: boolean }>;
-  run(input: {
-    ctx: AdapterExecutionContext;
-    target: AdapterKubernetesExecutionTarget;
-  }): Promise<AdapterExecutionResult>;
-}
-
-const DEFAULT_POLL_INTERVAL_MS = 1000;
-const DEFAULT_ACTIVE_DEADLINE_SECONDS = 1800;
-const DEFAULT_TTL_SECONDS_AFTER_FINISHED = 300;
-const DEFAULT_BOOTSTRAP_TTL_SECONDS = 600;
-
-function serializeRuntimeCommandSpec(spec: AdapterExecutionContext["runtimeCommandSpec"]): string | null {
-  if (!spec?.command) return null;
-  const maybeArgs = (spec as { args?: unknown }).args;
-  const args = Array.isArray(maybeArgs) ? maybeArgs.filter((arg): arg is string => typeof arg === "string") : [];
-  return JSON.stringify({
-    command: spec.command,
-    args,
-    ...(spec.detectCommand ? { detectCommand: spec.detectCommand } : {}),
-    ...(spec.installCommand ? { installCommand: spec.installCommand } : {}),
-  });
-}
-
-/**
- * Derive a DNS-1123-friendly agent slug from the agent UUID. Used in PVC,
- * Job, and Secret names. We pick the first 8 chars of the UUID's leading
- * hex segment, lowercased, to keep names short while still readable across
- * a tenant's k8s namespace.
- */
-function deriveAgentSlug(agentId: string): string {
-  const cleaned = agentId.toLowerCase().replace(/[^a-z0-9]/g, "");
-  return cleaned.slice(0, 8) || "agent";
-}
-
-function isJobTerminal(job: V1Job): { done: true; succeeded: boolean } | { done: false } {
-  if ((job.status?.succeeded ?? 0) >= 1) return { done: true, succeeded: true };
-  if ((job.status?.failed ?? 0) >= 1) return { done: true, succeeded: false };
-  for (const cond of job.status?.conditions ?? []) {
-    if (cond.status === "True" && (cond.type === "Complete" || cond.type === "Failed")) {
-      return { done: true, succeeded: cond.type === "Complete" };
-    }
-  }
-  return { done: false };
-}
-
-async function readPodForRun(
-  client: KubernetesApiClient,
-  namespace: string,
-  runId: string,
-): Promise<V1Pod | undefined> {
-  const labelSelector = `${PAPERCLIP_RUN_ID}=${runId}`;
-  const list = await client.core.listNamespacedPod(
-    namespace,
-    undefined, undefined, undefined, undefined,
-    labelSelector,
-  );
-  return list.body.items[0];
-}
-
-async function waitMs(ms: number, abort?: AbortSignal): Promise<void> {
-  await new Promise<void>((resolve) => {
-    const timer = setTimeout(() => {
-      abort?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(timer);
-      resolve();
-    };
-    abort?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-async function safeStop<T extends { abort: () => void; done: Promise<void> } | null | undefined>(handle: T): Promise<void> {
-  if (!handle) return;
-  handle.abort();
-  try {
-    await handle.done;
-  } catch {
-    /* swallow — abort is best-effort */
-  }
-}
-
-interface RunCancellation {
-  signal: AbortSignal;
-  dispose(): void;
-}
-
-function buildRunCancellation(ctx: AdapterExecutionContext): RunCancellation {
-  // AdapterExecutionContext does not (yet) expose an AbortSignal, but the
-  // surrounding heartbeat dispatch may register a `paperclipCancel` callback
-  // on `ctx.context`. Until that lands we expose an AbortController so callers
-  // can wire it up; the production path will populate this from heartbeat
-  // cancellation hooks once the contract is updated.
-  const ctlr = new AbortController();
-  const ctxAny = ctx.context as Record<string, unknown> | undefined;
-  const externalSignal = (ctxAny?.paperclipCancellationSignal as AbortSignal | undefined) ?? null;
-  if (externalSignal) {
-    if (externalSignal.aborted) {
-      ctlr.abort();
-    } else {
-      const onAbort = () => ctlr.abort();
-      externalSignal.addEventListener("abort", onAbort, { once: true });
-      return {
-        signal: ctlr.signal,
-        dispose: () => externalSignal.removeEventListener("abort", onAbort),
-      };
-    }
-  }
-  return {
-    signal: ctlr.signal,
-    dispose: () => { /* noop */ },
-  };
-}
-
-export function createKubernetesExecutionDriver(deps: KubernetesDriverDeps): KubernetesExecutionDriver {
-  const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-
-  return {
-    type: "kubernetes",
-
-    async validateTarget(target) {
-      const t = target as { kind?: string; clusterConnectionId?: string };
-      if (t.kind !== "kubernetes") {
-        throw new Error(
-          `KubernetesExecutionDriver received target with kind=${t.kind ?? "(none)"}, expected "kubernetes"`,
-        );
-      }
-      if (!t.clusterConnectionId) {
-        throw new Error(`KubernetesExecutionDriver target is missing clusterConnectionId`);
-      }
-      const connection = await deps.resolveConnection(t.clusterConnectionId);
-      if (!connection) {
-        throw new Error(`Cluster connection ${t.clusterConnectionId} not found`);
-      }
-    },
-
-    async ensureTenant({ clusterConnectionId, adapterType, ...rest }) {
-      const connection = await deps.resolveConnection(clusterConnectionId);
-      if (!connection) {
-        throw new Error(`Cluster connection ${clusterConnectionId} not found`);
-      }
-      const client = createKubernetesApiClient(connection);
-      // When adapterType is supplied, merge the adapter-defaults FQDN list
-      // into adapterAllowFqdns so the tenant's egress policy permits the
-      // adapter's required upstreams in addition to any caller-supplied
-      // FQDNs. Caller-supplied entries are preserved (set-deduped). When
-      // adapterType is omitted, we forward unchanged for backwards compat.
-      const adapterAllowFqdns = adapterType
-        ? Array.from(new Set([
-            ...(rest.adapterAllowFqdns ?? []),
-            ...getAdapterDefaults(adapterType).allowFqdns,
-          ]))
-        : rest.adapterAllowFqdns;
-      return ensureTenantNamespace(client, { connection, ...rest, adapterAllowFqdns });
-    },
-
-    async run(input) {
-      const { ctx, target } = input;
-
-      // ---- M1 fallback paths ---------------------------------------------------
-      // run() can only complete when both the bootstrap token minter and the
-      // run-context resolver are wired (server boots both at startup). In any
-      // other configuration we keep the M1 NOT_YET_SUPPORTED contract so that
-      // callers without DB/server plumbing get a structured rejection instead
-      // of a crash.
-      if (!deps.bootstrapTokenMinter || !deps.resolveRunContext) {
-        return {
-          exitCode: null,
-          signal: null,
-          timedOut: false,
-          errorCode: "execution_target_not_yet_supported",
-          errorMessage:
-            "Kubernetes agent execution requires the server-side bootstrap token minter " +
-            "and run-context resolver to be wired into the driver registry.",
-        };
-      }
-
-      const connection = await deps.resolveConnection(target.clusterConnectionId);
-      if (!connection) {
-        return {
-          exitCode: null,
-          signal: null,
-          timedOut: false,
-          errorCode: "execution_target_not_yet_supported",
-          errorMessage: `Cluster connection ${target.clusterConnectionId} not found`,
-        };
-      }
-      const client = createKubernetesApiClient(connection);
-
-      const runContext = await deps.resolveRunContext({
-        agent: ctx.agent,
-        target,
-        connection,
-        config: ctx.config,
-      });
-      if (!runContext) {
-        return {
-          exitCode: null,
-          signal: null,
-          timedOut: false,
-          errorCode: "execution_target_not_yet_supported",
-          errorMessage: "Driver run-context resolver returned no context for this run",
-        };
-      }
-
-      const namespace = (target.namespaceOverride ?? runContext.namespaceOverride ?? null)?.trim()
-        || deriveNamespaceName({
-          companySlug: runContext.companySlug,
-          companyId: ctx.agent.companyId,
-          prefix: connection.defaultNamespacePrefix,
-        });
-
-      const agentSlug = deriveAgentSlug(ctx.agent.id);
-      const runUlid = newRunUlidDns(deps.now ? () => deps.now!().getTime() : undefined);
-      const runId = ctx.runId;
-
-      const cancellation = buildRunCancellation(ctx);
-      const { signal: cancelSignal } = cancellation;
-
-      // Image policy enforcement.
-      //
-      // 1. allowAgentImageOverride (M2): when the connection forbids it,
-      //    a target.imageOverride is rejected outright — operators use this
-      //    to pin agents to the cluster-supplied default image.
-      // 2. imageAllowlist (M3b): when non-empty, runContext.image must
-      //    match an allowed repository prefix. runContext.image already
-      //    equals target.imageOverride ?? adapterImage (set by resolveRunContext),
-      //    so a single check covers both default and override cases.
-      if (target.imageOverride != null && !connection.allowAgentImageOverride) {
-        cancellation.dispose();
-        return {
-          exitCode: null, signal: null, timedOut: false,
-          errorCode: "image_override_not_allowed",
-          errorMessage: `Cluster connection does not permit agent image overrides`,
-        };
-      }
-      const allowlist = connection.imageAllowlist ?? [];
-      if (allowlist.length > 0) {
-        const matchesAllowlist = (img: string): boolean =>
-          allowlist.some((prefix) => {
-            const pathPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
-            return img === prefix || img.startsWith(pathPrefix);
-          });
-        if (!matchesAllowlist(runContext.image)) {
-          cancellation.dispose();
-          return {
-            exitCode: null, signal: null, timedOut: false,
-            errorCode: "image_not_allowed",
-            errorMessage: `Adapter image "${runContext.image}" not in cluster image_allowlist`,
-          };
-        }
-      }
-
-      const runtimeCommandSpecJson = serializeRuntimeCommandSpec(ctx.runtimeCommandSpec);
-      if (!runtimeCommandSpecJson) {
-        cancellation.dispose();
-        return {
-          exitCode: null,
-          signal: null,
-          timedOut: false,
-          errorCode: "execution_target_not_yet_supported",
-          errorMessage: `Adapter ${ctx.agent.adapterType ?? "unknown"} did not provide a runtime command spec for kubernetes execution`,
-        };
-      }
-
-      // 1. PVC (idempotent — reused across runs for the same agent).
-      const pvc = buildAgentWorkspacePvc({
-        namespace,
-        agentId: ctx.agent.id,
-        agentSlug,
-        companyId: ctx.agent.companyId,
-        companySlug: runContext.companySlug,
-        storageClass: runContext.storageClassName ?? connection.capabilities.storageClass,
-        sizeGi: runContext.storageSizeGi,
-        strategyKey: runContext.workspaceStrategyKey,
-      });
-      await applyAgentWorkspacePvc(client, pvc);
-
-      // 2. Mint bootstrap token (V1: jobUid="" — see Risk #5 deferred to V2).
-      const minted = await deps.bootstrapTokenMinter.mint({
-        agentId: ctx.agent.id,
-        companyId: ctx.agent.companyId,
-        runId,
-        jobUid: "",
-        ttlSeconds: DEFAULT_BOOTSTRAP_TTL_SECONDS,
-      });
-
-      // 3. Materialize per-Job ephemeral Secret. We create it WITHOUT an
-      //    OwnerReference first because the Job UID isn't known yet, then
-      //    PATCH it after the Job is created (two-phase commit). This avoids
-      //    a race where the pod starts before the Secret exists.
-      const secretName = `agent-${agentSlug}-run-${runUlid}-env`;
-      const adapterType = ctx.agent.adapterType ?? "unknown";
-      // The adapter-defaults registry is the single source of truth for which
-      // provider creds may reach the agent container. We filter the Server-
-      // resolved adapterEnv map down to defaults.envKeys so a server-side
-      // misconfiguration that surfaces extra keys (e.g. a leaked Anthropic
-      // key on a Gemini run) cannot land in the per-Job Secret. Unknown
-      // adapter types resolve to envKeys=[] which intentionally drops ALL
-      // adapter-supplied env (BOOTSTRAP_TOKEN is added unconditionally below).
-      const defaults = getAdapterDefaults(adapterType);
-      const adapterEnv = runContext.adapterEnv ?? {};
-      const filteredAdapterEnv: Record<string, string> = {};
-      for (const k of defaults.envKeys) {
-        const v = adapterEnv[k];
-        if (typeof v === "string") filteredAdapterEnv[k] = v;
-      }
-      const secretData: Record<string, string> = {
-        ...filteredAdapterEnv,
-        BOOTSTRAP_TOKEN: minted.token,
-        "runtime-command.json": runtimeCommandSpecJson,
-      };
-
-      const redactor: Redactor =
-        Object.values(secretData).length > 0
-          ? createRedactor(Object.values(secretData))
-          : noopRedactor;
-
-      // Build a placeholder Secret with no owner reference for the initial
-      // create; we'll patch the OwnerReference after the Job is created.
-      const placeholderSecret = buildEphemeralSecret({
-        namespace,
-        agentSlug,
-        runUlid,
-        companyId: ctx.agent.companyId,
-        companySlug: runContext.companySlug,
-        runId,
-        data: secretData,
-        ownerJob: { name: `agent-${agentSlug}-run-${runUlid}`, uid: "00000000-0000-0000-0000-000000000000" },
-      });
-      // Strip placeholder ownerReferences — they can't reference a Job that doesn't exist yet.
-      placeholderSecret.metadata!.ownerReferences = undefined;
-
-      try {
-        await applyEphemeralSecret(client, placeholderSecret);
-      } catch (err) {
-        cancellation.dispose();
-        return {
-          exitCode: null,
-          signal: null,
-          timedOut: false,
-          errorCode: "agent_exit_nonzero",
-          errorMessage: `Failed to create per-Job Secret: ${(err as Error).message}`,
-        };
-      }
-
-      let jobName = `agent-${agentSlug}-run-${runUlid}`;
-      let jobUid = "";
-      // Tracks whether the Secret has an OwnerReference back to the Job. When
-      // false at the end of the run, the finally block below explicitly
-      // deletes the Secret because Kubernetes GC won't touch it.
-      let ownerRefPatched = false;
-
-      try {
-        // 4. Create the Job referencing the Secret.
-        const job = buildAgentJob({
-          namespace,
-          agentId: ctx.agent.id,
-          agentSlug,
-          runId,
-          runUlid,
-          companyId: ctx.agent.companyId,
-          companySlug: runContext.companySlug,
-          adapterType,
-          image: target.imageOverride ?? runContext.image,
-          initImage: runContext.initImage,
-          imagePullSecrets: runContext.imagePullSecrets,
-          pvcName: pvc.metadata!.name!,
-          envSecretName: secretName,
-          resources: target.resources ?? undefined,
-          activeDeadlineSeconds: runContext.activeDeadlineSeconds ?? DEFAULT_ACTIVE_DEADLINE_SECONDS,
-          ttlSecondsAfterFinished: runContext.ttlSecondsAfterFinished ?? DEFAULT_TTL_SECONDS_AFTER_FINISHED,
-          workspaceStrategyJson: runContext.workspaceStrategyJson,
-          runtimeCommandSpecJson,
-          paperclipPublicUrl: runContext.paperclipPublicUrl,
-          traceparent: runContext.traceparent,
-        });
-
-        const created = await createAgentJob(client, job);
-        jobName = created.name;
-        jobUid = created.uid;
-
-        // 5. Patch the Secret with the now-known Job UID so it gets GC'd
-        //    automatically when the Job is deleted. Without the OwnerReference,
-        //    TTLSecondsAfterFinished only deletes the Job — the Secret would
-        //    persist indefinitely on long-lived clusters, accumulating spent
-        //    bootstrap tokens. Retry transient failures with exponential
-        //    backoff before falling back to a deferred delete in the finally
-        //    block below.
-        for (let attempt = 0; attempt < 3; attempt++) {
-          try {
-            await patchEphemeralSecretOwnerReference(client, namespace, secretName, {
-              name: jobName,
-              uid: jobUid,
-            });
-            ownerRefPatched = true;
-            break;
-          } catch (patchErr) {
-            if (attempt === 2) {
-              // Final attempt failed — log structured error so operators see
-              // the leak path even if the cleanup below fails too.
-              // eslint-disable-next-line no-console
-              console.error("[k8s-execution] OwnerRef patch failed after 3 attempts; will delete Secret on cleanup", {
-                namespace, secretName, jobName, jobUid,
-                error: (patchErr as Error).message,
-              });
-            } else {
-              await waitMs(50 * Math.pow(2, attempt));
-            }
-          }
-        }
-      } catch (err) {
-        // Job creation failed AFTER Secret creation — clean up the orphan.
-        try { await deleteEphemeralSecret(client, namespace, secretName); } catch { /* swallow */ }
-        cancellation.dispose();
-        return {
-          exitCode: null,
-          signal: null,
-          timedOut: false,
-          errorCode: "agent_exit_nonzero",
-          errorMessage: `Failed to create Job: ${(err as Error).message}`,
-        };
-      }
-
-      // 6. Start log + event streams. Both attach to the Pod that the Job
-      //    spawns; pod name resolution happens lazily inside the loop below
-      //    once the pod has been scheduled.
-      const adapterOnLog = ctx.onLog;
-      const onLog = async (stream: "stdout" | "stderr", chunk: string) => {
-        await adapterOnLog(stream, redactor.redact(chunk));
-      };
-
-      const eventWatch = startEventWatch({ client, namespace, jobName, onLog });
-
-      // Resolve the Pod that the Job created. The Job pod has the same run-id
-      // label so we can locate it via labelSelector.
-      let podName: string | null = null;
-      const POD_RESOLUTION_DEADLINE_MS = 30_000;
-      const podDeadline = Date.now() + POD_RESOLUTION_DEADLINE_MS;
-      while (!cancelSignal.aborted && Date.now() < podDeadline) {
-        const pod = await readPodForRun(client, namespace, runId).catch(() => undefined);
-        if (pod?.metadata?.name) {
-          podName = pod.metadata.name;
-          break;
-        }
-        await waitMs(500, cancelSignal);
-      }
-
-      const logStream = podName
-        ? startLogStream({ client, namespace, podName, containerName: "agent", onLog })
-        : null;
-
-      // 7. Poll Job status until terminal or cancelled.
-      let cancelled = false;
-      let terminalJob: V1Job | null = null;
-      try {
-        while (!cancelSignal.aborted) {
-          const jobRead = await client.batch
-            .readNamespacedJob(jobName, namespace)
-            .catch(() => null);
-          const job = jobRead?.body ?? null;
-          if (job) {
-            const t = isJobTerminal(job);
-            if (t.done) {
-              terminalJob = job;
-              break;
-            }
-          }
-          await waitMs(pollIntervalMs, cancelSignal);
-        }
-
-        if (cancelSignal.aborted && !terminalJob) {
-          cancelled = true;
-          await cancelJob({ client, namespace, jobName }).catch(() => { /* swallow */ });
-          // Re-poll briefly so we can read the final pod state for the Adapter result.
-          const cancelDeadline = Date.now() + 35_000;
-          while (Date.now() < cancelDeadline) {
-            const jobRead = await client.batch.readNamespacedJob(jobName, namespace).catch(() => null);
-            const job = jobRead?.body ?? null;
-            if (job) {
-              const t = isJobTerminal(job);
-              if (t.done) {
-                terminalJob = job;
-                break;
-              }
-            }
-            await waitMs(pollIntervalMs);
-          }
-        }
-      } finally {
-        await safeStop(logStream);
-        await safeStop(eventWatch);
-        cancellation.dispose();
-        // If the OwnerReference patch never succeeded, the Secret has no
-        // back-pointer to the Job and Kubernetes GC will never delete it
-        // (TTLSecondsAfterFinished only governs the Job itself). Delete it
-        // explicitly here. The bootstrap token has already been consumed at
-        // this point so deleting the Secret is safe even mid-run.
-        if (!ownerRefPatched) {
-          try { await deleteEphemeralSecret(client, namespace, secretName); }
-          catch { /* best-effort cleanup; log volume already covered above */ }
-        }
-      }
-
-      if (cancelled && !terminalJob) {
-        // Cancellation requested but we couldn't observe a terminal Job state
-        // within the grace window. Surface a structured cancellation result.
-        return {
-          exitCode: null,
-          signal: "SIGTERM",
-          timedOut: false,
-          errorCode: "agent_exit_nonzero",
-          errorMessage: "Run cancelled before Job reached terminal state",
-        };
-      }
-
-      // 8. Map the terminal state to an AdapterExecutionResult.
-      const finalPod = await readPodForRun(client, namespace, runId).catch(() => undefined);
-      const result = mapTerminalState({ job: terminalJob ?? ({} as V1Job), pod: finalPod });
-      if (cancelled) {
-        // Even if mapTerminalState saw a normal terminal, the user-visible
-        // outcome is "cancelled". Preserve any failure-code mapping that's
-        // strictly more informative (e.g. image_pull_failed) but otherwise
-        // signal SIGTERM.
-        if (!result.errorCode) {
-          return {
-            ...result,
-            signal: "SIGTERM",
-            errorCode: "agent_exit_nonzero",
-            errorMessage: result.errorMessage ?? "Run cancelled",
-          };
-        }
-      }
-      return result;
-    },
-  };
-}

packages/adapters/kubernetes-execution/src/index.ts

@@ -1,40 +0,0 @@
-export const PACKAGE_NAME = "@paperclipai/execution-target-kubernetes";
-
-export { createKubernetesExecutionDriver } from "./driver.js";
-export type {
-  KubernetesExecutionDriver,
-  KubernetesDriverDeps,
-  EnsureTenantDriverInput,
-  ResolveRunContextInput,
-  ResolvedRunContext,
-} from "./driver.js";
-
-export type {
-  BootstrapTokenMinter,
-  BootstrapTokenMintRequest,
-  BootstrapTokenMintResult,
-} from "./bootstrap/token.js";
-
-export {
-  ensureTenantNamespace,
-  type EnsureTenantInput,
-  type EnsureTenantResult,
-  type TenantPolicy,
-} from "./orchestrator/ensure-tenant.js";
-
-export { buildTenantCiliumPolicy } from "./orchestrator/cilium-tenant-policy.js";
-export { createKubernetesApiClient } from "./client.js";
-export { probeClusterCapabilities } from "./orchestrator/capabilities.js";
-export { deriveNamespaceName, isValidDns1123Label } from "./orchestrator/naming.js";
-
-export type {
-  ResolvedClusterConnection,
-  ClusterCapabilities,
-  KubernetesApiClient,
-} from "./types.js";
-
-export {
-  ADAPTER_DEFAULTS,
-  getAdapterDefaults,
-  type AdapterDefaults,
-} from "./orchestrator/adapter-defaults.js";

packages/adapters/kubernetes-execution/src/orchestrator/adapter-defaults.test.ts

@@ -1,105 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  ADAPTER_DEFAULTS,
-  getAdapterDefaults,
-  type AdapterDefaults,
-} from "./adapter-defaults.js";
-
-describe("adapter defaults registry", () => {
-  it("claude_local has known shape", () => {
-    const d = getAdapterDefaults("claude_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-claude/);
-    expect(d.envKeys).toContain("ANTHROPIC_API_KEY");
-    expect(d.allowFqdns).toContain("api.anthropic.com");
-  });
-
-  it("returns defaults for an unknown adapter", () => {
-    const d = getAdapterDefaults("totally-made-up");
-    // Unknown adapter falls back to base image + zero env keys + zero FQDNs.
-    // The driver still functions (will fail to invoke the unknown CLI inside
-    // the container) but provisioning succeeds.
-    expect(d.runtimeImage).toMatch(/agent-runtime-base/);
-    expect(d.envKeys).toEqual([]);
-    expect(d.allowFqdns).toEqual([]);
-  });
-
-  it("every registered adapter has a non-empty runtimeImage", () => {
-    for (const [type, defaults] of Object.entries(ADAPTER_DEFAULTS)) {
-      expect(defaults.runtimeImage, `adapter=${type}`).toBeTruthy();
-    }
-  });
-
-  it("type guard: AdapterDefaults requires the three fields", () => {
-    const sample: AdapterDefaults = { runtimeImage: "x", envKeys: [], allowFqdns: [] };
-    expect(sample.runtimeImage).toBe("x");
-  });
-
-  it("codex_local has expected env + fqdn defaults", () => {
-    const d = getAdapterDefaults("codex_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-codex/);
-    expect(d.envKeys).toContain("OPENAI_API_KEY");
-    expect(d.allowFqdns).toContain("api.openai.com");
-  });
-
-  it("gemini_local has expected env + fqdn defaults", () => {
-    const d = getAdapterDefaults("gemini_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-gemini/);
-    expect(d.envKeys).toEqual(expect.arrayContaining(["GEMINI_API_KEY", "GOOGLE_API_KEY"]));
-    expect(d.allowFqdns).toContain("generativelanguage.googleapis.com");
-  });
-
-  it("acpx_local has expected env + fqdn defaults", () => {
-    const d = getAdapterDefaults("acpx_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-acpx/);
-    expect(d.envKeys).toEqual(expect.arrayContaining(["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]));
-    expect(d.allowFqdns).toEqual(expect.arrayContaining(["api.anthropic.com", "api.openai.com"]));
-  });
-
-  it("opencode_local lists every provider it supports + their FQDNs", () => {
-    // opencode supports Anthropic, OpenAI, Gemini, and xAI. driver.run()
-    // filters adapterEnv strictly to defaults.envKeys before writing the
-    // per-Job Secret, so a missing key is silently dropped and the pod
-    // starts without credentials. Likewise allowFqdns gates the tenant
-    // NetworkPolicy. Asserting all four here prevents a regression that
-    // would only surface as an auth failure on a live cluster.
-    const d = getAdapterDefaults("opencode_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-opencode/);
-    expect(d.envKeys).toEqual(
-      expect.arrayContaining([
-        "ANTHROPIC_API_KEY",
-        "OPENAI_API_KEY",
-        "GEMINI_API_KEY",
-        "XAI_API_KEY",
-      ]),
-    );
-    expect(d.allowFqdns).toEqual(
-      expect.arrayContaining([
-        "api.anthropic.com",
-        "api.openai.com",
-        "generativelanguage.googleapis.com",
-        "api.x.ai",
-      ]),
-    );
-  });
-
-  it("pi_local has expected env + fqdn defaults", () => {
-    const d = getAdapterDefaults("pi_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-pi/);
-    expect(d.envKeys).toEqual(
-      expect.arrayContaining(["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "XAI_API_KEY"]),
-    );
-    expect(d.allowFqdns).toEqual(
-      expect.arrayContaining(["api.anthropic.com", "api.openai.com", "api.x.ai"]),
-    );
-  });
-
-  it("hermes_local registry entry exists with a runtime image (binary install is a follow-up)", () => {
-    const d = getAdapterDefaults("hermes_local");
-    expect(d.runtimeImage).toMatch(/agent-runtime-hermes/);
-    // Empty envKeys / allowFqdns until upstream binary lands; operators set
-    // their own via cluster_tenant_policies.networkJson.additionalAllowFqdns
-    // and the per-Job env Secret.
-    expect(d.envKeys).toEqual([]);
-    expect(d.allowFqdns).toEqual([]);
-  });
-});

packages/adapters/kubernetes-execution/src/orchestrator/adapter-defaults.ts

@@ -1,93 +0,0 @@
-/**
- * Per-adapter cloud-runtime defaults.
- *
- * Each entry tells the driver:
- *   - runtimeImage:  Which `agent-runtime-<adapter>` image to run (default
- *                    fallback is `agent-runtime-base`, which has no adapter
- *                    CLI and only succeeds for adapters whose binary is
- *                    already on PATH via the base image).
- *   - envKeys:       Which keys the driver should materialize from the
- *                    per-Job env Secret into the container's environment.
- *                    The Secret itself is populated by the server (from
- *                    company secrets) before driver.run() is called.
- *   - allowFqdns:    DNS names the tenant's NetworkPolicy + optional Cilium
- *                    CNP must permit egress to. Per-tenant policy overrides
- *                    via cluster_tenant_policies.networkJson.additionalAllowFqdns
- *                    are merged on top in ensureTenantNamespace.
- *
- * The image tags are appended downstream by the server's resolveRunContext;
- * this registry only carries the image NAME (no tag).
- */
-
-export interface AdapterDefaults {
-  /** Image name without tag, e.g. "ghcr.io/paperclipai/agent-runtime-claude". */
-  runtimeImage: string;
-  /** Env keys to copy from the per-Job Secret into the container environment. */
-  envKeys: string[];
-  /** FQDNs the tenant must be permitted egress to for the adapter to function. */
-  allowFqdns: string[];
-}
-
-const REGISTRY_BASE = "ghcr.io/paperclipai";
-
-export const ADAPTER_DEFAULTS: Record<string, AdapterDefaults> = {
-  claude_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-claude`,
-    envKeys: ["ANTHROPIC_API_KEY"],
-    allowFqdns: ["api.anthropic.com"],
-  },
-  codex_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-codex`,
-    envKeys: ["OPENAI_API_KEY"],
-    allowFqdns: ["api.openai.com"],
-  },
-  gemini_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-gemini`,
-    envKeys: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
-    allowFqdns: ["generativelanguage.googleapis.com"],
-  },
-  acpx_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-acpx`,
-    envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
-    allowFqdns: ["api.anthropic.com", "api.openai.com"],
-  },
-  opencode_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-opencode`,
-    // opencode supports multiple LLM providers (Anthropic, OpenAI, Gemini,
-    // xAI). driver.run() filters adapterEnv strictly to defaults.envKeys
-    // before writing the per-Job Secret, so a key not listed here is
-    // silently dropped — the pod then starts with no provider credentials
-    // and fails at the authentication step. Mirror pi_local's broader
-    // surface and include the matching FQDNs so the tenant NetworkPolicy
-    // permits egress.
-    envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "XAI_API_KEY"],
-    allowFqdns: [
-      "api.anthropic.com",
-      "api.openai.com",
-      "generativelanguage.googleapis.com",
-      "api.x.ai",
-    ],
-  },
-  pi_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-pi`,
-    envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "XAI_API_KEY"],
-    allowFqdns: ["api.anthropic.com", "api.openai.com", "api.x.ai"],
-  },
-  hermes_local: {
-    runtimeImage: `${REGISTRY_BASE}/agent-runtime-hermes`,
-    // Empty defaults: no upstream npm binary identified yet. See
-    // Dockerfile.hermes for the gap and the path forward.
-    envKeys: [],
-    allowFqdns: [],
-  },
-};
-
-export function getAdapterDefaults(adapterType: string): AdapterDefaults {
-  return (
-    ADAPTER_DEFAULTS[adapterType] ?? {
-      runtimeImage: `${REGISTRY_BASE}/agent-runtime-base`,
-      envKeys: [],
-      allowFqdns: [],
-    }
-  );
-}

packages/adapters/kubernetes-execution/src/orchestrator/cancellation.ts

@@ -1,31 +0,0 @@
-import type { KubernetesApiClient } from "../types.js";
-
-/**
- * Cancels a Job by deleting it with foreground propagation. Foreground
- * propagation guarantees that pods owned by the Job are torn down before
- * the Job object itself disappears, so finalizers and per-Job ephemeral
- * Secrets (which carry an OwnerReference back to the Job) get GC'd
- * deterministically.
- *
- * Default grace period is 30 seconds — enough time for the agent shim to
- * flush its final stdout/event payload before SIGKILL.
- */
-export interface CancelJobInput {
-  client: KubernetesApiClient;
-  namespace: string;
-  jobName: string;
-  graceSeconds?: number;
-}
-
-export async function cancelJob(input: CancelJobInput): Promise<void> {
-  const grace = input.graceSeconds ?? 30;
-  await input.client.batch.deleteNamespacedJob(
-    input.jobName,
-    input.namespace,
-    undefined, // pretty
-    undefined, // dryRun
-    grace, // gracePeriodSeconds
-    undefined, // orphanDependents
-    "Foreground", // propagationPolicy
-  );
-}

packages/adapters/kubernetes-execution/src/orchestrator/capabilities.ts

@@ -1,39 +0,0 @@
-import type { KubernetesApiClient, ClusterCapabilities } from "../types.js";
-
-export async function probeClusterCapabilities(client: KubernetesApiClient): Promise<ClusterCapabilities> {
-  const cilium = await detectCilium(client);
-
-  const nodes = await client.core.listNode();
-  const archSet = new Set<"amd64" | "arm64">();
-  for (const node of nodes.body.items) {
-    const arch = node.status?.nodeInfo?.architecture;
-    if (arch === "amd64" || arch === "arm64") archSet.add(arch);
-  }
-  const architectures: ("amd64" | "arm64")[] = archSet.size > 0 ? [...archSet] : ["amd64"];
-
-  const storageClass = await detectStorageClass(client);
-
-  return { cilium, storageClass, architectures };
-}
-
-async function detectCilium(client: KubernetesApiClient): Promise<boolean> {
-  try {
-    const res = await client.request<{ kind?: string } | null>("GET", "/apis/cilium.io/v2");
-    return res != null && res.kind === "APIResourceList";
-  } catch {
-    return false;
-  }
-}
-
-async function detectStorageClass(client: KubernetesApiClient): Promise<string> {
-  type SCList = { items: Array<{ metadata: { name: string; annotations?: Record<string, string> } }> };
-  try {
-    const res = await client.request<SCList | null>("GET", "/apis/storage.k8s.io/v1/storageclasses");
-    if (!res || !res.items.length) return "standard";
-    const isDefault = (sc: SCList["items"][number]) =>
-      sc.metadata.annotations?.["storageclass.kubernetes.io/is-default-class"] === "true";
-    return res.items.find(isDefault)?.metadata.name ?? res.items[0].metadata.name;
-  } catch {
-    return "standard";
-  }
-}

packages/adapters/kubernetes-execution/src/orchestrator/cilium-network-policy.ts

@@ -1,84 +0,0 @@
-import type { KubernetesApiClient } from "../types.js";
-import { tenantBaseLabels, PAPERCLIP_ROLE, ROLE_AGENT_RUNTIME } from "./labels.js";
-
-interface CiliumFqdn {
-  matchPattern?: string;
-  matchName?: string;
-}
-
-export interface CiliumNetworkPolicyDoc {
-  apiVersion: "cilium.io/v2";
-  kind: "CiliumNetworkPolicy";
-  metadata: { name: string; namespace: string; labels?: Record<string, string> };
-  spec: {
-    endpointSelector: { matchLabels: Record<string, string> };
-    egress: Array<{
-      toFQDNs?: CiliumFqdn[];
-      toEndpoints?: Array<{ matchLabels: Record<string, string> }>;
-      toCIDR?: string[];
-      toPorts?: Array<{
-        ports: Array<{ port: string; protocol: string }>;
-        rules?: { dns?: Array<{ matchPattern?: string; matchName?: string }> };
-      }>;
-    }>;
-  };
-}
-
-export interface BuildCiliumInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-  adapterAllowFqdns: string[];
-  tenantAllowFqdns: string[];
-  controlPlaneSelector: { matchLabels: Record<string, string> } | null;
-}
-
-export function buildCiliumAgentEgressPolicy(input: BuildCiliumInput): CiliumNetworkPolicyDoc {
-  const labels = tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug });
-  const merged = Array.from(new Set([...input.adapterAllowFqdns, ...input.tenantAllowFqdns])).sort();
-  const fqdns: CiliumFqdn[] = merged.map(p => p.includes("*") ? { matchPattern: p } : { matchName: p });
-
-  const egress: CiliumNetworkPolicyDoc["spec"]["egress"] = [];
-  if (fqdns.length > 0) {
-    egress.push({ toFQDNs: fqdns, toPorts: [{ ports: [{ port: "443", protocol: "TCP" }] }] });
-  }
-  if (input.controlPlaneSelector) {
-    egress.push({
-      toEndpoints: [{ matchLabels: input.controlPlaneSelector.matchLabels }],
-      toPorts: [{ ports: [{ port: "443", protocol: "TCP" }] }],
-    });
-  }
-
-  return {
-    apiVersion: "cilium.io/v2",
-    kind: "CiliumNetworkPolicy",
-    metadata: { name: "paperclip-agent-egress-l7", namespace: input.namespace, labels },
-    spec: {
-      endpointSelector: { matchLabels: { [PAPERCLIP_ROLE]: ROLE_AGENT_RUNTIME } },
-      egress,
-    },
-  };
-}
-
-export async function applyCiliumNetworkPolicy(client: KubernetesApiClient, p: CiliumNetworkPolicyDoc): Promise<void> {
-  const ns = p.metadata.namespace;
-  const name = p.metadata.name;
-  const itemPath = `/apis/cilium.io/v2/namespaces/${encodeURIComponent(ns)}/ciliumnetworkpolicies/${encodeURIComponent(name)}`;
-  const collectionPath = `/apis/cilium.io/v2/namespaces/${encodeURIComponent(ns)}/ciliumnetworkpolicies`;
-  try {
-    await client.request("GET", itemPath);
-    await client.request("PUT", itemPath, p);
-  } catch (err: unknown) {
-    const is404 =
-      /\b404\b/.test(String(err)) ||
-      (typeof err === "object" && err !== null && (err as Record<string, unknown>)["statusCode"] === 404) ||
-      (typeof err === "object" && err !== null &&
-        typeof (err as Record<string, unknown>)["response"] === "object" &&
-        ((err as Record<string, unknown>)["response"] as Record<string, unknown>)?.["statusCode"] === 404);
-    if (is404) {
-      await client.request("POST", collectionPath, p);
-      return;
-    }
-    throw err;
-  }
-}

packages/adapters/kubernetes-execution/src/orchestrator/cilium-tenant-policy.test.ts

@@ -1,80 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { buildTenantCiliumPolicy } from "./cilium-tenant-policy.js";
-
-describe("buildTenantCiliumPolicy", () => {
-  it("returns null when both arrays are empty (no extra CNP)", () => {
-    const result = buildTenantCiliumPolicy({
-      namespace: "paperclip-acme",
-      companySlug: "acme",
-      dnsAllowlist: [],
-      egressCidrs: [],
-    });
-    expect(result).toBeNull();
-  });
-
-  it("emits an additional CNP with kube-dns + FQDNs when dnsAllowlist is set", () => {
-    const result = buildTenantCiliumPolicy({
-      namespace: "paperclip-acme",
-      companySlug: "acme",
-      dnsAllowlist: ["api.anthropic.com", "github.com"],
-      egressCidrs: [],
-    });
-    expect(result).not.toBeNull();
-    if (!result) return;
-    expect(result.metadata.name).toBe("paperclip-tenant-acme-restrict");
-    expect(result.metadata.namespace).toBe("paperclip-acme");
-    expect(result.spec.endpointSelector.matchLabels["paperclip.ai/managed-by"]).toBe("paperclip");
-    // Always-on kube-dns rule preserves DNS resolution for the FQDNs themselves.
-    const kubeDnsRule = result.spec.egress.find((r) =>
-      r.toEndpoints?.some((e) => e.matchLabels["k8s:k8s-app"] === "kube-dns"),
-    );
-    expect(kubeDnsRule).toBeDefined();
-    // FQDN rule contains the two allowlisted hosts and uses matchName for non-wildcard entries.
-    const fqdnRule = result.spec.egress.find((r) => r.toFQDNs);
-    expect(fqdnRule?.toFQDNs).toEqual([{ matchName: "api.anthropic.com" }, { matchName: "github.com" }]);
-    // FQDN rule mirrors the M1 baseline by pinning to 443/TCP so the
-    // tenant policy is self-documenting (no behaviour change because
-    // Cilium AND-intersects it with the baseline).
-    expect(fqdnRule?.toPorts).toEqual([{ ports: [{ port: "443", protocol: "TCP" }] }]);
-  });
-
-  it("uses matchPattern for wildcard FQDNs", () => {
-    const result = buildTenantCiliumPolicy({
-      namespace: "paperclip-acme",
-      companySlug: "acme",
-      dnsAllowlist: ["*.linear.app"],
-      egressCidrs: [],
-    });
-    expect(result).not.toBeNull();
-    const fqdnRule = result!.spec.egress.find((r) => r.toFQDNs);
-    expect(fqdnRule?.toFQDNs).toEqual([{ matchPattern: "*.linear.app" }]);
-  });
-
-  it("includes a toCIDR rule when egressCidrs is set", () => {
-    const result = buildTenantCiliumPolicy({
-      namespace: "paperclip-acme",
-      companySlug: "acme",
-      dnsAllowlist: [],
-      egressCidrs: ["10.42.0.0/16", "172.20.0.0/12"],
-    });
-    expect(result).not.toBeNull();
-    const cidrRule = result!.spec.egress.find((r) => r.toCIDR);
-    expect(cidrRule?.toCIDR).toEqual(["10.42.0.0/16", "172.20.0.0/12"]);
-    expect(cidrRule?.toPorts).toEqual([{ ports: [{ port: "443", protocol: "TCP" }] }]);
-  });
-
-  it("emits both DNS and CIDR rules when both are set", () => {
-    const result = buildTenantCiliumPolicy({
-      namespace: "paperclip-acme",
-      companySlug: "acme",
-      dnsAllowlist: ["api.anthropic.com"],
-      egressCidrs: ["10.42.0.0/16"],
-    });
-    expect(result).not.toBeNull();
-    expect(result!.spec.egress.some((r) => r.toFQDNs)).toBe(true);
-    expect(result!.spec.egress.some((r) => r.toCIDR)).toBe(true);
-    expect(result!.spec.egress.some((r) =>
-      r.toEndpoints?.some((e) => e.matchLabels["k8s:k8s-app"] === "kube-dns"),
-    )).toBe(true);
-  });
-});

packages/adapters/kubernetes-execution/src/orchestrator/cilium-tenant-policy.ts

@@ -1,78 +0,0 @@
-import type { CiliumNetworkPolicyDoc } from "./cilium-network-policy.js";
-
-export interface BuildTenantCiliumInput {
-  namespace: string;
-  companySlug: string;
-  dnsAllowlist: string[];
-  egressCidrs: string[];
-}
-
-/**
- * Build a per-tenant CiliumNetworkPolicy that narrows tenant egress.
- *
- * Cilium combines multiple allow-only policies selecting the same endpoint as
- * a union, so every rule emitted here must carry its own safety bounds instead
- * of relying on the baseline policy to subtract ports later.
- *
- * Returns `null` when both arrays are empty, in which case
- * `ensureTenantNamespace` does not apply a second CNP and the M1 baseline
- * alone governs egress.
- */
-export function buildTenantCiliumPolicy(input: BuildTenantCiliumInput): CiliumNetworkPolicyDoc | null {
-  if (input.dnsAllowlist.length === 0 && input.egressCidrs.length === 0) return null;
-
-  const egress: CiliumNetworkPolicyDoc["spec"]["egress"] = [];
-
-  // Always preserve kube-dns access. Without this, a dnsAllowlist of
-  // ["api.anthropic.com"] would also block DNS resolution for that very
-  // host and the agent would fail to resolve any FQDN at all.
-  egress.push({
-    toEndpoints: [{
-      matchLabels: {
-        "k8s:io.kubernetes.pod.namespace": "kube-system",
-        "k8s:k8s-app": "kube-dns",
-      },
-    }],
-    toPorts: [{
-      ports: [{ port: "53", protocol: "ANY" }],
-      rules: { dns: [{ matchPattern: "*" }] },
-    }],
-  });
-
-  if (input.dnsAllowlist.length > 0) {
-    // Mirror the M1 baseline shape — `toFQDNs` plus an explicit
-    // `toPorts: [443/TCP]`. This is a no-op behaviorally because Cilium
-    // AND-intersects this CNP with the M1 baseline, which already
-    // restricts egress to 443/TCP — so the effective port set is
-    // unchanged. Emitting it here makes the tenant policy
-    // self-documenting on its own (a reader doesn't have to chase the
-    // baseline to see why arbitrary ports aren't reachable) and keeps
-    // both policies symmetric so future port additions only need to
-    // change one shape.
-    egress.push({
-      toFQDNs: input.dnsAllowlist.map((dns) =>
-        dns.includes("*") ? { matchPattern: dns } : { matchName: dns },
-      ),
-      toPorts: [{ ports: [{ port: "443", protocol: "TCP" }] }],
-    });
-  }
-  if (input.egressCidrs.length > 0) {
-    egress.push({
-      toCIDR: input.egressCidrs,
-      toPorts: [{ ports: [{ port: "443", protocol: "TCP" }] }],
-    });
-  }
-
-  return {
-    apiVersion: "cilium.io/v2",
-    kind: "CiliumNetworkPolicy",
-    metadata: {
-      name: `paperclip-tenant-${input.companySlug}-restrict`,
-      namespace: input.namespace,
-    },
-    spec: {
-      endpointSelector: { matchLabels: { "paperclip.ai/managed-by": "paperclip" } },
-      egress,
-    },
-  };
-}

packages/adapters/kubernetes-execution/src/orchestrator/ensure-tenant.ts

@@ -1,154 +0,0 @@
-import type { KubernetesApiClient, ResolvedClusterConnection } from "../types.js";
-import { deriveNamespaceName } from "./naming.js";
-import { buildNamespace, applyNamespace } from "./namespace.js";
-import {
-  buildAgentServiceAccount, applyAgentServiceAccount,
-  buildDriverRoleBinding, applyDriverRoleBinding,
-} from "./rbac.js";
-import {
-  buildResourceQuota, buildLimitRange,
-  applyResourceQuota, applyLimitRange,
-  type QuotaOverride, type LimitRangeOverride,
-} from "./resource-quota.js";
-import {
-  buildDefaultDenyPolicies, buildAgentEgressPolicy, applyNetworkPolicy,
-} from "./network-policy.js";
-import {
-  buildCiliumAgentEgressPolicy, applyCiliumNetworkPolicy,
-} from "./cilium-network-policy.js";
-import { buildTenantCiliumPolicy } from "./cilium-tenant-policy.js";
-import {
-  buildImagePullSecret, applyImagePullSecret,
-} from "./image-pull-secret.js";
-
-export interface TenantPolicy {
-  quota: QuotaOverride | null;
-  limitRange: LimitRangeOverride | null;
-  additionalAllowFqdns: string[];
-  imageOverrides: Record<string, string> | null;
-  /** Cilium DSL — empty array means "no extra restrictions beyond M1 baseline". */
-  ciliumDnsAllowlist?: string[];
-  /** Cilium DSL — empty array means "no extra CIDR restrictions". */
-  ciliumEgressCidrs?: string[];
-}
-
-export interface EnsureTenantInput {
-  connection: ResolvedClusterConnection;
-  company: { id: string; slug: string };
-  tenantPolicy: TenantPolicy | null;
-  driverServiceAccount: { name: string; namespace: string };
-  controlPlane: {
-    topology: "in-cluster" | "cross-cluster";
-    namespaceLabels: Record<string, string>;
-    podLabels: Record<string, string>;
-  };
-  adapterAllowFqdns: string[];
-  /** Resolved registry credentials. If null, no image pull secret is created. */
-  imagePullDockerConfigJson: string | null;
-}
-
-export interface EnsureTenantResult {
-  namespace: string;
-  ciliumApplied: boolean;
-}
-
-/**
- * Idempotently provision a tenant namespace with all isolation primitives:
- * Namespace → RBAC → ResourceQuota/LimitRange → NetworkPolicies → optional CiliumNetworkPolicy → optional image pull secret.
- *
- * Order matters: the Namespace must be created first because everything else is namespaced.
- * The remaining objects can be in any order, but we prefer the creation order to match the
- * "outer to inner" reading flow for kubectl debuggability (rbac → quota → policies → secrets).
- */
-export async function ensureTenantNamespace(
-  client: KubernetesApiClient,
-  input: EnsureTenantInput,
-): Promise<EnsureTenantResult> {
-  const namespace = deriveNamespaceName({
-    companySlug: input.company.slug,
-    companyId: input.company.id,
-    prefix: input.connection.defaultNamespacePrefix,
-  });
-
-  // 1. Namespace (must come first).
-  await applyNamespace(client, buildNamespace({
-    name: namespace,
-    companyId: input.company.id,
-    companySlug: input.company.slug,
-  }));
-
-  // 2. RBAC.
-  await applyAgentServiceAccount(client, buildAgentServiceAccount({
-    namespace, companyId: input.company.id, companySlug: input.company.slug,
-  }));
-  await applyDriverRoleBinding(client, buildDriverRoleBinding({
-    namespace,
-    driverServiceAccount: input.driverServiceAccount,
-    clusterRoleName: "paperclip-tenant-manager",
-    companyId: input.company.id, companySlug: input.company.slug,
-  }));
-
-  // 3. Quota & LimitRange.
-  await applyResourceQuota(client, buildResourceQuota({
-    namespace, companyId: input.company.id, companySlug: input.company.slug,
-    override: input.tenantPolicy?.quota ?? null,
-  }));
-  await applyLimitRange(client, buildLimitRange({
-    namespace, companyId: input.company.id, companySlug: input.company.slug,
-    override: input.tenantPolicy?.limitRange ?? null,
-  }));
-
-  // 4. NetworkPolicies (vanilla — always).
-  for (const p of buildDefaultDenyPolicies({
-    namespace, companyId: input.company.id, companySlug: input.company.slug,
-  })) {
-    await applyNetworkPolicy(client, p);
-  }
-  await applyNetworkPolicy(client, buildAgentEgressPolicy({
-    namespace,
-    companyId: input.company.id,
-    companySlug: input.company.slug,
-    topology: input.controlPlane.topology,
-    controlPlaneSelector: input.controlPlane.topology === "in-cluster"
-      ? { namespaceLabel: input.controlPlane.namespaceLabels, podLabel: input.controlPlane.podLabels }
-      : null,
-  }));
-
-  // 5. Cilium policy (only when cluster supports it).
-  let ciliumApplied = false;
-  if (input.connection.capabilities.cilium) {
-    await applyCiliumNetworkPolicy(client, buildCiliumAgentEgressPolicy({
-      namespace,
-      companyId: input.company.id,
-      companySlug: input.company.slug,
-      adapterAllowFqdns: input.adapterAllowFqdns,
-      tenantAllowFqdns: input.tenantPolicy?.additionalAllowFqdns ?? [],
-      controlPlaneSelector: input.controlPlane.topology === "in-cluster"
-        ? { matchLabels: input.controlPlane.namespaceLabels }
-        : null,
-    }));
-    // Tenant Cilium rules are allow-list rules and combine with other matching
-    // CNPs by union, so each emitted rule carries its own port/protocol bounds.
-    // Empty arrays in the policy -> builder returns null -> no tenant CNP applied.
-    const tenantCnp = buildTenantCiliumPolicy({
-      namespace,
-      companySlug: input.company.slug,
-      dnsAllowlist: input.tenantPolicy?.ciliumDnsAllowlist ?? [],
-      egressCidrs: input.tenantPolicy?.ciliumEgressCidrs ?? [],
-    });
-    if (tenantCnp) {
-      await applyCiliumNetworkPolicy(client, tenantCnp);
-    }
-    ciliumApplied = true;
-  }
-
-  // 6. Image pull secret (when registry creds were supplied).
-  if (input.imagePullDockerConfigJson) {
-    await applyImagePullSecret(client, buildImagePullSecret({
-      namespace, companyId: input.company.id, companySlug: input.company.slug,
-      dockerConfigJson: input.imagePullDockerConfigJson,
-    }));
-  }
-
-  return { namespace, ciliumApplied };
-}

packages/adapters/kubernetes-execution/src/orchestrator/event-watch.ts

@@ -1,114 +0,0 @@
-import type { KubernetesApiClient } from "../types.js";
-
-/**
- * Watches Kubernetes Events for a given Job (and its Pod via the same
- * involvedObject.name field selector) and surfaces Warning events as
- * `[k8s] <reason>: <message>` log lines through `onLog`. Normal events
- * are intentionally dropped — they're noisy and not actionable for users.
- */
-export interface EventWatchHandle {
-  abort(): void;
-  done: Promise<void>;
-}
-
-export interface StartEventWatchInput {
-  client: KubernetesApiClient;
-  namespace: string;
-  /** Filter to events whose involvedObject is the Job or its Pod. */
-  jobName: string;
-  onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
-}
-
-interface RawWatchEvent {
-  type: string;
-  object: {
-    metadata?: { resourceVersion?: string };
-    type?: string;
-    reason?: string;
-    message?: string;
-    involvedObject?: { kind?: string; name?: string };
-  };
-}
-
-export function startEventWatch(input: StartEventWatchInput): EventWatchHandle {
-  const controller = new AbortController();
-  let resolveDone!: () => void;
-  const done = new Promise<void>((res) => {
-    resolveDone = res;
-  });
-
-  const loop = async () => {
-    // No fieldSelector: a Kubernetes fieldSelector on Event only supports
-    // exact-match keys, so we cannot select Job-events AND Pod-events
-    // (which carry a generated name like `<jobName>-<hash>`) in a single
-    // watch. The most actionable failure events — OOMKilling, BackOff,
-    // ImagePullBackOff, Failed — are emitted against the Pod, not the Job,
-    // so a `involvedObject.name=<jobName>` filter silently dropped them and
-    // users debugging an OOM saw zero `[k8s]` output.
-    //
-    // We watch all events in the tenant namespace (which is exclusively
-    // Paperclip-managed) and filter in-code by involvedObject:
-    //   - kind=Job   AND name === jobName
-    //   - kind=Pod   AND name starts with `<jobName>-`  (Job-spawned pod naming)
-    // The volume is bounded by the namespace's own pod count and is well
-    // within reasonable streaming overhead.
-    let resourceVersion = "0";
-    while (!controller.signal.aborted) {
-      try {
-        const path =
-          `/api/v1/namespaces/${encodeURIComponent(input.namespace)}/events` +
-          `?watch=true&resourceVersion=${resourceVersion}`;
-        const res = await input.client.requestStream("GET", path);
-        if (!res.ok || !res.body) break;
-        const reader = res.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-        while (!controller.signal.aborted) {
-          const { value, done: streamDone } = await reader.read();
-          if (streamDone) break;
-          buffer += decoder.decode(value, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop() ?? "";
-          for (const line of lines) {
-            if (!line.trim()) continue;
-            try {
-              const evt = JSON.parse(line) as RawWatchEvent;
-              if (evt.object.metadata?.resourceVersion) {
-                resourceVersion = evt.object.metadata.resourceVersion;
-              }
-              if (evt.object.type !== "Warning") continue;
-              const involved = evt.object.involvedObject;
-              const matchesJob = involved?.kind === "Job" && involved?.name === input.jobName;
-              const matchesPod =
-                involved?.kind === "Pod" &&
-                typeof involved?.name === "string" &&
-                involved.name.startsWith(`${input.jobName}-`);
-              if (!matchesJob && !matchesPod) continue;
-              await input.onLog(
-                "stdout",
-                `[k8s] ${evt.object.reason ?? "Warning"}: ${evt.object.message ?? ""}`,
-              );
-            } catch {
-              /* skip malformed line — partial JSON, recoverable */
-            }
-          }
-        }
-        if (controller.signal.aborted) break;
-        await new Promise((r) => setTimeout(r, 500));
-      } catch {
-        if (controller.signal.aborted) break;
-        await new Promise((r) => setTimeout(r, 500));
-      }
-    }
-    resolveDone();
-  };
-
-  loop().catch(() => {
-    /* swallow; abort path always resolves done */
-  });
-
-  return {
-    abort: () => controller.abort(),
-    done,
-  };
-}

packages/adapters/kubernetes-execution/src/orchestrator/failure-mapping.ts

@@ -1,117 +0,0 @@
-import type { V1Job, V1Pod } from "@kubernetes/client-node";
-import type { AdapterExecutionResult } from "@paperclipai/adapter-utils";
-
-/**
- * Pure function: takes a terminal Job + Pod state and returns the
- * AdapterExecutionResult the driver should hand back to the caller.
- *
- * Mapping order matters — we check earlier (more specific) reasons first
- * so e.g. ImagePullBackOff is reported as image_pull_failed even though
- * Job.status.failed may also be ≥1 by the time we observe it.
- *
- * Recognised error codes (Spec §7.5):
- *   - image_pull_failed       (transient_upstream family)
- *   - workspace_init_failed
- *   - oom_killed
- *   - timeout
- *   - agent_exit_nonzero
- *   - unknown_terminal_state  (fallback when Job/Pod expose no terminal signal)
- */
-export interface MapTerminalStateInput {
-  job: V1Job;
-  pod?: V1Pod;
-}
-
-export function mapTerminalState(input: MapTerminalStateInput): AdapterExecutionResult {
-  const job = input.job;
-  const pod = input.pod;
-
-  // Success path — Job marked succeeded; surface the agent container's exit code.
-  if ((job.status?.succeeded ?? 0) >= 1) {
-    const main = pod?.status?.containerStatuses?.find((c) => c.name === "agent");
-    return {
-      exitCode: main?.state?.terminated?.exitCode ?? 0,
-      signal: null,
-      timedOut: false,
-    };
-  }
-
-  const containers = pod?.status?.containerStatuses ?? [];
-  const initContainers = pod?.status?.initContainerStatuses ?? [];
-
-  // ImagePullBackOff — latched on container statuses (init or main). Transient
-  // upstream so retryable per the existing AdapterExecutionErrorFamily rules.
-  for (const c of [...containers, ...initContainers]) {
-    const reason = c.state?.waiting?.reason;
-    if (reason === "ImagePullBackOff" || reason === "ErrImagePull") {
-      return {
-        exitCode: null,
-        signal: null,
-        timedOut: false,
-        errorCode: "image_pull_failed",
-        errorFamily: "transient_upstream",
-        errorMessage: `Image pull failed for container ${c.name}: ${c.state?.waiting?.message ?? reason}`,
-      };
-    }
-  }
-
-  // Init container terminal failure (e.g. workspace clone failed).
-  for (const c of initContainers) {
-    if (c.state?.terminated && c.state.terminated.exitCode !== 0) {
-      return {
-        exitCode: null,
-        signal: null,
-        timedOut: false,
-        errorCode: "workspace_init_failed",
-        errorMessage:
-          `Init container ${c.name} exited ${c.state.terminated.exitCode}: ${c.state.terminated.reason ?? ""} ${c.state.terminated.message ?? ""}`.trim(),
-      };
-    }
-  }
-
-  // OOM killed — accept either the explicit reason or the conventional 137 exit code.
-  for (const c of containers) {
-    if (c.state?.terminated?.reason === "OOMKilled" || c.state?.terminated?.exitCode === 137) {
-      return {
-        exitCode: 137,
-        signal: "SIGKILL",
-        timedOut: false,
-        errorCode: "oom_killed",
-        errorMessage: `Container ${c.name} OOMKilled`,
-      };
-    }
-  }
-
-  // Job-level deadline exceeded — surfaces as `timedOut: true` for billing/retry policy.
-  if (job.status?.conditions?.some((cond) => cond.type === "Failed" && cond.reason === "DeadlineExceeded")) {
-    return {
-      exitCode: null,
-      signal: "SIGTERM",
-      timedOut: true,
-      errorCode: "timeout",
-      errorMessage: "Job exceeded activeDeadlineSeconds",
-    };
-  }
-
-  // Generic terminal failure — Job.status.failed ≥ 1 with no specific cause matched above.
-  if ((job.status?.failed ?? 0) >= 1) {
-    const main = containers.find((c) => c.name === "agent");
-    const exit = main?.state?.terminated?.exitCode ?? null;
-    return {
-      exitCode: exit,
-      signal: null,
-      timedOut: false,
-      errorCode: "agent_exit_nonzero",
-      errorMessage: main?.state?.terminated?.message ?? `Agent exited ${exit}`,
-    };
-  }
-
-  // No terminal state observed — driver should not hit this in normal operation.
-  return {
-    exitCode: null,
-    signal: null,
-    timedOut: false,
-    errorCode: "unknown_terminal_state",
-    errorMessage: "No terminal state observed on Job/Pod",
-  };
-}

packages/adapters/kubernetes-execution/src/orchestrator/image-pull-secret.ts

@@ -1,44 +0,0 @@
-import type { V1Secret } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import { tenantBaseLabels } from "./labels.js";
-
-export interface BuildImagePullSecretInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-  /** Already-resolved docker config JSON string (from a Paperclip secret_ref). */
-  dockerConfigJson: string;
-}
-
-export function buildImagePullSecret(input: BuildImagePullSecretInput): V1Secret {
-  return {
-    apiVersion: "v1",
-    kind: "Secret",
-    metadata: {
-      name: "paperclip-image-pull",
-      namespace: input.namespace,
-      labels: tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-    },
-    type: "kubernetes.io/dockerconfigjson",
-    data: {
-      ".dockerconfigjson": Buffer.from(input.dockerConfigJson, "utf-8").toString("base64"),
-    },
-  };
-}
-
-export async function applyImagePullSecret(client: KubernetesApiClient, s: V1Secret): Promise<void> {
-  const ns = s.metadata!.namespace!;
-  const name = s.metadata!.name!;
-  try {
-    await client.core.readNamespacedSecret(name, ns);
-    await client.core.patchNamespacedSecret(name, ns, s, undefined, undefined, undefined, undefined, undefined, {
-      headers: { "Content-Type": "application/strategic-merge-patch+json" },
-    } as never);
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) {
-      await client.core.createNamespacedSecret(ns, s);
-      return;
-    }
-    throw err;
-  }
-}

packages/adapters/kubernetes-execution/src/orchestrator/job.ts

@@ -1,165 +0,0 @@
-import type { V1Job, V1Container, V1Volume } from "@kubernetes/client-node";
-import {
-  tenantBaseLabels, PAPERCLIP_AGENT_ID, PAPERCLIP_RUN_ID, PAPERCLIP_ROLE, ROLE_AGENT_RUNTIME,
-} from "./labels.js";
-
-export interface BuildJobInput {
-  namespace: string;
-  agentId: string;
-  agentSlug: string;
-  runId: string;
-  runUlid: string;
-  companyId: string;
-  companySlug: string;
-  adapterType: string;
-  /** Image for the main container (e.g. ghcr.io/paperclipai/agent-runtime-claude:vX.Y.Z) */
-  image: string;
-  /** Image for the init container (always agent-runtime-base; baked-in workspace-init). */
-  initImage: string;
-  imagePullSecrets?: string[];
-  pvcName: string;
-  envSecretName: string;
-  /** Resource requests/limits for the main container. */
-  resources?: {
-    requests?: { cpu?: string; memory?: string };
-    limits?:   { cpu?: string; memory?: string };
-  };
-  /** Hard ceiling for the run; clamped against ResourceQuota.maxRunSeconds upstream. */
-  activeDeadlineSeconds: number;
-  ttlSecondsAfterFinished: number;
-  /** Workspace strategy serialized as JSON for the init container. */
-  workspaceStrategyJson: string;
-  /** AdapterRuntimeCommandSpec serialized as JSON for paperclip-agent-shim. */
-  runtimeCommandSpecJson: string;
-  paperclipPublicUrl: string;
-  /** Trace context propagated into the pod. */
-  traceparent?: string;
-}
-
-export function buildAgentJob(input: BuildJobInput): V1Job {
-  const labels = {
-    ...tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-    [PAPERCLIP_AGENT_ID]: input.agentId,
-    [PAPERCLIP_RUN_ID]:   input.runId,
-    [PAPERCLIP_ROLE]:     ROLE_AGENT_RUNTIME,
-  };
-
-  const volumes: V1Volume[] = [
-    { name: "workspace", persistentVolumeClaim: { claimName: input.pvcName } },
-    { name: "tmp", emptyDir: { sizeLimit: "1Gi" } },
-    { name: "env", secret: { secretName: input.envSecretName, defaultMode: 0o400 } },
-  ];
-
-  const restrictedSecurity = {
-    runAsNonRoot: true,
-    runAsUser: 1000,
-    runAsGroup: 1000,
-    fsGroup: 1000,
-    seccompProfile: { type: "RuntimeDefault" as const },
-  };
-
-  const containerSecurity = {
-    allowPrivilegeEscalation: false,
-    readOnlyRootFilesystem: true,
-    capabilities: { drop: ["ALL"] },
-  };
-
-  const initContainer: V1Container = {
-    name: "workspace-init",
-    image: input.initImage,
-    command: ["/usr/local/bin/paperclip-workspace-init"],
-    env: [
-      // workspace-init reads this env var; the name must match the constant
-      // it expects (process.env.PAPERCLIP_WORKSPACE_REQUEST). The value is a
-      // serialized WorkspaceRealizationRequest carrying version + source +
-      // strategy. The internal field is named workspaceStrategyJson for
-      // historical reasons; the wire-level env var is the contract.
-      { name: "PAPERCLIP_WORKSPACE_REQUEST", value: input.workspaceStrategyJson },
-      { name: "PAPERCLIP_WORKSPACE_ROOT", value: "/workspace" },
-      { name: "PAPERCLIP_RUN_ID", value: input.runId },
-      { name: "PAPERCLIP_PUBLIC_URL", value: input.paperclipPublicUrl },
-      { name: "BOOTSTRAP_TOKEN", valueFrom: { secretKeyRef: { name: input.envSecretName, key: "BOOTSTRAP_TOKEN" } } },
-    ],
-    volumeMounts: [
-      { name: "workspace", mountPath: "/workspace" },
-      { name: "tmp", mountPath: "/tmp" },
-    ],
-    securityContext: containerSecurity,
-    resources: {
-      requests: { cpu: "200m", memory: "256Mi" },
-      limits:   { cpu: "2",    memory: "1Gi"  },
-    },
-  };
-
-  const mainContainer: V1Container = {
-    name: "agent",
-    image: input.image,
-    imagePullPolicy: "IfNotPresent",
-    workingDir: "/workspace",
-    command: ["/usr/bin/tini", "--"],
-    args: ["/usr/local/bin/paperclip-agent-shim", "--adapter", input.adapterType],
-    env: [
-      { name: "PAPERCLIP_RUN_ID", value: input.runId },
-      { name: "PAPERCLIP_PUBLIC_URL", value: input.paperclipPublicUrl },
-      ...(input.traceparent ? [{ name: "TRACEPARENT", value: input.traceparent }] : []),
-    ],
-    // BOOTSTRAP_TOKEN (and any other agent-shim secrets) are loaded from the
-    // tenant env Secret; envFrom is the single source of truth for those keys.
-    envFrom: [{ secretRef: { name: input.envSecretName } }],
-    volumeMounts: [
-      { name: "workspace", mountPath: "/workspace" },
-      { name: "tmp", mountPath: "/tmp" },
-      { name: "env", mountPath: "/run/paperclip/env", readOnly: true },
-      { name: "env", mountPath: "/run/paperclip/runtime-command.json", subPath: "runtime-command.json", readOnly: true },
-    ],
-    resources: input.resources ?? {},
-    securityContext: containerSecurity,
-  };
-
-  return {
-    apiVersion: "batch/v1",
-    kind: "Job",
-    metadata: {
-      name: `agent-${input.agentSlug}-run-${input.runUlid}`,
-      namespace: input.namespace,
-      labels,
-    },
-    spec: {
-      backoffLimit: 0,
-      ttlSecondsAfterFinished: input.ttlSecondsAfterFinished,
-      activeDeadlineSeconds: input.activeDeadlineSeconds,
-      completions: 1,
-      parallelism: 1,
-      podFailurePolicy: {
-        rules: [
-          { action: "FailJob", onPodConditions: [{ type: "PodHasNetwork", status: "False" }] },
-          { action: "FailJob", onExitCodes: { containerName: "agent", operator: "In", values: [137] } },
-        ],
-      },
-      template: {
-        metadata: {
-          labels,
-          annotations: { "paperclip.ai/job-spec-version": "v1" },
-        },
-        spec: {
-          automountServiceAccountToken: false,
-          serviceAccountName: "paperclip-agent",
-          restartPolicy: "Never",
-          enableServiceLinks: false,
-          terminationGracePeriodSeconds: 30,
-          securityContext: restrictedSecurity,
-          imagePullSecrets: input.imagePullSecrets?.map((name) => ({ name })) ?? [],
-          initContainers: [initContainer],
-          containers: [mainContainer],
-          volumes,
-        },
-      },
-    },
-  };
-}
-
-/** Apply (create) the Job. Returns the server-assigned UID for OwnerReference wiring. */
-export async function createAgentJob(client: import("../types.js").KubernetesApiClient, job: V1Job): Promise<{ name: string; uid: string }> {
-  const created = await client.batch.createNamespacedJob(job.metadata!.namespace!, job);
-  return { name: created.body.metadata!.name!, uid: created.body.metadata!.uid! };
-}

packages/adapters/kubernetes-execution/src/orchestrator/labels.ts

@@ -1,27 +0,0 @@
-export const PAPERCLIP_MANAGED_BY = "paperclip.ai/managed-by";
-export const PAPERCLIP_MANAGED_BY_VALUE = "paperclip";
-
-export const PAPERCLIP_COMPANY_ID    = "paperclip.ai/company-id";
-export const PAPERCLIP_COMPANY_SLUG  = "paperclip.ai/company-slug";
-export const PAPERCLIP_AGENT_ID      = "paperclip.ai/agent-id";
-export const PAPERCLIP_RUN_ID        = "paperclip.ai/run-id";
-export const PAPERCLIP_ROLE          = "paperclip.ai/role";
-export const PAPERCLIP_ARCHIVED      = "paperclip.ai/archived";
-export const PAPERCLIP_WORKSPACE_STRATEGY = "paperclip.ai/workspace-strategy";
-
-export const ROLE_AGENT_RUNTIME      = "agent-runtime";
-export const ROLE_AGENT_WORKSPACE    = "agent-workspace";
-export const ROLE_CONTROL_PLANE      = "control-plane";
-
-export const PSS_ENFORCE = "pod-security.kubernetes.io/enforce";
-export const PSS_AUDIT   = "pod-security.kubernetes.io/audit";
-export const PSS_WARN    = "pod-security.kubernetes.io/warn";
-export const PSS_RESTRICTED = "restricted";
-
-export function tenantBaseLabels(input: { companyId: string; companySlug: string }): Record<string, string> {
-  return {
-    [PAPERCLIP_MANAGED_BY]:   PAPERCLIP_MANAGED_BY_VALUE,
-    [PAPERCLIP_COMPANY_ID]:   input.companyId,
-    [PAPERCLIP_COMPANY_SLUG]: input.companySlug,
-  };
-}

packages/adapters/kubernetes-execution/src/orchestrator/log-stream.ts

@@ -1,82 +0,0 @@
-import type { KubernetesApiClient } from "../types.js";
-
-/**
- * Streams logs from a Pod's container via `pods/log?follow=true&timestamps=true`,
- * line-buffers the response, strips the leading RFC3339 timestamp, and forwards
- * each line to `onLog`. Reconnects automatically using `sinceTime=<lastTimestamp>`
- * so we don't double-buffer on transient server-side closes.
- *
- * The handle's `done` Promise resolves once the loop exits (after `abort()`).
- */
-export interface LogStreamHandle {
-  abort(): void;
-  done: Promise<void>;
-}
-
-export interface StartLogStreamInput {
-  client: KubernetesApiClient;
-  namespace: string;
-  podName: string;
-  containerName: string;
-  onLog: (stream: "stdout" | "stderr", chunk: string) => Promise<void>;
-}
-
-export function startLogStream(input: StartLogStreamInput): LogStreamHandle {
-  const controller = new AbortController();
-  let resolveDone!: () => void;
-  const done = new Promise<void>((res) => {
-    resolveDone = res;
-  });
-
-  const start = async () => {
-    let lastTimestamp: string | undefined;
-    while (!controller.signal.aborted) {
-      try {
-        const path =
-          `/api/v1/namespaces/${encodeURIComponent(input.namespace)}/pods/${encodeURIComponent(input.podName)}/log` +
-          `?container=${encodeURIComponent(input.containerName)}&follow=true&timestamps=true` +
-          (lastTimestamp ? `&sinceTime=${encodeURIComponent(lastTimestamp)}` : "");
-        const response = await input.client.requestStream("GET", path);
-        if (!response.ok || !response.body) break;
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-        while (!controller.signal.aborted) {
-          const { value, done: streamDone } = await reader.read();
-          if (streamDone) break;
-          // stream:true preserves partial UTF-8 sequences across chunk boundaries.
-          buffer += decoder.decode(value, { stream: true });
-          const lines = buffer.split("\n");
-          buffer = lines.pop() ?? "";
-          for (const line of lines) {
-            const sep = line.indexOf(" ");
-            if (sep > 0) {
-              const ts = line.slice(0, sep);
-              lastTimestamp = ts;
-              await input.onLog("stdout", line.slice(sep + 1));
-            } else if (line.length > 0) {
-              await input.onLog("stdout", line);
-            }
-          }
-        }
-        if (controller.signal.aborted) break;
-        // Stream ended cleanly but pod may still be running — back off and reconnect.
-        await new Promise((r) => setTimeout(r, 500));
-      } catch {
-        if (controller.signal.aborted) break;
-        await new Promise((r) => setTimeout(r, 500));
-      }
-    }
-    resolveDone();
-  };
-
-  // Kick off in the background; the loop above handles its own errors and reconnects.
-  start().catch(() => {
-    /* swallow; abort path always resolves done */
-  });
-
-  return {
-    abort: () => controller.abort(),
-    done,
-  };
-}

packages/adapters/kubernetes-execution/src/orchestrator/namespace.ts

@@ -1,86 +0,0 @@
-import type { V1Namespace } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import {
-  PSS_ENFORCE, PSS_AUDIT, PSS_WARN, PSS_RESTRICTED,
-  tenantBaseLabels, PAPERCLIP_MANAGED_BY, PAPERCLIP_MANAGED_BY_VALUE,
-  PAPERCLIP_COMPANY_ID,
-} from "./labels.js";
-
-export interface BuildNamespaceInput {
-  name: string;
-  companyId: string;
-  companySlug: string;
-  extraLabels?: Record<string, string>;
-}
-
-export function buildNamespace(input: BuildNamespaceInput): V1Namespace {
-  return {
-    apiVersion: "v1",
-    kind: "Namespace",
-    metadata: {
-      name: input.name,
-      labels: {
-        ...tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-        [PSS_ENFORCE]: PSS_RESTRICTED,
-        [PSS_AUDIT]:   PSS_RESTRICTED,
-        [PSS_WARN]:    PSS_RESTRICTED,
-        ...input.extraLabels,
-      },
-    },
-  };
-}
-
-/**
- * Idempotently apply a tenant namespace. Refuses to overwrite a namespace
- * that is not labeled `paperclip.ai/managed-by=paperclip` OR that belongs to
- * a different company than the one being applied. Without the company-id
- * check, two companies whose slugs collide on a short prefix (e.g. both
- * derive `paperclip-acme`) would silently take over each other's namespace
- * — a multi-tenancy isolation breach.
- */
-export async function applyNamespace(
-  client: KubernetesApiClient,
-  ns: V1Namespace,
-): Promise<{ created: boolean }> {
-  const name = ns.metadata!.name!;
-  const incomingCompanyId = ns.metadata?.labels?.[PAPERCLIP_COMPANY_ID];
-  try {
-    const existing = await client.core.readNamespace(name);
-    const managed = existing.body.metadata?.labels?.[PAPERCLIP_MANAGED_BY];
-    if (managed !== PAPERCLIP_MANAGED_BY_VALUE) {
-      throw new Error(
-        `Refusing to manage namespace "${name}": missing label ${PAPERCLIP_MANAGED_BY}=${PAPERCLIP_MANAGED_BY_VALUE}`,
-      );
-    }
-    const existingCompanyId = existing.body.metadata?.labels?.[PAPERCLIP_COMPANY_ID];
-    // We only enforce the cross-tenant check when both sides carry a
-    // company-id label. A pre-existing managed-by=paperclip namespace without
-    // a company-id (legacy / pre-M1) is treated as adoptable by the current
-    // call. Once it's been written once with a company-id, every future
-    // application must match — which is the lock we need.
-    if (
-      existingCompanyId !== undefined &&
-      incomingCompanyId !== undefined &&
-      existingCompanyId !== incomingCompanyId
-    ) {
-      throw new Error(
-        `Refusing to manage namespace "${name}": labeled for company ${existingCompanyId}, not ${incomingCompanyId}`,
-      );
-    }
-    await client.core.patchNamespace(name, ns, undefined, undefined, undefined, undefined, undefined, {
-      headers: { "Content-Type": "application/strategic-merge-patch+json" },
-    } as never);
-    return { created: false };
-  } catch (err: unknown) {
-    if (isNotFound(err)) {
-      await client.core.createNamespace(ns);
-      return { created: true };
-    }
-    throw err;
-  }
-}
-
-function isNotFound(err: unknown): boolean {
-  const code = (err as { response?: { statusCode?: number } })?.response?.statusCode;
-  return code === 404;
-}

packages/adapters/kubernetes-execution/src/orchestrator/naming.ts

@@ -1,54 +0,0 @@
-import { createHash } from "node:crypto";
-
-const DNS_1123_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
-const MAX_LABEL = 63;
-const HASH_LENGTH = 8;
-
-export function isValidDns1123Label(s: string): boolean {
-  return s.length > 0 && s.length <= MAX_LABEL && DNS_1123_LABEL.test(s);
-}
-
-function shortHash(input: string): string {
-  // base36 of first 5 bytes of sha256 → ≤8 chars, lowercase alphanumeric only.
-  const hash = createHash("sha256").update(input).digest();
-  let n = 0n;
-  for (let i = 0; i < 5; i++) n = (n << 8n) + BigInt(hash[i]);
-  return n.toString(36).slice(0, HASH_LENGTH).padStart(HASH_LENGTH, "0");
-}
-
-function sanitizeSlug(slug: string): string {
-  // Lowercase, replace runs of invalid chars with single hyphen, trim leading/trailing hyphens.
-  const cleaned = slug.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
-  return cleaned.length === 0 ? "x" : cleaned;
-}
-
-export interface DeriveNamespaceNameInput {
-  companySlug: string;
-  companyId: string;
-  prefix: string;
-}
-
-export function deriveNamespaceName(input: DeriveNamespaceNameInput): string {
-  const { companySlug, companyId, prefix } = input;
-  const slug = sanitizeSlug(companySlug);
-  // Always-hash: every namespace ends with `-<8-char-hash(companyId)>`. This
-  // guarantees globally-unique namespace names by construction, so two
-  // companies with identical slugs ("Acme" twice) cannot collide on the
-  // (cluster_connection_id, namespace_name) unique index in
-  // cluster_namespace_bindings. M3b Task 17 — replaces the M1 takeover
-  // guard, which only blocked the failure rather than preventing collision.
-  const suffix = `-${shortHash(companyId)}`;
-  const room = MAX_LABEL - prefix.length - suffix.length;
-  if (room <= 0) {
-    // Pathological: caller passed an absurdly long prefix (> 53 chars) such
-    // that prefix + suffix already meets or exceeds MAX_LABEL. Truncate the
-    // prefix and replace the slug with a single placeholder character so the
-    // result still fits MAX_LABEL. The companyId hash remains the unique
-    // discriminator. This branch is defensive — operators using the default
-    // "paperclip-" prefix (10 chars) never hit it.
-    const safePrefixLen = Math.max(0, MAX_LABEL - suffix.length - 1);
-    return `${prefix.slice(0, safePrefixLen)}x${suffix}`;
-  }
-  const truncatedSlug = slug.slice(0, room).replace(/-+$/g, "") || "x";
-  return `${prefix}${truncatedSlug}${suffix}`;
-}

packages/adapters/kubernetes-execution/src/orchestrator/network-policy.ts

@@ -1,118 +0,0 @@
-import type { V1NetworkPolicy } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import { tenantBaseLabels, PAPERCLIP_ROLE, ROLE_AGENT_RUNTIME } from "./labels.js";
-
-// IPv4-only private/internal ranges to exclude from the catch-all egress rule.
-// fd00::/8 (IPv6 ULA) is listed separately in RFC1918_IPV6_DENY because the
-// Kubernetes NetworkPolicy ipBlock.except entries must be a strict subset of
-// the parent cidr. Mixing IPv6 ranges inside an IPv4 cidr (0.0.0.0/0) is
-// rejected with a 422 by the k8s API.
-const RFC1918_IPV4_DENY = [
-  "10.0.0.0/8",
-  "172.16.0.0/12",
-  "192.168.0.0/16",
-  "169.254.0.0/16",   // link-local incl. cloud metadata
-  "100.64.0.0/10",    // CGNAT
-];
-
-const RFC1918_IPV6_DENY = [
-  "fd00::/8",         // IPv6 ULA
-];
-
-export interface BuildDefaultDenyInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-}
-
-export function buildDefaultDenyPolicies(input: BuildDefaultDenyInput): V1NetworkPolicy[] {
-  const labels = tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug });
-  return [
-    {
-      apiVersion: "networking.k8s.io/v1",
-      kind: "NetworkPolicy",
-      metadata: { name: "default-deny-ingress", namespace: input.namespace, labels },
-      spec: { podSelector: {}, policyTypes: ["Ingress"] },
-    },
-    {
-      apiVersion: "networking.k8s.io/v1",
-      kind: "NetworkPolicy",
-      metadata: { name: "default-deny-egress", namespace: input.namespace, labels },
-      spec: { podSelector: {}, policyTypes: ["Egress"] },
-    },
-  ];
-}
-
-export interface AgentEgressInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-  topology: "in-cluster" | "cross-cluster";
-  controlPlaneSelector: {
-    namespaceLabel: Record<string, string>;
-    podLabel: Record<string, string>;
-  } | null;
-}
-
-export function buildAgentEgressPolicy(input: AgentEgressInput): V1NetworkPolicy {
-  const labels = tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug });
-  const egress: NonNullable<V1NetworkPolicy["spec"]>["egress"] = [
-    // DNS
-    {
-      to: [{
-        namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": "kube-system" } },
-        podSelector:       { matchLabels: { "k8s-app": "kube-dns" } },
-      }],
-      ports: [{ port: 53, protocol: "UDP" }, { port: 53, protocol: "TCP" }],
-    },
-  ];
-
-  if (input.topology === "in-cluster" && input.controlPlaneSelector) {
-    egress.push({
-      to: [{
-        namespaceSelector: { matchLabels: input.controlPlaneSelector.namespaceLabel },
-        podSelector:       { matchLabels: input.controlPlaneSelector.podLabel },
-      }],
-      ports: [{ port: 443, protocol: "TCP" }, { port: 3102, protocol: "TCP" }],
-    });
-  }
-
-  // Internet egress — two ipBlock entries keep IPv4 and IPv6 CIDRs separate.
-  // The k8s API validates that each except entry is a strict subset of its
-  // parent cidr, so IPv6 ranges (fd00::/8) cannot live inside 0.0.0.0/0.
-  egress.push({
-    to: [
-      { ipBlock: { cidr: "0.0.0.0/0", except: RFC1918_IPV4_DENY } },
-      { ipBlock: { cidr: "::/0",       except: RFC1918_IPV6_DENY } },
-    ],
-    ports: [{ port: 443, protocol: "TCP" }],
-  });
-
-  return {
-    apiVersion: "networking.k8s.io/v1",
-    kind: "NetworkPolicy",
-    metadata: { name: "paperclip-agent-egress", namespace: input.namespace, labels },
-    spec: {
-      podSelector: { matchLabels: { [PAPERCLIP_ROLE]: ROLE_AGENT_RUNTIME } },
-      policyTypes: ["Egress"],
-      egress,
-    },
-  };
-}
-
-export async function applyNetworkPolicy(client: KubernetesApiClient, p: V1NetworkPolicy): Promise<void> {
-  const ns = p.metadata!.namespace!;
-  const name = p.metadata!.name!;
-  try {
-    await client.networking.readNamespacedNetworkPolicy(name, ns);
-    await client.networking.patchNamespacedNetworkPolicy(name, ns, p, undefined, undefined, undefined, undefined, undefined, {
-      headers: { "Content-Type": "application/strategic-merge-patch+json" },
-    } as never);
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) {
-      await client.networking.createNamespacedNetworkPolicy(ns, p);
-      return;
-    }
-    throw err;
-  }
-}

packages/adapters/kubernetes-execution/src/orchestrator/pvc.ts

@@ -1,62 +0,0 @@
-import type { V1PersistentVolumeClaim } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import {
-  tenantBaseLabels, PAPERCLIP_AGENT_ID, PAPERCLIP_ROLE, ROLE_AGENT_WORKSPACE,
-  PAPERCLIP_WORKSPACE_STRATEGY,
-} from "./labels.js";
-
-export interface BuildAgentWorkspacePvcInput {
-  namespace: string;
-  agentId: string;
-  agentSlug: string;
-  companyId: string;
-  companySlug: string;
-  storageClass: string;
-  sizeGi?: number;
-  strategyKey: string;
-}
-
-export function buildAgentWorkspacePvc(input: BuildAgentWorkspacePvcInput): V1PersistentVolumeClaim {
-  const sizeGi = input.sizeGi ?? 10;
-  return {
-    apiVersion: "v1",
-    kind: "PersistentVolumeClaim",
-    metadata: {
-      name: `agent-${input.agentSlug}-workspace`,
-      namespace: input.namespace,
-      labels: {
-        ...tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-        [PAPERCLIP_AGENT_ID]: input.agentId,
-        [PAPERCLIP_ROLE]: ROLE_AGENT_WORKSPACE,
-      },
-      annotations: {
-        [PAPERCLIP_WORKSPACE_STRATEGY]: input.strategyKey,
-        "paperclip.ai/created-at": new Date().toISOString(),
-      },
-    },
-    spec: {
-      accessModes: ["ReadWriteOnce"],
-      storageClassName: input.storageClass,
-      resources: { requests: { storage: `${sizeGi}Gi` } },
-    },
-  };
-}
-
-export async function applyAgentWorkspacePvc(
-  client: KubernetesApiClient, pvc: V1PersistentVolumeClaim,
-): Promise<{ existed: boolean }> {
-  const ns = pvc.metadata!.namespace!;
-  const name = pvc.metadata!.name!;
-  try {
-    await client.core.readNamespacedPersistentVolumeClaim(name, ns);
-    // PVC spec is immutable in critical fields (storage size CAN be expanded; class CAN'T change).
-    // We don't patch on subsequent runs — the existing PVC carries forward.
-    return { existed: true };
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) {
-      await client.core.createNamespacedPersistentVolumeClaim(ns, pvc);
-      return { existed: false };
-    }
-    throw err;
-  }
-}

packages/adapters/kubernetes-execution/src/orchestrator/rbac.ts

@@ -1,110 +0,0 @@
-import type { V1ServiceAccount, V1RoleBinding } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import { tenantBaseLabels } from "./labels.js";
-
-export interface BuildAgentServiceAccountInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-}
-
-export function buildAgentServiceAccount(input: BuildAgentServiceAccountInput): V1ServiceAccount {
-  return {
-    apiVersion: "v1",
-    kind: "ServiceAccount",
-    metadata: {
-      name: "paperclip-agent",
-      namespace: input.namespace,
-      labels: tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-    },
-    automountServiceAccountToken: false,
-  };
-}
-
-export interface BuildDriverRoleBindingInput {
-  namespace: string;
-  driverServiceAccount: { name: string; namespace: string };
-  clusterRoleName: string;
-  companyId: string;
-  companySlug: string;
-}
-
-export function buildDriverRoleBinding(input: BuildDriverRoleBindingInput): V1RoleBinding {
-  return {
-    apiVersion: "rbac.authorization.k8s.io/v1",
-    kind: "RoleBinding",
-    metadata: {
-      name: "paperclip-driver",
-      namespace: input.namespace,
-      labels: tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-    },
-    subjects: [{
-      kind: "ServiceAccount",
-      name: input.driverServiceAccount.name,
-      namespace: input.driverServiceAccount.namespace,
-    }],
-    roleRef: {
-      kind: "ClusterRole",
-      apiGroup: "rbac.authorization.k8s.io",
-      name: input.clusterRoleName,
-    },
-  };
-}
-
-export async function applyAgentServiceAccount(client: KubernetesApiClient, sa: V1ServiceAccount): Promise<void> {
-  const ns = sa.metadata!.namespace!;
-  const name = sa.metadata!.name!;
-  try {
-    await client.core.readNamespacedServiceAccount(name, ns);
-    await client.core.patchNamespacedServiceAccount(name, ns, sa, undefined, undefined, undefined, undefined, undefined, {
-      headers: { "Content-Type": "application/strategic-merge-patch+json" },
-    } as never);
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) {
-      await client.core.createNamespacedServiceAccount(ns, sa);
-      return;
-    }
-    throw err;
-  }
-}
-
-export async function applyDriverRoleBinding(client: KubernetesApiClient, rb: V1RoleBinding): Promise<void> {
-  const ns = rb.metadata!.namespace!;
-  const name = rb.metadata!.name!;
-  try {
-    const existing = await client.rbac.readNamespacedRoleBinding(name, ns);
-    const sameRoleRef =
-      existing.body.roleRef?.kind === rb.roleRef.kind &&
-      existing.body.roleRef?.name === rb.roleRef.name &&
-      existing.body.roleRef?.apiGroup === rb.roleRef.apiGroup;
-    if (sameRoleRef) {
-      // Idempotent path: roleRef hasn't changed (the common case for ensureTenant
-      // re-runs). RoleBinding subjects are mutable, so we patch in place — no
-      // delete window, no race where the namespace briefly has no permissions.
-      await client.rbac.patchNamespacedRoleBinding(name, ns, rb, undefined, undefined, undefined, undefined, undefined, {
-        headers: { "Content-Type": "application/strategic-merge-patch+json" },
-      } as never);
-      return;
-    }
-    // roleRef differs — k8s makes roleRef immutable, so we must delete+create.
-    // This is the rare path (only fires when an admin renames the bound ClusterRole).
-    // If the recreate fails, surface a descriptive error pointing at recovery so
-    // the operator knows the tenant has no driver permissions until ensureTenant re-runs.
-    await client.rbac.deleteNamespacedRoleBinding(name, ns);
-    try {
-      await client.rbac.createNamespacedRoleBinding(ns, rb);
-    } catch (createErr) {
-      throw new Error(
-        `RoleBinding ${name} in ${ns} was deleted to change roleRef, but the recreate failed: ` +
-          `${(createErr as Error).message}. ` +
-          `The tenant namespace currently has NO driver RoleBinding — re-run ensureTenant to recover.`,
-      );
-    }
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) {
-      await client.rbac.createNamespacedRoleBinding(ns, rb);
-      return;
-    }
-    throw err;
-  }
-}

packages/adapters/kubernetes-execution/src/orchestrator/resource-quota.ts

@@ -1,200 +0,0 @@
-import { ObjectSerializer, type V1ResourceQuota, type V1LimitRange } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import { tenantBaseLabels } from "./labels.js";
-
-export const defaultTenantQuota = {
-  requestsCpu: "16",
-  requestsMemory: "64Gi",
-  limitsCpu: "64",
-  limitsMemory: "256Gi",
-  requestsStorage: "200Gi",
-  countJobs: 100,
-  countPvcs: 50,
-  countSecrets: 200,
-  countConfigMaps: 200,
-} as const;
-
-export const defaultTenantLimits = {
-  default: { cpu: "1", memory: "2Gi" },
-  defaultRequest: { cpu: "250m", memory: "512Mi" },
-  max: { cpu: "8", memory: "32Gi" },
-  pvcMaxStorage: "20Gi",
-} as const;
-
-export interface QuotaOverride {
-  requestsCpu?: string;
-  requestsMemory?: string;
-  limitsCpu?: string;
-  limitsMemory?: string;
-  requestsStorage?: string;
-  countJobs?: number;
-  countPvcs?: number;
-  countSecrets?: number;
-  countConfigMaps?: number;
-}
-
-export interface LimitRangeOverride {
-  default?: { cpu?: string; memory?: string };
-  defaultRequest?: { cpu?: string; memory?: string };
-  max?: { cpu?: string; memory?: string };
-  pvcMaxStorage?: string;
-}
-
-export interface BuildQuotaInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-  override: QuotaOverride | null;
-}
-
-export function buildResourceQuota(input: BuildQuotaInput): V1ResourceQuota {
-  const o = { ...defaultTenantQuota, ...(input.override ?? {}) };
-  return {
-    apiVersion: "v1",
-    kind: "ResourceQuota",
-    metadata: {
-      name: "paperclip-tenant-quota",
-      namespace: input.namespace,
-      labels: tenantBaseLabels({
-        companyId: input.companyId,
-        companySlug: input.companySlug,
-      }),
-    },
-    spec: {
-      hard: {
-        "requests.cpu": o.requestsCpu,
-        "requests.memory": o.requestsMemory,
-        "limits.cpu": o.limitsCpu,
-        "limits.memory": o.limitsMemory,
-        "requests.storage": o.requestsStorage,
-        "count/jobs.batch": String(o.countJobs),
-        "count/persistentvolumeclaims": String(o.countPvcs),
-        "count/secrets": String(o.countSecrets),
-        "count/configmaps": String(o.countConfigMaps),
-      },
-    },
-  };
-}
-
-export interface BuildLimitRangeInput {
-  namespace: string;
-  companyId: string;
-  companySlug: string;
-  override: LimitRangeOverride | null;
-}
-
-export function buildLimitRange(input: BuildLimitRangeInput): V1LimitRange {
-  const o = {
-    default: { ...defaultTenantLimits.default, ...(input.override?.default ?? {}) },
-    defaultRequest: {
-      ...defaultTenantLimits.defaultRequest,
-      ...(input.override?.defaultRequest ?? {}),
-    },
-    max: { ...defaultTenantLimits.max, ...(input.override?.max ?? {}) },
-    pvcMaxStorage:
-      input.override?.pvcMaxStorage ?? defaultTenantLimits.pvcMaxStorage,
-  };
-  return {
-    apiVersion: "v1",
-    kind: "LimitRange",
-    metadata: {
-      name: "paperclip-tenant-limits",
-      namespace: input.namespace,
-      labels: tenantBaseLabels({
-        companyId: input.companyId,
-        companySlug: input.companySlug,
-      }),
-    },
-    spec: {
-      limits: [
-        {
-          type: "Container",
-          _default: o.default,
-          defaultRequest: o.defaultRequest,
-          max: o.max,
-        },
-        { type: "PersistentVolumeClaim", max: { storage: o.pvcMaxStorage } },
-      ],
-    },
-  };
-}
-
-function toLimitRangeWireBody(lr: V1LimitRange): V1LimitRange {
-  return ObjectSerializer.serialize(lr, "V1LimitRange") as V1LimitRange;
-}
-
-async function upsertNamespaced<
-  T extends { metadata?: { name?: string; namespace?: string } }
->(
-  obj: T,
-  read: (ns: string, name: string) => Promise<unknown>,
-  patch: (ns: string, name: string, body: T) => Promise<unknown>,
-  create: (ns: string, body: T) => Promise<unknown>,
-): Promise<void> {
-  const ns = obj.metadata!.namespace!;
-  const name = obj.metadata!.name!;
-  try {
-    await read(ns, name);
-    await patch(ns, name, obj);
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) {
-      await create(ns, obj);
-      return;
-    }
-    throw err;
-  }
-}
-
-export async function applyResourceQuota(
-  client: KubernetesApiClient,
-  q: V1ResourceQuota,
-): Promise<void> {
-  await upsertNamespaced(
-    q,
-    (ns, name) => client.core.readNamespacedResourceQuota(name, ns),
-    (ns, name, body) =>
-      client.core.patchNamespacedResourceQuota(
-        name,
-        ns,
-        body,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        {
-          headers: {
-            "Content-Type": "application/strategic-merge-patch+json",
-          },
-        } as never,
-      ),
-    (ns, body) => client.core.createNamespacedResourceQuota(ns, body),
-  );
-}
-
-export async function applyLimitRange(
-  client: KubernetesApiClient,
-  lr: V1LimitRange,
-): Promise<void> {
-  await upsertNamespaced(
-    lr,
-    (ns, name) => client.core.readNamespacedLimitRange(name, ns),
-    (ns, name, body) =>
-      client.core.patchNamespacedLimitRange(
-        name,
-        ns,
-        toLimitRangeWireBody(body),
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        undefined,
-        {
-          headers: {
-            "Content-Type": "application/strategic-merge-patch+json",
-          },
-        } as never,
-      ),
-    (ns, body) => client.core.createNamespacedLimitRange(ns, toLimitRangeWireBody(body)),
-  );
-}

packages/adapters/kubernetes-execution/src/orchestrator/run-id.ts

@@ -1,52 +0,0 @@
-import { randomBytes } from "node:crypto";
-
-/**
- * Crockford base32 — used by ULID for the timestamp + randomness encoding.
- * Excludes I, L, O, U so encoded IDs are unambiguous when read aloud.
- */
-const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
-
-function encodeBase32(bytes: Uint8Array, length: number): string {
-  let bits = 0n;
-  for (const b of bytes) bits = (bits << 8n) | BigInt(b);
-  // Pad/truncate to exactly `length` characters of 5-bit symbols.
-  const totalBits = BigInt(length * 5);
-  if (BigInt(bytes.length * 8) < totalBits) {
-    bits <<= totalBits - BigInt(bytes.length * 8);
-  } else if (BigInt(bytes.length * 8) > totalBits) {
-    bits >>= BigInt(bytes.length * 8) - totalBits;
-  }
-  const out: string[] = [];
-  for (let i = length - 1; i >= 0; i--) {
-    const idx = Number((bits >> BigInt(i * 5)) & 31n);
-    out.push(CROCKFORD[idx]);
-  }
-  return out.join("");
-}
-
-/**
- * Generate a ULID — 48-bit timestamp + 80-bit random, encoded as 26-char
- * Crockford base32. Lexicographically sortable by creation time.
- *
- * `now` is injectable for deterministic tests.
- */
-export function newRunUlid(now?: () => number): string {
-  const ts = (now ?? (() => Date.now()))();
-  const tsBytes = new Uint8Array(6);
-  let n = BigInt(ts);
-  for (let i = 5; i >= 0; i--) {
-    tsBytes[i] = Number(n & 0xffn);
-    n >>= 8n;
-  }
-  const tsPart = encodeBase32(tsBytes, 10);
-  const randomPart = encodeBase32(new Uint8Array(randomBytes(10)), 16);
-  return `${tsPart}${randomPart}`;
-}
-
-/**
- * Lowercased ULID for use in DNS-1123 names (Job/Secret names). K8s names
- * must be lowercase alphanumeric+hyphen so we lowercase the Crockford output.
- */
-export function newRunUlidDns(now?: () => number): string {
-  return newRunUlid(now).toLowerCase();
-}

packages/adapters/kubernetes-execution/src/orchestrator/secret.ts

@@ -1,107 +0,0 @@
-import type { V1Secret, V1OwnerReference } from "@kubernetes/client-node";
-import type { KubernetesApiClient } from "../types.js";
-import { tenantBaseLabels, PAPERCLIP_RUN_ID } from "./labels.js";
-
-export interface BuildEphemeralSecretInput {
-  namespace: string;
-  agentSlug: string;
-  runUlid: string;
-  companyId: string;
-  companySlug: string;
-  runId: string;
-  /** Plaintext key/value pairs to materialize. Will be base64-encoded. */
-  data: Record<string, string>;
-  /** OwnerReference to the Job so the Secret is auto-GC'd with TTL. */
-  ownerJob: { name: string; uid: string };
-}
-
-export function buildEphemeralSecret(input: BuildEphemeralSecretInput): V1Secret {
-  const ownerReferences: V1OwnerReference[] = [{
-    apiVersion: "batch/v1",
-    kind: "Job",
-    name: input.ownerJob.name,
-    uid: input.ownerJob.uid,
-    controller: true,
-    blockOwnerDeletion: true,
-  }];
-
-  const data: Record<string, string> = {};
-  for (const [k, v] of Object.entries(input.data)) {
-    data[k] = Buffer.from(v, "utf-8").toString("base64");
-  }
-
-  return {
-    apiVersion: "v1",
-    kind: "Secret",
-    type: "Opaque",
-    metadata: {
-      name: `agent-${input.agentSlug}-run-${input.runUlid}-env`,
-      namespace: input.namespace,
-      labels: {
-        ...tenantBaseLabels({ companyId: input.companyId, companySlug: input.companySlug }),
-        [PAPERCLIP_RUN_ID]: input.runId,
-      },
-      ownerReferences,
-    },
-    data,
-  };
-}
-
-/**
- * Apply the Secret. NOT idempotent on update — Secrets are created once per run and never updated.
- * If a Secret with the same name exists (collision impossible with ULIDs but defensive), this throws.
- */
-export async function applyEphemeralSecret(client: KubernetesApiClient, secret: V1Secret): Promise<void> {
-  const ns = secret.metadata!.namespace!;
-  await client.core.createNamespacedSecret(ns, secret);
-}
-
-/**
- * Best-effort delete used when Job creation fails AFTER Secret creation but BEFORE
- * the Job's OwnerReference is established.
- */
-export async function deleteEphemeralSecret(client: KubernetesApiClient, namespace: string, name: string): Promise<void> {
-  try {
-    await client.core.deleteNamespacedSecret(name, namespace);
-  } catch (err) {
-    if ((err as { response?: { statusCode?: number } })?.response?.statusCode === 404) return;
-    throw err;
-  }
-}
-
-/**
- * Patch an ephemeral Secret with an OwnerReference back to the owning Job.
- * Used by the two-phase commit flow in driver.run(): create Secret first
- * (no OwnerRef), create Job referencing the Secret, then patch the Secret
- * with OwnerRef pointing at the now-known Job UID. After the patch the
- * Secret is GC'd automatically when the Job is deleted (TTLSecondsAfterFinished
- * or Foreground delete).
- */
-export async function patchEphemeralSecretOwnerReference(
-  client: KubernetesApiClient,
-  namespace: string,
-  name: string,
-  ownerJob: { name: string; uid: string },
-): Promise<void> {
-  const patch = {
-    metadata: {
-      ownerReferences: [
-        {
-          apiVersion: "batch/v1",
-          kind: "Job",
-          name: ownerJob.name,
-          uid: ownerJob.uid,
-          controller: true,
-          blockOwnerDeletion: true,
-        },
-      ],
-    },
-  };
-  await client.core.patchNamespacedSecret(
-    name,
-    namespace,
-    patch,
-    undefined, undefined, undefined, undefined, undefined,
-    { headers: { "Content-Type": "application/strategic-merge-patch+json" } },
-  );
-}

packages/adapters/kubernetes-execution/src/redaction.ts

@@ -1,31 +0,0 @@
-export interface Redactor {
-  redact(input: string): string;
-  values(): readonly string[];
-}
-
-export function createRedactor(values: ReadonlyArray<string | undefined | null>): Redactor {
-  const set = new Set<string>();
-  for (const v of values) {
-    if (typeof v === "string" && v.length >= 8) set.add(v);
-  }
-  // Sort longest-first so we don't redact a substring before its enclosing string.
-  const sorted = [...set].sort((a, b) => b.length - a.length);
-  return {
-    values() { return sorted; },
-    redact(input: string) {
-      let out = input;
-      for (const v of sorted) {
-        if (v.length === 0) continue;
-        // Escape regex metacharacters
-        const pattern = new RegExp(v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
-        out = out.replace(pattern, "<redacted>");
-      }
-      return out;
-    },
-  };
-}
-
-export const noopRedactor: Redactor = {
-  redact: (s) => s,
-  values: () => [],
-};

packages/adapters/kubernetes-execution/src/types.ts

@@ -1,47 +0,0 @@
-import type {
-  CoreV1Api,
-  BatchV1Api,
-  NetworkingV1Api,
-  RbacAuthorizationV1Api,
-  ApiextensionsV1Api,
-} from "@kubernetes/client-node";
-
-export interface ResolvedClusterConnection {
-  id: string;
-  label: string;
-  kind: "in-cluster" | "kubeconfig";
-  /** Already resolved kubeconfig blob if kind === "kubeconfig". */
-  kubeconfigYaml?: string;
-  apiServerUrl?: string | null;
-  defaultNamespacePrefix: string;
-  paperclipPublicUrl?: string | null;
-  imageRegistry?: string | null;
-  allowAgentImageOverride: boolean;
-  /** Per-cluster image allow-list: image must string-start-with one of these prefixes. Empty = preserve M2 behavior (allowAgentImageOverride boolean alone governs). */
-  imageAllowlist: string[];
-  capabilities: ClusterCapabilities;
-}
-
-export interface ClusterCapabilities {
-  cilium: boolean;
-  storageClass: string;
-  architectures: ("amd64" | "arm64")[];
-}
-
-export interface KubernetesApiClient {
-  core: CoreV1Api;
-  batch: BatchV1Api;
-  networking: NetworkingV1Api;
-  rbac: RbacAuthorizationV1Api;
-  apiext: ApiextensionsV1Api;
-  /** kubeconfig context info for logging only. */
-  describe: () => string;
-  /** Throwaway dynamic client used for arbitrary CRDs (Cilium). */
-  request: <T = unknown>(method: string, path: string, body?: unknown) => Promise<T>;
-  /**
-   * Streaming variant of `request`. Returns the raw `Response` so the caller can
-   * drive `body.getReader()` for endpoints like `pods/log` and `events?watch=true`
-   * that emit chunked, line-delimited output. Auth is applied identically to `request`.
-   */
-  requestStream: (method: string, path: string, body?: unknown) => Promise<Response>;
-}

packages/adapters/kubernetes-execution/test/integration/_fixtures/test-repo/README.md

@@ -1,3 +0,0 @@
-# paperclip-claude-test
-
-A small test repo for claude-code integration.

packages/adapters/kubernetes-execution/test/integration/_harness.ts

@@ -1,31 +0,0 @@
-import { execSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-export interface KindCluster {
-  name: string;
-  kubeconfigPath: string;
-  kubeconfigYaml: string;
-  cleanup(): void;
-}
-
-export function spinUpKind(): KindCluster {
-  const name = `pp-test-${Math.random().toString(36).slice(2, 8)}`;
-  const dir = mkdtempSync(join(tmpdir(), `${name}-`));
-  const kubeconfigPath = join(dir, "kubeconfig");
-  // --wait waits for the control plane Pod to be Ready before returning.
-  execSync(`kind create cluster --name ${name} --kubeconfig ${kubeconfigPath} --wait 90s`, {
-    stdio: "inherit",
-  });
-  const kubeconfigYaml = readFileSync(kubeconfigPath, "utf-8");
-  return {
-    name,
-    kubeconfigPath,
-    kubeconfigYaml,
-    cleanup: () => {
-      try { execSync(`kind delete cluster --name ${name}`, { stdio: "ignore" }); } catch { /* swallow */ }
-      try { rmSync(dir, { recursive: true, force: true }); } catch { /* swallow */ }
-    },
-  };
-}

packages/adapters/kubernetes-execution/test/integration/_helpers/busybox-job.ts

@@ -1,129 +0,0 @@
-import type { V1Job } from "@kubernetes/client-node";
-
-/**
- * Test-only helper that builds a minimal Job spec for the lifecycle integration
- * test. It mirrors the security context, labels and volume layout of
- * `buildAgentJob()` (PSS Restricted, workspace + tmp + env volumes, no
- * automount of the SA token), but swaps the agent-runtime images for busybox
- * and overrides the entrypoints with simple shell scripts.
- *
- * Purpose: prove the WIRING (PVC mount, ephemeral Secret env, log stream,
- * lifecycle, terminal-state mapping) against a real cluster without requiring
- * the agent-runtime images to be built/published. The agent-shim contract is
- * validated by the unit tests on `buildAgentJob()` and by Task 26's end-to-end
- * test.
- */
-export interface BuildBusyboxTestJobInput {
-  namespace: string;
-  jobName: string;
-  pvcName: string;
-  envSecretName: string;
-  /** Override the main container's command. Defaults to a quick "hello" + exit 0. */
-  agentScript?: string;
-  /** Override the init container's command. Defaults to a no-op echo. */
-  initScript?: string;
-  activeDeadlineSeconds?: number;
-  /**
-   * Override the main container's image. Defaults to `busybox:1.36`. Used by
-   * the failure-modes test to inject a deliberately bogus image for the
-   * ImagePullBackOff case.
-   */
-  image?: string;
-  /**
-   * Override the init container's image. Defaults to `busybox:1.36`. Same
-   * rationale as `image` — lets the failure-modes test set a bogus init image
-   * if needed.
-   */
-  initImage?: string;
-  /**
-   * Override the main container's `resources.limits.memory`. Defaults to
-   * `64Mi`. Used by the OOMKilled test to drop the limit low enough that an
-   * intentional allocation overshoots it.
-   */
-  memoryLimit?: string;
-  /**
-   * Override the main container's `resources.limits.cpu`. Defaults to `200m`.
-   */
-  cpuLimit?: string;
-}
-
-export function buildBusyboxTestJob(input: BuildBusyboxTestJobInput): V1Job {
-  const restrictedSecurity = {
-    runAsNonRoot: true,
-    runAsUser: 1000,
-    runAsGroup: 1000,
-    fsGroup: 1000,
-    seccompProfile: { type: "RuntimeDefault" as const },
-  };
-  const containerSecurity = {
-    allowPrivilegeEscalation: false,
-    readOnlyRootFilesystem: true,
-    capabilities: { drop: ["ALL"] },
-  };
-
-  const labels = { "paperclip.ai/test": "busybox-lifecycle" };
-
-  return {
-    apiVersion: "batch/v1",
-    kind: "Job",
-    metadata: {
-      name: input.jobName,
-      namespace: input.namespace,
-      labels,
-    },
-    spec: {
-      backoffLimit: 0,
-      ttlSecondsAfterFinished: 30,
-      activeDeadlineSeconds: input.activeDeadlineSeconds ?? 60,
-      completions: 1,
-      parallelism: 1,
-      template: {
-        metadata: { labels },
-        spec: {
-          automountServiceAccountToken: false,
-          restartPolicy: "Never",
-          terminationGracePeriodSeconds: 5,
-          securityContext: restrictedSecurity,
-          initContainers: [{
-            name: "init",
-            image: input.initImage ?? "busybox:1.36",
-            command: ["sh", "-c", input.initScript ?? "ls -la /workspace; echo init-done"],
-            volumeMounts: [
-              { name: "workspace", mountPath: "/workspace" },
-              { name: "tmp", mountPath: "/tmp" },
-            ],
-            securityContext: containerSecurity,
-            resources: {
-              requests: { cpu: "50m", memory: "32Mi" },
-              limits: { cpu: "200m", memory: "64Mi" },
-            },
-          }],
-          containers: [{
-            name: "agent",
-            image: input.image ?? "busybox:1.36",
-            command: ["sh", "-c", input.agentScript ?? "echo hello from agent; sleep 1; exit 0"],
-            volumeMounts: [
-              { name: "workspace", mountPath: "/workspace" },
-              { name: "tmp", mountPath: "/tmp" },
-              { name: "env", mountPath: "/run/paperclip/env", readOnly: true },
-            ],
-            envFrom: [{ secretRef: { name: input.envSecretName } }],
-            securityContext: containerSecurity,
-            resources: {
-              requests: { cpu: "50m", memory: "32Mi" },
-              limits: {
-                cpu: input.cpuLimit ?? "200m",
-                memory: input.memoryLimit ?? "64Mi",
-              },
-            },
-          }],
-          volumes: [
-            { name: "workspace", persistentVolumeClaim: { claimName: input.pvcName } },
-            { name: "tmp", emptyDir: { sizeLimit: "64Mi" } },
-            { name: "env", secret: { secretName: input.envSecretName, defaultMode: 0o400 } },
-          ],
-        },
-      },
-    },
-  };
-}

packages/adapters/kubernetes-execution/test/integration/_helpers/cilium.ts

@@ -1,32 +0,0 @@
-import { execSync } from "node:child_process";
-
-/**
- * Installs Cilium into a kind cluster using the Cilium CLI. Requires
- * `cilium` on PATH (install via `brew install cilium-cli` or per the
- * Cilium docs).
- *
- * The kind cluster MUST have been started first via spinUpKind() in
- * _harness.ts; we just install Cilium on top.
- */
-export function installCilium(kubeconfigPath: string): void {
-  // Cilium 1.16+ ships a kind-friendly default; we don't override anything
-  // beyond enabling kubeProxyReplacement so kind's default kube-proxy is
-  // bypassed. The default node image (kind v0.24.0 → kindest/node:v1.31.x)
-  // works without further tuning.
-  execSync(
-    `cilium install --version 1.16.0 --set kubeProxyReplacement=true`,
-    { stdio: "inherit", env: { ...process.env, KUBECONFIG: kubeconfigPath } },
-  );
-}
-
-/**
- * Block until Cilium is fully Ready in the kind cluster. The CLI's
- * `cilium status --wait` polls cilium-operator + DaemonSet rollout and
- * exits 0 when everything is green.
- */
-export function waitForCiliumReady(kubeconfigPath: string): void {
-  execSync(
-    `cilium status --wait`,
-    { stdio: "inherit", env: { ...process.env, KUBECONFIG: kubeconfigPath } },
-  );
-}

packages/adapters/kubernetes-execution/test/integration/_helpers/fake-agent.Dockerfile

@@ -1,22 +0,0 @@
-# Test-only image for M2 Task 26's end-to-end test on kind.
-#
-# Scope reduction: this image stands in for `paperclipai/agent-runtime-claude`
-# during the integration test. It runs a busybox shell script that calls the
-# fake Anthropic server (see fake-anthropic.ts) and echoes the response. This
-# proves the FULL orchestrator + Job lifecycle + log streaming path without
-# needing a real claude-code CLI.
-#
-# Real claude-code integration is covered by Task 26.5 / M3 follow-up.
-FROM busybox:1.36
-
-# busybox's wget supports https only when built with TLS — we POST plain HTTP
-# to the host's fake server so this is fine.
-COPY fake-agent.sh /usr/local/bin/paperclip-agent-shim
-RUN chmod +x /usr/local/bin/paperclip-agent-shim
-
-# Match the runAsNonRoot / runAsUser=1000 PSS Restricted constraints that
-# buildBusyboxTestJob (and the real Job builder) enforce.
-USER 1000:1000
-WORKDIR /workspace
-
-ENTRYPOINT ["/usr/local/bin/paperclip-agent-shim"]

packages/adapters/kubernetes-execution/test/integration/_helpers/fake-agent.sh

@@ -1,47 +0,0 @@
-#!/bin/sh
-# Test-only fake "agent" used by M2 Task 26's end-to-end test.
-#
-# Simulates the agent-shim contract just enough to prove the FULL
-# orchestrator + Job lifecycle + log streaming path against a real kind
-# cluster, without depending on the real claude-code CLI.
-#
-# Real claude-code integration is covered by Task 26.5 / M3 follow-up; the
-# scope reduction is documented in claude-end-to-end.test.ts.
-#
-# Behavior:
-#   1. Sleep briefly so kind's pod networking + DNS settle (host.docker.internal
-#      resolution can be slow on first start).
-#   2. POST a minimal "messages" payload to ANTHROPIC_BASE_URL/v1/messages.
-#   3. Echo the response so the test can assert on it via pod logs.
-#   4. Exit 0 if the assistant text we expect appears, otherwise exit 1.
-set -eu
-
-URL="${ANTHROPIC_BASE_URL:-http://host.docker.internal:8080}/v1/messages"
-
-echo "[fake-agent] starting"
-echo "[fake-agent] ANTHROPIC_BASE_URL=${ANTHROPIC_BASE_URL:-<unset>}"
-
-# Give kind's networking a beat to settle (DNS rewriting for host.docker.internal
-# happens inside the kindnetd CNI; first resolution can take a couple of seconds).
-sleep 2
-
-echo "[fake-agent] POST $URL"
-RESP=$(wget -O- -q \
-  --header='content-type: application/json' \
-  --post-data='{"model":"claude-opus-4-7","messages":[{"role":"user","content":"hi"}]}' \
-  "$URL" 2>&1) || {
-  echo "[fake-agent] wget failed:"
-  echo "$RESP"
-  exit 1
-}
-
-echo "[fake-agent] response: $RESP"
-
-# Look for the deterministic marker the fake server returns.
-if echo "$RESP" | grep -q 'I read your prompt and I am alive'; then
-  echo "[fake-agent] success: assistant marker found"
-  exit 0
-fi
-
-echo "[fake-agent] failure: assistant marker not found"
-exit 1

packages/adapters/kubernetes-execution/test/integration/_helpers/fake-anthropic.ts

@@ -1,101 +0,0 @@
-import { createServer, type Server } from "node:http";
-import { networkInterfaces } from "node:os";
-
-/**
- * Minimal fake of Anthropic's `/v1/messages` endpoint for the M2 Task 26
- * end-to-end test. Listens on a random localhost port and returns a single
- * deterministic assistant message. Anything other than `POST /v1/messages`
- * returns 404.
- *
- * The returned `url` uses `host.docker.internal` so a Pod inside kind can
- * reach the host. On Docker Desktop (macOS/Windows) this DNS name resolves
- * automatically. On Linux CI you may need a kind cluster config that adds
- * `extraPortMappings` + `--add-host=host.docker.internal:host-gateway`. See
- * the test's docstring for the workaround.
- *
- * `urlForLinux` is a fallback used when `host.docker.internal` does not
- * resolve: it picks the first non-loopback IPv4 on the host.
- */
-export interface FakeAnthropic {
-  /** URL the in-cluster client should hit. Uses `host.docker.internal`. */
-  url: string;
-  /** The host's primary non-loopback IPv4 (Linux fallback). */
-  hostIp: string;
-  /** The bound port. */
-  port: number;
-  stop(): Promise<void>;
-}
-
-export interface StartFakeAnthropicOptions {
-  /** Override the assistant text returned. Default proves the round-trip. */
-  assistantText?: string;
-}
-
-const DEFAULT_TEXT = "I read your prompt and I am alive.";
-
-export async function startFakeAnthropic(
-  options: StartFakeAnthropicOptions = {},
-): Promise<FakeAnthropic> {
-  const text = options.assistantText ?? DEFAULT_TEXT;
-  return new Promise((resolve) => {
-    const server: Server = createServer((req, res) => {
-      if (req.method === "POST" && req.url === "/v1/messages") {
-        let body = "";
-        req.on("data", (c) => {
-          body += c;
-        });
-        req.on("end", () => {
-          try {
-            JSON.parse(body);
-          } catch {
-            res.writeHead(400, { "content-type": "application/json" });
-            res.end(JSON.stringify({ type: "error", error: { type: "invalid_request_error", message: "bad json" } }));
-            return;
-          }
-          res.writeHead(200, { "content-type": "application/json" });
-          res.end(
-            JSON.stringify({
-              id: "msg_test_01",
-              type: "message",
-              role: "assistant",
-              model: "claude-opus-4-7",
-              content: [{ type: "text", text }],
-              stop_reason: "end_turn",
-              stop_sequence: null,
-              usage: { input_tokens: 10, output_tokens: 8 },
-            }),
-          );
-        });
-      } else {
-        res.writeHead(404, { "content-type": "application/json" });
-        res.end(JSON.stringify({ type: "error", error: { type: "not_found_error", message: "not_found" } }));
-      }
-    });
-    // Bind 0.0.0.0 so kind's bridge network can reach us via host-gateway.
-    server.listen(0, "0.0.0.0", () => {
-      const addr = server.address() as { port: number };
-      const port = addr.port;
-      const hostIp = pickHostIp();
-      resolve({
-        url: `http://host.docker.internal:${port}`,
-        hostIp,
-        port,
-        stop: () =>
-          new Promise<void>((r) => {
-            server.close(() => r());
-          }),
-      });
-    });
-  });
-}
-
-function pickHostIp(): string {
-  const ifaces = networkInterfaces();
-  for (const list of Object.values(ifaces)) {
-    if (!list) continue;
-    for (const iface of list) {
-      if (iface.family === "IPv4" && !iface.internal) return iface.address;
-    }
-  }
-  return "127.0.0.1";
-}

packages/adapters/kubernetes-execution/test/integration/_helpers/metrics-server.ts

@@ -1,134 +0,0 @@
-import { execSync } from "node:child_process";
-
-/**
- * Test-only helper that bootstraps metrics-server inside a kind cluster.
- *
- * kind's kubelet uses a self-signed serving cert, so the upstream
- * metrics-server manifest needs to be patched with `--kubelet-insecure-tls`
- * before it can scrape kubelet stats. We apply the upstream manifest, patch
- * the deployment's container args, and poll `kubectl top nodes` until it
- * succeeds (typically 60-120s after the deployment becomes Ready).
- *
- * This is exercised by the empirical-measurement integration test (M2 Task 28
- * — Risk #4 partial resolution); production clusters are expected to have
- * metrics-server (or an equivalent metrics.k8s.io provider) installed by the
- * cluster operator, so the adapter itself does not depend on it.
- */
-
-const METRICS_SERVER_MANIFEST_URL =
-  "https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml";
-
-export function installMetricsServer(kubeconfigPath: string): void {
-  execSync(
-    `KUBECONFIG=${kubeconfigPath} kubectl apply -f ${METRICS_SERVER_MANIFEST_URL}`,
-    { stdio: "inherit" },
-  );
-
-  // Patch the deployment to add `--kubelet-insecure-tls`. The upstream
-  // manifest's args are written as a single container; we replace them
-  // wholesale via a strategic-merge patch keyed on container name.
-  const patch = JSON.stringify({
-    spec: {
-      template: {
-        spec: {
-          containers: [
-            {
-              name: "metrics-server",
-              args: [
-                "--cert-dir=/tmp",
-                "--secure-port=10250",
-                "--kubelet-preferred-address-types=InternalIP,ExternalIP,Hostname",
-                "--kubelet-insecure-tls",
-                "--kubelet-use-node-status-port",
-                "--metric-resolution=15s",
-              ],
-            },
-          ],
-        },
-      },
-    },
-  });
-
-  execSync(
-    `KUBECONFIG=${kubeconfigPath} kubectl -n kube-system patch deployment metrics-server --type=strategic --patch='${patch}'`,
-    { stdio: "inherit" },
-  );
-}
-
-export async function waitForMetricsServerReady(
-  kubeconfigPath: string,
-  timeoutMs = 180_000,
-): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      // `kubectl top nodes` is a thin wrapper over the metrics.k8s.io API; if
-      // it returns a non-empty table the APIService is healthy and the scrape
-      // pipeline has produced at least one sample. Suppress stderr (the API
-      // returns 503 "metrics not available yet" for the first ~60s).
-      const out = execSync(
-        `KUBECONFIG=${kubeconfigPath} kubectl top nodes --no-headers 2>/dev/null`,
-        { encoding: "utf-8" },
-      );
-      if (out.trim().length > 0) return;
-    } catch {
-      /* not ready yet */
-    }
-    await new Promise((r) => setTimeout(r, 3000));
-  }
-  throw new Error("metrics-server did not become ready in time");
-}
-
-export interface PodMetricSample {
-  name: string;
-  cpuMillicores: number;
-  memoryMi: number;
-}
-
-/**
- * Reads the current pod metrics in a namespace by parsing `kubectl top pod`
- * stdout. We deliberately avoid wiring the metrics.k8s.io client (it would
- * require an extra `@kubernetes/client-node` API constructor and custom URL
- * handling) — the parsing surface here is small and fully under test control.
- *
- * Throws on any execSync failure; callers should guard with try/catch
- * because metrics-server can briefly 503 between scrapes.
- */
-export function readPodMetrics(
-  namespace: string,
-  kubeconfigPath: string,
-): PodMetricSample[] {
-  const out = execSync(
-    `KUBECONFIG=${kubeconfigPath} kubectl top pod -n ${namespace} --no-headers --containers=false`,
-    { encoding: "utf-8" },
-  );
-  const lines = out.trim().split("\n").filter(Boolean);
-  return lines.map((line) => {
-    const cols = line.split(/\s+/).filter(Boolean);
-    // Expected layout: NAME  CPU(cores)  MEMORY(bytes)
-    const [name, cpu, mem] = cols;
-    return {
-      name,
-      cpuMillicores: parseCpuMillicores(cpu),
-      memoryMi: parseMemoryMi(mem),
-    };
-  });
-}
-
-function parseCpuMillicores(value: string | undefined): number {
-  if (!value) return 0;
-  if (value.endsWith("m")) return parseInt(value.slice(0, -1), 10) || 0;
-  // Bare integer means whole cores.
-  const n = parseFloat(value);
-  return Number.isFinite(n) ? Math.round(n * 1000) : 0;
-}
-
-function parseMemoryMi(value: string | undefined): number {
-  if (!value) return 0;
-  if (value.endsWith("Mi")) return parseInt(value.slice(0, -2), 10) || 0;
-  if (value.endsWith("Ki")) return Math.round((parseInt(value.slice(0, -2), 10) || 0) / 1024);
-  if (value.endsWith("Gi")) return (parseInt(value.slice(0, -2), 10) || 0) * 1024;
-  // Bare bytes fallback.
-  const n = parseInt(value, 10);
-  return Number.isFinite(n) ? Math.round(n / 1024 / 1024) : 0;
-}

packages/adapters/kubernetes-execution/test/integration/_helpers/seed-workspace.ts

@@ -1,70 +0,0 @@
-import { execSync } from "node:child_process";
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-
-/**
- * Populate a PVC with a fixture directory by spinning a one-shot Pod that
- * `git init && cp -r /fixtures/* . && git add . && git commit`. The fixture
- * is delivered to the Pod via a ConfigMap (small repos only — KB scale).
- */
-export async function seedWorkspaceFromFixture(input: {
-  kubeconfigPath: string;
-  namespace: string;
-  pvcName: string;
-  fixtureDir: string;          // local path to copy
-  podName?: string;
-}): Promise<void> {
-  const podName = input.podName ?? "seed-workspace";
-
-  // 1. Pack the fixture into a ConfigMap. ConfigMaps support up to 1Mi.
-  const tmp = mkdtempSync(join(tmpdir(), "paperclip-fixture-"));
-  const archive = join(tmp, "fixture.tar.gz");
-  execSync(`tar -czf ${archive} -C ${input.fixtureDir} .`, { stdio: "inherit" });
-  execSync(
-    `kubectl --kubeconfig ${input.kubeconfigPath} -n ${input.namespace} create configmap fixture-tar --from-file=fixture.tar.gz=${archive} --dry-run=client -o yaml | kubectl --kubeconfig ${input.kubeconfigPath} apply -f -`,
-    { stdio: "inherit" },
-  );
-
-  // 2. Run a one-shot Pod that unpacks the tar into the PVC + git inits.
-  const podYaml = `
-apiVersion: v1
-kind: Pod
-metadata:
-  name: ${podName}
-  namespace: ${input.namespace}
-spec:
-  restartPolicy: Never
-  containers:
-    - name: seed
-      image: alpine/git:2.45.0
-      command: ["sh", "-euxc"]
-      args:
-        - |
-          mkdir -p /workspace
-          cd /workspace
-          tar -xzf /fixture/fixture.tar.gz
-          git init -b main
-          git -c user.email=seed@local -c user.name=seed add .
-          git -c user.email=seed@local -c user.name=seed commit -m "init"
-      volumeMounts:
-        - name: workspace
-          mountPath: /workspace
-        - name: fixture
-          mountPath: /fixture
-  volumes:
-    - name: workspace
-      persistentVolumeClaim:
-        claimName: ${input.pvcName}
-    - name: fixture
-      configMap:
-        name: fixture-tar
-`;
-  const yamlFile = join(tmp, "pod.yaml");
-  writeFileSync(yamlFile, podYaml);
-  execSync(`kubectl --kubeconfig ${input.kubeconfigPath} apply -f ${yamlFile}`, { stdio: "inherit" });
-  execSync(
-    `kubectl --kubeconfig ${input.kubeconfigPath} wait --for=condition=Ready=false --for=jsonpath='{.status.phase}'=Succeeded pod/${podName} -n ${input.namespace} --timeout=120s`,
-    { stdio: "inherit" },
-  );
-}

packages/adapters/kubernetes-execution/test/integration/acpx-smoke.test.ts

@@ -1,93 +0,0 @@
-import { execSync } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createKubernetesApiClient } from "../../src/index.js";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-/**
- * M3b Task 11: smoke test for the `agent-runtime-acpx` runtime image.
- *
- * Scope: prove that the freshly built image:
- *   - boots in a kind cluster
- *   - has the `acpx` CLI on PATH (matching the shim's exec.LookPath contract)
- *
- * This is intentionally a thin probe — it does NOT exercise the full driver
- * orchestration (covered by claude-end-to-end.test.ts and the unit tests on
- * driver.run()) nor the real Anthropic / OpenAI APIs (which would require
- * live keys). ACPX bridges Claude (ANTHROPIC_API_KEY) and Codex
- * (OPENAI_API_KEY) backends.
- *
- * Gated on K8S_INTEGRATION so contributors without docker + kind on PATH can
- * still run the full unit suite.
- */
-describe.skipIf(!process.env["K8S_INTEGRATION"])(
-  "acpx_local runtime image smoke",
-  () => {
-    let kind: KindCluster;
-    const IMAGE = "paperclipai/agent-runtime-acpx:test-m3b";
-
-    beforeAll(() => {
-      kind = spinUpKind();
-      const repoRoot = path.resolve(__dirname, "../../../../..");
-      // Build base + acpx into the local docker daemon, then load into kind.
-      execSync(
-        `docker buildx bake --file ${repoRoot}/docker/agent-runtime/buildx-bake.hcl --set "base.tags=paperclipai/agent-runtime-base:test-m3b" --set "acpx.tags=${IMAGE}" --set "*.platforms=linux/amd64" base acpx`,
-        { cwd: repoRoot, stdio: "inherit" },
-      );
-      execSync(`kind load docker-image ${IMAGE} --name ${kind.name}`, {
-        stdio: "inherit",
-      });
-    }, 600_000);
-
-    afterAll(() => kind?.cleanup());
-
-    it("the agent-runtime-acpx image boots and `acpx` is on PATH", () => {
-      // Construct the API client purely to assert the connection shape this
-      // package exports remains compatible with acpx_local runtime usage.
-      // The actual probe is a kubectl-driven Pod since the smoke test does
-      // not need the full orchestrator path.
-      createKubernetesApiClient({
-        id: "c-1",
-        label: "kind",
-        kind: "kubeconfig",
-        kubeconfigYaml: kind.kubeconfigYaml,
-        defaultNamespacePrefix: "paperclip-",
-        allowAgentImageOverride: false,
-        imageAllowlist: [],
-        capabilities: {
-          cilium: false,
-          storageClass: "standard",
-          architectures: ["amd64"],
-        },
-      });
-
-      const podYaml = `apiVersion: v1
-kind: Pod
-metadata:
-  name: acpx-probe
-  namespace: default
-spec:
-  restartPolicy: Never
-  containers:
-    - name: c
-      image: ${IMAGE}
-      imagePullPolicy: IfNotPresent
-      command: ["sh", "-c", "command -v acpx && echo ACPX_OK"]
-`;
-      const env = { ...process.env, KUBECONFIG: kind.kubeconfigPath };
-      execSync(`kubectl apply -f - <<'EOF'\n${podYaml}\nEOF`, {
-        env,
-        shell: "/bin/bash",
-      });
-      execSync(
-        `kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/acpx-probe --timeout=120s`,
-        { env },
-      );
-      const logs = execSync(`kubectl logs pod/acpx-probe`, { env }).toString();
-      expect(logs).toContain("ACPX_OK");
-    }, 600_000);
-  },
-);

packages/adapters/kubernetes-execution/test/integration/cilium-tenant-policy.test.ts

@@ -1,119 +0,0 @@
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { exec as execCb } from "node:child_process";
-import { promisify } from "node:util";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-import { installCilium, waitForCiliumReady } from "./_helpers/cilium.js";
-import {
-  createKubernetesApiClient,
-  ensureTenantNamespace,
-  type ResolvedClusterConnection,
-} from "../../src/index.js";
-
-const exec = promisify(execCb);
-
-/**
- * M3a Task 9: kind+Cilium integration test for the per-tenant Cilium DSL.
- *
- * Requires the Cilium CLI on PATH (`brew install cilium-cli` or per
- * https://docs.cilium.io/en/stable/gettingstarted/k8s-install-default/#install-the-cilium-cli).
- *
- * Opt-in via two env vars: K8S_INTEGRATION (gates all kind tests in this
- * suite) AND K8S_CILIUM_INTEGRATION (gates the slow Cilium-installing
- * tests specifically). The full run takes ~3–5 minutes on a warm Docker
- * layer cache.
- */
-
-describe.skipIf(!process.env["K8S_INTEGRATION"] || !process.env["K8S_CILIUM_INTEGRATION"])(
-  "tenant Cilium DSL on kind+Cilium",
-  () => {
-    let kind: KindCluster;
-    let connection: ResolvedClusterConnection;
-
-    beforeAll(async () => {
-      kind = spinUpKind();
-      installCilium(kind.kubeconfigPath);
-      waitForCiliumReady(kind.kubeconfigPath);
-      connection = {
-        id: "c-1", label: "kind-cilium", kind: "kubeconfig",
-        kubeconfigYaml: kind.kubeconfigYaml,
-        defaultNamespacePrefix: "paperclip-",
-        allowAgentImageOverride: false,
-        capabilities: { cilium: true, storageClass: "standard", architectures: ["amd64"] },
-      };
-    }, 600_000);
-
-    afterAll(() => kind?.cleanup());
-
-    it(
-      "blocks egress to a host not in dnsAllowlist while permitting one that is",
-      async () => {
-        const client = createKubernetesApiClient(connection);
-        // Always-hash namespace shape (M3b Task 17): the actual namespace is
-        // paperclip-<slug>-<8-char-hash(companyId)>, so capture it from the
-        // ensureTenantNamespace return value rather than hardcoding.
-        const ensure = await ensureTenantNamespace(client, {
-          connection,
-          company: { id: "11111111-1111-1111-1111-111111111111", slug: "acme" },
-          tenantPolicy: {
-            quota: null, limitRange: null,
-            additionalAllowFqdns: [],
-            imageOverrides: null,
-            ciliumDnsAllowlist: ["example.com"],
-            ciliumEgressCidrs: [],
-          },
-          driverServiceAccount: { name: "default", namespace: "default" },
-          controlPlane: { topology: "cross-cluster", namespaceLabels: {}, podLabels: {} },
-          adapterAllowFqdns: [],
-          imagePullDockerConfigJson: null,
-        });
-        const ns = ensure.namespace;
-
-        // Wait for Cilium to ingest both CNPs (the M1 baseline + the M3a restrict).
-        await new Promise((r) => setTimeout(r, 3000));
-
-        // Run a probe pod with the agent label so it matches both CNPs'
-        // endpointSelector (paperclip.ai/managed-by: paperclip).
-        const probeYaml = `apiVersion: v1
-kind: Pod
-metadata:
-  name: probe
-  namespace: ${ns}
-  labels:
-    paperclip.ai/managed-by: paperclip
-    paperclip.ai/role: agent-runtime
-spec:
-  containers:
-    - name: c
-      image: curlimages/curl:8.10.1
-      command: ["sh", "-c", "sleep 3600"]
-`;
-        const env = { ...process.env, KUBECONFIG: kind.kubeconfigPath };
-        await exec(`kubectl apply -f - <<'EOF'
-${probeYaml}
-EOF`, { env, shell: "/bin/bash" });
-        await exec(`kubectl wait --for=condition=Ready pod/probe -n ${ns} --timeout=60s`, { env });
-
-        // Allowed: example.com (in dnsAllowlist).
-        const allowed = await exec(
-          `kubectl exec -n ${ns} probe -- ` +
-          `curl -sS -m 8 -o /dev/null -w "%{http_code}" https://example.com`,
-          { env },
-        ).catch((e) => ({ stdout: "ERR", stderr: String(e) }));
-        // 200/301/302 etc. all acceptable — what matters is the connection succeeded.
-        expect(allowed.stdout.trim()).toMatch(/^(2..|3..)$/);
-
-        // Blocked: github.com (not in dnsAllowlist; the second CNP intersects
-        // the M1 baseline down to "kube-dns + example.com" only).
-        const blocked = await exec(
-          `kubectl exec -n ${ns} probe -- ` +
-          `curl -sS -m 8 -o /dev/null -w "%{http_code}" https://github.com`,
-          { env },
-        ).catch((e) => ({ stdout: "ERR", stderr: String(e) }));
-        // Cilium drops the connection: curl exits non-zero (catch path) OR
-        // returns "000" (no HTTP response received).
-        expect(blocked.stdout === "ERR" || blocked.stdout.trim() === "000").toBe(true);
-      },
-      300_000,
-    );
-  },
-);

packages/adapters/kubernetes-execution/test/integration/claude-code-real.test.ts

@@ -1,241 +0,0 @@
-/**
- * M3a Task 13: Real claude-code on kind, gated on K8S_INTEGRATION + ANTHROPIC_API_KEY.
- *
- * DONE_WITH_CONCERNS notes:
- *
- * 1. workspaceStrategyJson — The init container reads PAPERCLIP_WORKSPACE_REQUEST.
- *    We pass `{"version":1,"source":{"strategy":"noop"}}` under the assumption the
- *    workspace-init binary accepts a "noop" source strategy (i.e. does nothing and
- *    treats the already-populated PVC as the workspace). If the init image requires
- *    a different strategy key or schema version, the init container will exit
- *    non-zero and the pod will fail before claude-code even starts. Adjust
- *    workspaceStrategyJson to match the contract the real workspace-init binary
- *    expects, or use imageOverride on the target to skip the init container.
- *
- * 2. Bootstrap token exchange — The shim exchanges the minted token via
- *    POST PAPERCLIP_PUBLIC_URL/api/agent-auth/exchange. We pass
- *    "http://example.invalid" which will cause the exchange to fail immediately.
- *    Whether this terminates the process before claude-code runs depends on the
- *    shim's error-handling. If the shim is strict (exits on exchange failure),
- *    the run will exit non-zero. In that case: either run a real control-plane
- *    reachable from the kind node, or modify the shim to accept a
- *    PAPERCLIP_SKIP_AUTH_EXCHANGE env var (a test-only escape hatch).
- *
- * 3. PVC pre-population — We seed the workspace before driver.run() via
- *    seedWorkspaceFromFixture. The driver also calls applyAgentWorkspacePvc
- *    (idempotent), so the PVC must not be bound to a different StorageClass. We
- *    pass storageClassName: "standard" in resolveRunContext to match kind's default.
- *
- * Manual run procedure (once K8S_INTEGRATION + ANTHROPIC_API_KEY are available):
- *
- *   K8S_INTEGRATION=1 ANTHROPIC_API_KEY=sk-ant-... \
- *     pnpm --filter @paperclipai/execution-target-kubernetes exec \
- *     vitest run test/integration/claude-code-real.test.ts
- *
- * Expected: PASS in ~3–5 minutes (kind boot ~90s + image load ~60s + agent run).
- * Cost: ~$0.01–0.05 per run.
- */
-
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { execSync } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-import { seedWorkspaceFromFixture } from "./_helpers/seed-workspace.js";
-import {
-  createKubernetesApiClient,
-  createKubernetesExecutionDriver,
-  ensureTenantNamespace,
-  type ResolvedClusterConnection,
-} from "../../src/index.js";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const REAL_CLAUDE_IMAGE =
-  process.env["AGENT_CLAUDE_REAL_IMAGE"] ?? "paperclipai/agent-runtime-claude:test-m3a";
-const BASE_IMAGE =
-  process.env["AGENT_BASE_IMAGE"] ?? "paperclipai/agent-runtime-base:test-m3a";
-
-const COMPANY_ID = "55555555-5555-5555-5555-555555555556";
-const COMPANY_SLUG = "claudereal";
-const AGENT_ID = "66666666-6666-6666-6666-666666666667";
-const CONNECTION_ID = "c-real-1";
-
-describe.skipIf(!process.env["K8S_INTEGRATION"] || !process.env["ANTHROPIC_API_KEY"])(
-  "real claude-code on kind",
-  () => {
-    let kind: KindCluster;
-    let connection: ResolvedClusterConnection;
-
-    beforeAll(async () => {
-      kind = spinUpKind();
-
-      // Build agent-runtime-base + agent-runtime-claude and load both into kind.
-      const repoRoot = path.resolve(__dirname, "../../../../..");
-      // eslint-disable-next-line no-console
-      console.log("[claude-code-real] building agent-runtime-base...");
-      execSync(
-        `docker build -t ${BASE_IMAGE} -f docker/agent-runtime/base/Dockerfile docker/agent-runtime/base`,
-        { cwd: repoRoot, stdio: "inherit" },
-      );
-      // eslint-disable-next-line no-console
-      console.log("[claude-code-real] building agent-runtime-claude...");
-      execSync(
-        `docker build -t ${REAL_CLAUDE_IMAGE} -f docker/agent-runtime/claude/Dockerfile docker/agent-runtime/claude`,
-        { cwd: repoRoot, stdio: "inherit" },
-      );
-      // eslint-disable-next-line no-console
-      console.log("[claude-code-real] loading images into kind...");
-      execSync(`kind load docker-image ${BASE_IMAGE} --name ${kind.name}`, { stdio: "inherit" });
-      execSync(`kind load docker-image ${REAL_CLAUDE_IMAGE} --name ${kind.name}`, { stdio: "inherit" });
-
-      connection = {
-        id: CONNECTION_ID,
-        label: "kind-real",
-        kind: "kubeconfig",
-        kubeconfigYaml: kind.kubeconfigYaml,
-        defaultNamespacePrefix: "paperclip-",
-        allowAgentImageOverride: false,
-        capabilities: {
-          cilium: false,
-          storageClass: "standard",
-          architectures: ["amd64", "arm64"],
-        },
-      };
-    }, 900_000);
-
-    afterAll(() => kind?.cleanup());
-
-    it(
-      "reads README.md via tool-use and surfaces the project name in logs",
-      async () => {
-        const client = createKubernetesApiClient(connection);
-
-        // 1. Ensure tenant namespace.
-        const ensure = await ensureTenantNamespace(client, {
-          connection,
-          company: { id: COMPANY_ID, slug: COMPANY_SLUG },
-          tenantPolicy: null,
-          driverServiceAccount: { name: "default", namespace: "default" },
-          controlPlane: {
-            topology: "cross-cluster",
-            namespaceLabels: {},
-            podLabels: {},
-          },
-          adapterAllowFqdns: ["api.anthropic.com"],
-          imagePullDockerConfigJson: null,
-        });
-        const namespace = ensure.namespace;
-        // Always-hash namespace shape: paperclip-<slug>-<8-char-hash(companyId)>.
-        // See M3b Task 17 / orchestrator/naming.ts for the rationale.
-        expect(namespace).toMatch(new RegExp(`^paperclip-${COMPANY_SLUG}-[0-9a-z]{8}$`));
-
-        // 2. Apply PVC (driver will also call applyAgentWorkspacePvc, which is
-        //    idempotent; we apply it first so seedWorkspaceFromFixture can bind it).
-        execSync(
-          [
-            `kubectl --kubeconfig ${kind.kubeconfigPath}`,
-            `-n ${namespace} apply -f -`,
-          ].join(" "),
-          {
-            input: [
-              "apiVersion: v1",
-              "kind: PersistentVolumeClaim",
-              "metadata:",
-              "  name: agent-claudereal-workspace",
-              `  namespace: ${namespace}`,
-              "spec:",
-              "  accessModes: [ReadWriteOnce]",
-              "  resources:",
-              "    requests:",
-              "      storage: 1Gi",
-              "  storageClassName: standard",
-            ].join("\n"),
-            stdio: ["pipe", "inherit", "inherit"],
-          },
-        );
-
-        // 3. Seed the workspace with the fixture repo.
-        await seedWorkspaceFromFixture({
-          kubeconfigPath: kind.kubeconfigPath,
-          namespace,
-          pvcName: "agent-claudereal-workspace",
-          fixtureDir: path.resolve(__dirname, "_fixtures/test-repo"),
-        });
-
-        // 4. Collect logs via onLog callback (AdapterExecutionResult has no logs field).
-        const collectedLogs: string[] = [];
-
-        // 5. Wire up the driver.
-        const driver = createKubernetesExecutionDriver({
-          resolveConnection: async (id) => {
-            if (id === CONNECTION_ID) return connection;
-            return null;
-          },
-          bootstrapTokenMinter: {
-            mint: async () => ({
-              token: "bst_test_unused",
-              expiresAt: new Date(Date.now() + 600_000),
-            }),
-          },
-          resolveRunContext: async () => ({
-            companySlug: COMPANY_SLUG,
-            image: REAL_CLAUDE_IMAGE,
-            initImage: BASE_IMAGE,
-            paperclipPublicUrl: "http://example.invalid",
-            workspaceStrategyJson: JSON.stringify({ version: 1, source: { strategy: "noop" } }),
-            workspaceStrategyKey: "claudereal-noop",
-            storageClassName: "standard",
-            storageSizeGi: 1,
-            adapterEnv: {
-              ANTHROPIC_API_KEY: process.env["ANTHROPIC_API_KEY"]!,
-            },
-          }),
-          pollIntervalMs: 2000,
-        });
-
-        // 6. Run the driver.
-        const result = await driver.run({
-          ctx: {
-            runId: "r-real-1",
-            agent: {
-              id: AGENT_ID,
-              companyId: COMPANY_ID,
-              name: "real-claude-test-agent",
-              adapterType: "claude_local",
-              adapterConfig: {},
-            },
-            runtime: {
-              sessionId: null,
-              sessionParams: null,
-              sessionDisplayId: null,
-              taskKey: null,
-            },
-            config: {},
-            context: {},
-            onLog: async (_stream, chunk) => {
-              collectedLogs.push(chunk);
-            },
-          },
-          target: {
-            kind: "kubernetes",
-            clusterConnectionId: CONNECTION_ID,
-          },
-        });
-
-        // 7. Assertions.
-        const joinedLogs = collectedLogs.join("\n");
-        if (result.exitCode !== 0) {
-          // eslint-disable-next-line no-console
-          console.warn("[claude-code-real] non-zero exit. result:", result, "\nlogs:\n", joinedLogs);
-        }
-        expect(result.exitCode, `expected exit 0; logs:\n${joinedLogs}`).toBe(0);
-        expect(
-          joinedLogs.toLowerCase(),
-          "expected 'paperclip-claude-test' in pod logs",
-        ).toContain("paperclip-claude-test");
-      },
-      900_000,
-    );
-  },
-);

packages/adapters/kubernetes-execution/test/integration/claude-end-to-end.test.ts

@@ -1,351 +0,0 @@
-import { execFile } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-import type { V1Job, V1Pod } from "@kubernetes/client-node";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import {
-  createKubernetesApiClient,
-  ensureTenantNamespace,
-  type ResolvedClusterConnection,
-} from "../../src/index.js";
-import { mapTerminalState } from "../../src/orchestrator/failure-mapping.js";
-import { startLogStream } from "../../src/orchestrator/log-stream.js";
-import {
-  applyAgentWorkspacePvc,
-  buildAgentWorkspacePvc,
-} from "../../src/orchestrator/pvc.js";
-import {
-  applyEphemeralSecret,
-  buildEphemeralSecret,
-  patchEphemeralSecretOwnerReference,
-} from "../../src/orchestrator/secret.js";
-import type { KubernetesApiClient } from "../../src/types.js";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-import { buildBusyboxTestJob } from "./_helpers/busybox-job.js";
-import {
-  startFakeAnthropic,
-  type FakeAnthropic,
-} from "./_helpers/fake-anthropic.js";
-
-const exec = promisify(execFile);
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-/**
- * M2 Task 26: end-to-end integration test for the claude_local execution
- * path on a real kind cluster.
- *
- * Scope reduction (documented intentionally):
- *
- *   This test does NOT exercise the real `@anthropic-ai/claude-code` CLI nor
- *   the `paperclipai/agent-runtime-claude` image. Both are too heavy/coupled
- *   to integrate cleanly here:
- *     - claude-code expects a structurally valid Anthropic protocol response
- *       and a working API key flow.
- *     - The runtime image's workspace-init runs first and would need the
- *       paperclip control-plane reachable from the pod (via PAPERCLIP_PUBLIC_URL
- *       pointing at host.docker.internal) plus a real bootstrap token exchange.
- *
- *   Building all of that just for this test would balloon scope without
- *   strengthening the M2 acceptance criteria. Real claude-code integration is
- *   deferred to a Task 26.5 / M3 follow-up.
- *
- * What this test PROVES:
- *   - The FULL Job lifecycle on kind: PVC + Secret + Job, scheduled, runs,
- *     terminates, log stream surfaces stdout, mapTerminalState reports success.
- *   - The agent container can reach an HTTP server running on the host via
- *     `host.docker.internal` (the wiring claude-local needs for ANTHROPIC_BASE_URL
- *     overrides during tests/dev).
- *   - The fake-agent's POST round-trip to `/v1/messages` works end-to-end.
- *
- * What this test does NOT exercise (and where it IS covered):
- *   - The real claude-code CLI: deferred to Task 26.5 / M3.
- *   - The agent-shim → workspace-init → exchange flow: covered by unit tests
- *     on `buildAgentJob()` and the bootstrap-token service.
- *   - The `KubernetesExecutionDriver.run()` orchestration: covered by
- *     `driver-run.test.ts` (unit) and exercised here by re-using the same
- *     orchestrator helpers (ensureTenantNamespace, applyEphemeralSecret,
- *     applyAgentWorkspacePvc, startLogStream, mapTerminalState).
- *
- * Networking caveat:
- *   The fake server runs on the host; the agent pod reaches it via
- *   `host.docker.internal`. On Docker Desktop (macOS/Windows) this resolves
- *   automatically. On Linux CI (GitHub Actions runners), kind needs an
- *   explicit `extraPortMappings` + `--add-host=host.docker.internal:host-gateway`
- *   in the cluster config. If this test fails on Linux with a DNS error, that
- *   is the fix; we do not currently encode it because all M2 contributors run
- *   Docker Desktop locally.
- */
-
-const COMPANY_ID = "55555555-5555-5555-5555-555555555555";
-const COMPANY_SLUG = "claudeend";
-const AGENT_SLUG = "claudeend-agent";
-const RUN_ULID = "01testclaudeend000000000001";
-const FAKE_AGENT_TAG = "paperclipai/fake-agent:test-m2";
-
-interface PollOpts {
-  intervalMs?: number;
-}
-
-async function pollUntil<T>(
-  fn: () => Promise<T | undefined>,
-  deadlineMs: number,
-  opts: PollOpts = {},
-): Promise<T | undefined> {
-  const interval = opts.intervalMs ?? 1000;
-  const deadline = Date.now() + deadlineMs;
-  while (Date.now() < deadline) {
-    const v = await fn();
-    if (v !== undefined) return v;
-    await new Promise((r) => setTimeout(r, interval));
-  }
-  return undefined;
-}
-
-async function findPod(
-  client: KubernetesApiClient,
-  namespace: string,
-  jobName: string,
-): Promise<V1Pod | undefined> {
-  const list = await client.core.listNamespacedPod(
-    namespace,
-    undefined,
-    undefined,
-    undefined,
-    undefined,
-    `job-name=${jobName}`,
-  );
-  return list.body.items[0];
-}
-
-describe.skipIf(!process.env["K8S_INTEGRATION"])(
-  "claude-style agent end-to-end on kind (fake LLM, fake agent)",
-  () => {
-    let kind: KindCluster;
-    let fake: FakeAnthropic;
-    let client: KubernetesApiClient;
-    let connection: ResolvedClusterConnection;
-    let agentImage: string;
-
-    beforeAll(async () => {
-      kind = spinUpKind();
-      fake = await startFakeAnthropic();
-
-      // Build + load the fake-agent image into kind, unless an override was
-      // provided (CI can pre-build to skip the ~10s build cost on warm
-      // Docker layer cache).
-      const override = process.env["AGENT_CLAUDE_IMAGE"];
-      if (override) {
-        agentImage = override;
-        // eslint-disable-next-line no-console
-        console.log(`[claude-end-to-end] using pre-built image override: ${agentImage}`);
-      } else {
-        agentImage = FAKE_AGENT_TAG;
-        const helpersDir = path.resolve(__dirname, "_helpers");
-        // eslint-disable-next-line no-console
-        console.log(`[claude-end-to-end] building ${agentImage} from ${helpersDir}/fake-agent.Dockerfile`);
-        await exec(
-          "docker",
-          [
-            "build",
-            "-t",
-            agentImage,
-            "-f",
-            path.join(helpersDir, "fake-agent.Dockerfile"),
-            helpersDir,
-          ],
-          { maxBuffer: 16 * 1024 * 1024 },
-        );
-        // eslint-disable-next-line no-console
-        console.log(`[claude-end-to-end] loading ${agentImage} into kind cluster ${kind.name}`);
-        await exec(
-          "kind",
-          ["load", "docker-image", agentImage, "--name", kind.name],
-          { maxBuffer: 16 * 1024 * 1024 },
-        );
-      }
-
-      connection = {
-        id: "c-1",
-        label: "kind",
-        kind: "kubeconfig",
-        kubeconfigYaml: kind.kubeconfigYaml,
-        defaultNamespacePrefix: "paperclip-",
-        allowAgentImageOverride: false,
-        capabilities: { cilium: false, storageClass: "standard", architectures: ["amd64", "arm64"] },
-      };
-      client = createKubernetesApiClient(connection);
-    }, 300_000);
-
-    afterAll(async () => {
-      await fake?.stop();
-      kind?.cleanup();
-    });
-
-    it(
-      "runs the fake agent against the fake Anthropic and surfaces the assistant text in pod logs",
-      async () => {
-        // 1. Tenant namespace.
-        const ensureResult = await ensureTenantNamespace(client, {
-          connection,
-          company: { id: COMPANY_ID, slug: COMPANY_SLUG },
-          tenantPolicy: null,
-          driverServiceAccount: { name: "default", namespace: "default" },
-          controlPlane: {
-            topology: "cross-cluster",
-            namespaceLabels: {},
-            podLabels: {},
-          },
-          adapterAllowFqdns: [],
-          imagePullDockerConfigJson: null,
-        });
-        const namespace = ensureResult.namespace;
-        // Always-hash namespace shape: paperclip-<slug>-<8-char-hash(companyId)>.
-        // See M3b Task 17 / orchestrator/naming.ts for the rationale.
-        expect(namespace).toMatch(new RegExp(`^paperclip-${COMPANY_SLUG}-[0-9a-z]{8}$`));
-
-        // 2. Workspace PVC. We don't actually write to /workspace, but the
-        //    Job spec mounts one and the failure-modes/job-lifecycle helpers
-        //    insist on a PVC name. Reuse the same builder for parity.
-        const pvc = buildAgentWorkspacePvc({
-          namespace,
-          agentId: "66666666-6666-6666-6666-666666666666",
-          agentSlug: AGENT_SLUG,
-          companyId: COMPANY_ID,
-          companySlug: COMPANY_SLUG,
-          storageClass: "standard",
-          sizeGi: 1,
-          strategyKey: "none",
-        });
-        await applyAgentWorkspacePvc(client, pvc);
-
-        // 3. Ephemeral Secret carrying ANTHROPIC_BASE_URL pointing at the
-        //    host's fake server. This is the variable the fake-agent script
-        //    reads. We use a placeholder OwnerReference and patch it after
-        //    Job creation (same two-phase commit as the driver).
-        const secret = buildEphemeralSecret({
-          namespace,
-          agentSlug: AGENT_SLUG,
-          runUlid: RUN_ULID,
-          runId: `test-run-${RUN_ULID}`,
-          companyId: COMPANY_ID,
-          companySlug: COMPANY_SLUG,
-          data: {
-            ANTHROPIC_BASE_URL: fake.url,
-            // The real driver injects BOOTSTRAP_TOKEN via this same envFrom
-            // path. We include a placeholder so the env shape mirrors prod
-            // even though our fake-agent ignores it.
-            BOOTSTRAP_TOKEN: "bst_test_unused",
-          },
-          ownerJob: {
-            name: "placeholder",
-            uid: "00000000-0000-0000-0000-000000000000",
-          },
-        });
-        const secretName = secret.metadata!.name!;
-        secret.metadata!.ownerReferences = [];
-        await applyEphemeralSecret(client, secret);
-
-        // 4. Job. We re-use buildBusyboxTestJob with an image override so we
-        //    inherit the PSS Restricted security context, volume layout, and
-        //    envFrom plumbing from the existing tested helper.
-        const jobName = `agent-${AGENT_SLUG}-run-${RUN_ULID}`;
-        const jobSpec = buildBusyboxTestJob({
-          namespace,
-          jobName,
-          pvcName: pvc.metadata!.name!,
-          envSecretName: secretName,
-          image: agentImage,
-          // The fake-agent image's ENTRYPOINT runs the script, but
-          // buildBusyboxTestJob hard-codes `command: ["sh", "-c", agentScript]`
-          // so we explicitly invoke the binary. /usr/local/bin is on busybox's
-          // default PATH; using the absolute path is robust against any PATH
-          // surprise from the security context.
-          agentScript: "/usr/local/bin/paperclip-agent-shim",
-          activeDeadlineSeconds: 60,
-        });
-        const created = await client.batch.createNamespacedJob(namespace, jobSpec);
-        const jobUid = created.body.metadata!.uid!;
-        expect(jobUid).toBeTruthy();
-
-        await patchEphemeralSecretOwnerReference(client, namespace, secretName, {
-          name: jobName,
-          uid: jobUid,
-        });
-
-        // 5. Wait for the agent container to enter Running or Terminated, then
-        //    attach the log stream. (See job-lifecycle.test.ts for why we don't
-        //    open the stream against a Pending pod.)
-        const podName = await pollUntil<string>(async () => {
-          const p = await findPod(client, namespace, jobName);
-          const c = p?.status?.containerStatuses?.find((s) => s.name === "agent");
-          if (p?.metadata?.name && (c?.state?.running || c?.state?.terminated)) {
-            return p.metadata.name;
-          }
-          return undefined;
-        }, 90_000, { intervalMs: 500 });
-        expect(podName, "expected agent container to start within 90s").toBeTruthy();
-
-        const logs: string[] = [];
-        const logHandle = startLogStream({
-          client,
-          namespace,
-          podName: podName!,
-          containerName: "agent",
-          onLog: async (_stream, chunk) => {
-            logs.push(chunk);
-          },
-        });
-
-        // 6. Poll for terminal Job state.
-        let terminalJob: V1Job | undefined;
-        let terminalPod: V1Pod | undefined;
-        const deadline = Date.now() + 120_000;
-        while (Date.now() < deadline) {
-          await new Promise((r) => setTimeout(r, 1000));
-          const j = await client.batch.readNamespacedJob(jobName, namespace);
-          if ((j.body.status?.succeeded ?? 0) >= 1 || (j.body.status?.failed ?? 0) >= 1) {
-            terminalJob = j.body;
-            terminalPod = await findPod(client, namespace, jobName);
-            break;
-          }
-        }
-        logHandle.abort();
-        await logHandle.done;
-
-        // Diagnostics dump on failure paths so platform-specific networking
-        // skew is visible in CI logs.
-        const joinedLogs = logs.join("\n");
-        if (!terminalJob) {
-          // eslint-disable-next-line no-console
-          console.warn("[claude-end-to-end] no terminal Job state. logs so far:\n" + joinedLogs);
-        }
-        expect(terminalJob, "expected Job to reach terminal state within 120s").toBeTruthy();
-
-        const result = mapTerminalState({ job: terminalJob!, pod: terminalPod });
-        if (result.exitCode !== 0) {
-          // eslint-disable-next-line no-console
-          console.warn(
-            "[claude-end-to-end] non-zero exit. mapped result:",
-            result,
-            "\nlogs:\n" + joinedLogs,
-          );
-        }
-        expect(result.exitCode).toBe(0);
-        expect(result.errorCode).toBeUndefined();
-        expect(result.timedOut).toBe(false);
-
-        // 7. The assistant text from the fake server must show up in the
-        //    container's stdout — proving the round-trip:
-        //    pod  →  host.docker.internal:port/v1/messages  →  fake server
-        //         ←  JSON with {"text":"I read your prompt and I am alive."}  ←
-        expect(joinedLogs).toMatch(/I read your prompt and I am alive/);
-        // And the fake-agent's own progress markers, so we know the script
-        // actually executed (not just a stale cached log).
-        expect(joinedLogs).toContain("[fake-agent] starting");
-        expect(joinedLogs).toContain("[fake-agent] success: assistant marker found");
-      },
-      300_000,
-    );
-  },
-);

packages/adapters/kubernetes-execution/test/integration/codex-smoke.test.ts

@@ -1,91 +0,0 @@
-import { execSync } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createKubernetesApiClient } from "../../src/index.js";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-/**
- * M3b Task 9: smoke test for the `agent-runtime-codex` runtime image.
- *
- * Scope: prove that the freshly built image:
- *   - boots in a kind cluster
- *   - has the `codex` CLI on PATH (matching the shim's exec.LookPath contract)
- *
- * This is intentionally a thin probe — it does NOT exercise the full driver
- * orchestration (covered by claude-end-to-end.test.ts and the unit tests on
- * driver.run()) nor the real OpenAI API (which would require a live key).
- *
- * Gated on K8S_INTEGRATION so contributors without docker + kind on PATH can
- * still run the full unit suite.
- */
-describe.skipIf(!process.env["K8S_INTEGRATION"])(
-  "codex_local runtime image smoke",
-  () => {
-    let kind: KindCluster;
-    const IMAGE = "paperclipai/agent-runtime-codex:test-m3b";
-
-    beforeAll(() => {
-      kind = spinUpKind();
-      const repoRoot = path.resolve(__dirname, "../../../../..");
-      // Build base + codex into the local docker daemon, then load into kind.
-      execSync(
-        `docker buildx bake --file ${repoRoot}/docker/agent-runtime/buildx-bake.hcl --set "base.tags=paperclipai/agent-runtime-base:test-m3b" --set "codex.tags=${IMAGE}" --set "*.platforms=linux/amd64" base codex`,
-        { cwd: repoRoot, stdio: "inherit" },
-      );
-      execSync(`kind load docker-image ${IMAGE} --name ${kind.name}`, {
-        stdio: "inherit",
-      });
-    }, 600_000);
-
-    afterAll(() => kind?.cleanup());
-
-    it("the agent-runtime-codex image boots and `codex` is on PATH", () => {
-      // Construct the API client purely to assert the connection shape this
-      // package exports remains compatible with codex_local runtime usage.
-      // The actual probe is a kubectl-driven Pod since the smoke test does
-      // not need the full orchestrator path.
-      createKubernetesApiClient({
-        id: "c-1",
-        label: "kind",
-        kind: "kubeconfig",
-        kubeconfigYaml: kind.kubeconfigYaml,
-        defaultNamespacePrefix: "paperclip-",
-        allowAgentImageOverride: false,
-        imageAllowlist: [],
-        capabilities: {
-          cilium: false,
-          storageClass: "standard",
-          architectures: ["amd64"],
-        },
-      });
-
-      const podYaml = `apiVersion: v1
-kind: Pod
-metadata:
-  name: codex-probe
-  namespace: default
-spec:
-  restartPolicy: Never
-  containers:
-    - name: c
-      image: ${IMAGE}
-      imagePullPolicy: IfNotPresent
-      command: ["sh", "-c", "command -v codex && echo CODEX_OK"]
-`;
-      const env = { ...process.env, KUBECONFIG: kind.kubeconfigPath };
-      execSync(`kubectl apply -f - <<'EOF'\n${podYaml}\nEOF`, {
-        env,
-        shell: "/bin/bash",
-      });
-      execSync(
-        `kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/codex-probe --timeout=120s`,
-        { env },
-      );
-      const logs = execSync(`kubectl logs pod/codex-probe`, { env }).toString();
-      expect(logs).toContain("CODEX_OK");
-    }, 600_000);
-  },
-);

packages/adapters/kubernetes-execution/test/integration/empirical-measurement-claude.test.ts

@@ -1,466 +0,0 @@
-/**
- * M3a Tasks 14–16: empirical resource measurement with the real claude-code agent.
- *
- * APPROACH: This is a NEW test file added alongside the M2 busybox measurement
- * test (empirical-measurement.test.ts). The M2 test is left intact as a cheap
- * CI smoke for measurement plumbing; this file adds the real workload:
- *   - Image: paperclipai/agent-runtime-claude:test-m3a
- *   - Prompt: "Read README.md in /workspace and tell me the project name in one word."
- *   - Runs: 5 sequential, fresh metric-capture each run
- *   - Workspace: PVC seeded from _fixtures/test-repo via seedWorkspaceFromFixture
- *
- * Gate: K8S_INTEGRATION + ANTHROPIC_API_KEY must both be set. This means the
- * test does NOT run on every K8S_INTEGRATION CI step — only when the operator
- * explicitly provides an Anthropic API key (e.g. for the measurement run).
- *
- * After 5 runs the test writes Peak / Median / p95 numbers into
- * docs/k8s-execution/sizing.md (overwriting the TBD placeholders from Task 15).
- *
- * Cost per full run: ~$0.05–0.20. Do not run on every CI push.
- *
- * Manual run:
- *   ANTHROPIC_API_KEY=sk-ant-... K8S_INTEGRATION=1 \
- *     pnpm --filter @paperclipai/execution-target-kubernetes exec \
- *     vitest run test/integration/empirical-measurement-claude.test.ts
- */
-
-import { writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { execSync } from "node:child_process";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import type { V1Pod } from "@kubernetes/client-node";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-import {
-  installMetricsServer,
-  readPodMetrics,
-  waitForMetricsServerReady,
-} from "./_helpers/metrics-server.js";
-import { seedWorkspaceFromFixture } from "./_helpers/seed-workspace.js";
-import {
-  createKubernetesApiClient,
-  ensureTenantNamespace,
-  type ResolvedClusterConnection,
-} from "../../src/index.js";
-import {
-  buildAgentWorkspacePvc,
-  applyAgentWorkspacePvc,
-} from "../../src/orchestrator/pvc.js";
-import {
-  buildEphemeralSecret,
-  applyEphemeralSecret,
-  patchEphemeralSecretOwnerReference,
-} from "../../src/orchestrator/secret.js";
-import { buildBusyboxTestJob } from "./_helpers/busybox-job.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const REAL_CLAUDE_IMAGE =
-  process.env["AGENT_CLAUDE_REAL_IMAGE"] ?? "paperclipai/agent-runtime-claude:test-m3a";
-const BASE_IMAGE =
-  process.env["AGENT_BASE_IMAGE"] ?? "paperclipai/agent-runtime-base:test-m3a";
-
-const NUM_RUNS = 5;
-const COMPANY_ID = "55555555-5555-5555-5555-555555555557";
-const COMPANY_SLUG = "measure-claude";
-
-/**
- * Both K8S_INTEGRATION and ANTHROPIC_API_KEY must be set. The measurement is
- * gated on ANTHROPIC_API_KEY so it does not run on every K8S_INTEGRATION CI
- * step (which would incur API costs and extended runtimes on unrelated PRs).
- */
-describe.skipIf(!process.env["K8S_INTEGRATION"] || !process.env["ANTHROPIC_API_KEY"])(
-  "empirical resource measurement — real claude-code agent (5 runs)",
-  () => {
-    let kind: KindCluster;
-
-    beforeAll(async () => {
-      kind = spinUpKind();
-
-      // Build and load agent-runtime-base + agent-runtime-claude into kind,
-      // mirroring the approach in claude-code-real.test.ts (Task 13).
-      const repoRoot = join(__dirname, "../../../../..");
-      // eslint-disable-next-line no-console
-      console.log("[measure-claude] building agent-runtime-base...");
-      execSync(
-        `docker build -t ${BASE_IMAGE} -f docker/agent-runtime/base/Dockerfile docker/agent-runtime/base`,
-        { cwd: repoRoot, stdio: "inherit" },
-      );
-      // eslint-disable-next-line no-console
-      console.log("[measure-claude] building agent-runtime-claude...");
-      execSync(
-        `docker build -t ${REAL_CLAUDE_IMAGE} -f docker/agent-runtime/claude/Dockerfile docker/agent-runtime/claude`,
-        { cwd: repoRoot, stdio: "inherit" },
-      );
-      // eslint-disable-next-line no-console
-      console.log("[measure-claude] loading images into kind...");
-      execSync(`kind load docker-image ${BASE_IMAGE} --name ${kind.name}`, { stdio: "inherit" });
-      execSync(`kind load docker-image ${REAL_CLAUDE_IMAGE} --name ${kind.name}`, {
-        stdio: "inherit",
-      });
-
-      installMetricsServer(kind.kubeconfigPath);
-      await waitForMetricsServerReady(kind.kubeconfigPath);
-    }, 900_000);
-
-    afterAll(() => {
-      kind?.cleanup();
-    });
-
-    it(
-      "measures peak CPU/memory across 5 real claude-code runs; records numbers to sizing.md",
-      async () => {
-        const connection: ResolvedClusterConnection = {
-          id: "c-measure-claude-1",
-          label: "kind-measure-claude",
-          kind: "kubeconfig",
-          kubeconfigYaml: kind.kubeconfigYaml,
-          defaultNamespacePrefix: "paperclip-",
-          allowAgentImageOverride: false,
-          capabilities: {
-            cilium: false,
-            storageClass: "standard",
-            architectures: ["amd64"],
-          },
-        };
-        const client = createKubernetesApiClient(connection);
-
-        const ensureResult = await ensureTenantNamespace(client, {
-          connection,
-          company: { id: COMPANY_ID, slug: COMPANY_SLUG },
-          tenantPolicy: null,
-          driverServiceAccount: { name: "default", namespace: "default" },
-          controlPlane: {
-            topology: "cross-cluster",
-            namespaceLabels: {},
-            podLabels: {},
-          },
-          adapterAllowFqdns: ["api.anthropic.com"],
-          imagePullDockerConfigJson: null,
-        });
-        const namespace = ensureResult.namespace;
-
-        const agentSlug = "measure-claude-agent";
-        const agentId = "66666666-6666-6666-6666-666666666668";
-
-        // Accumulate samples across all 5 runs.
-        const allSamples: Array<{
-          run: number;
-          tMs: number;
-          cpuMillicores: number;
-          memoryMi: number;
-        }> = [];
-        const runPeaks: Array<{ cpuMillicores: number; memoryMi: number }> = [];
-
-        for (let run = 1; run <= NUM_RUNS; run++) {
-          // Fresh PVC per run so claude-code always sees a clean workspace.
-          const runPvcName = `agent-${agentSlug}-workspace-r${run}`;
-          const pvc = buildAgentWorkspacePvc({
-            namespace,
-            agentId,
-            agentSlug: `${agentSlug}-r${run}`,
-            companyId: COMPANY_ID,
-            companySlug: COMPANY_SLUG,
-            storageClass: "standard",
-            sizeGi: 1,
-            strategyKey: "none",
-          });
-          // Override the PVC name so each run gets its own volume.
-          pvc.metadata!.name = runPvcName;
-          await applyAgentWorkspacePvc(client, pvc);
-
-          // Seed the workspace with the fixture repo (README.md + .gitignore).
-          await seedWorkspaceFromFixture({
-            kubeconfigPath: kind.kubeconfigPath,
-            namespace,
-            pvcName: runPvcName,
-            fixtureDir: join(__dirname, "_fixtures/test-repo"),
-            podName: `seed-workspace-r${run}`,
-          });
-
-          const runUlid = `01testclaudemeasure0000${run}`;
-          const secret = buildEphemeralSecret({
-            namespace,
-            agentSlug: `${agentSlug}-r${run}`,
-            runUlid,
-            runId: `test-run-measure-claude-${run}`,
-            companyId: COMPANY_ID,
-            companySlug: COMPANY_SLUG,
-            data: { ANTHROPIC_API_KEY: process.env["ANTHROPIC_API_KEY"]! },
-            ownerJob: {
-              name: "placeholder",
-              uid: "00000000-0000-0000-0000-000000000000",
-            },
-          });
-          const secretName = secret.metadata!.name!;
-          secret.metadata!.ownerReferences = [];
-          await applyEphemeralSecret(client, secret);
-
-          // The real claude-code agent job: use the actual agent-runtime-claude
-          // image as the main container. We use buildBusyboxTestJob only for
-          // the Job scaffolding (PSS-restricted, PVC + secret volumes) and
-          // override the image + command to invoke claude-code with our prompt.
-          //
-          // The agent-runtime-claude image entrypoint is the paperclip shim,
-          // which exchanges a bootstrap token before starting claude-code. In
-          // this test environment we bypass the shim by invoking claude-code
-          // directly via an override command, passing the prompt via --print
-          // (non-interactive single-turn mode).
-          //
-          // Resource limits are set to the M1 defaults (200m / 2cpu, 256Mi /
-          // 1Gi) so the test measures peak usage relative to those limits.
-          const jobName = `agent-${agentSlug}-run-${runUlid}`;
-          const prompt =
-            "Read README.md in /workspace and tell me the project name in one word.";
-          const jobSpec = buildBusyboxTestJob({
-            namespace,
-            jobName,
-            pvcName: runPvcName,
-            envSecretName: secretName,
-            // Use the real claude-code image.
-            image: REAL_CLAUDE_IMAGE,
-            // claude-code --print runs a single non-interactive turn and exits.
-            agentScript: `claude --print "${prompt}"`,
-            // Init container still uses busybox — just checks workspace is ready.
-            initScript: "ls -la /workspace; echo init-done",
-            activeDeadlineSeconds: 300,
-            cpuLimit: "2",
-            memoryLimit: "1Gi",
-          });
-          // Override resource requests to M1 defaults as well.
-          const mainContainer = jobSpec.spec!.template!.spec!.containers![0]!;
-          mainContainer.resources = {
-            requests: { cpu: "200m", memory: "256Mi" },
-            limits: { cpu: "2", memory: "1Gi" },
-          };
-
-          const created = await client.batch.createNamespacedJob(namespace, jobSpec);
-          const jobUid = created.body.metadata!.uid!;
-          await patchEphemeralSecretOwnerReference(client, namespace, secretName, {
-            name: jobName,
-            uid: jobUid,
-          });
-
-          // Polling loop: every 5s while the Job is alive, scrape pod metrics.
-          const runPeak = { cpuMillicores: 0, memoryMi: 0 };
-          const startedAt = Date.now();
-          const stop = setInterval(() => {
-            try {
-              const metrics = readPodMetrics(namespace, kind.kubeconfigPath);
-              for (const m of metrics) {
-                if (!m.name.startsWith(jobName)) continue;
-                runPeak.cpuMillicores = Math.max(runPeak.cpuMillicores, m.cpuMillicores);
-                runPeak.memoryMi = Math.max(runPeak.memoryMi, m.memoryMi);
-                allSamples.push({
-                  run,
-                  tMs: Date.now() - startedAt,
-                  cpuMillicores: m.cpuMillicores,
-                  memoryMi: m.memoryMi,
-                });
-              }
-            } catch {
-              /* metrics-server briefly unavailable — skip this poll */
-            }
-          }, 5000);
-
-          // Wait for terminal state (max 5 minutes per run).
-          let succeeded = false;
-          const deadline = Date.now() + 300_000;
-          let terminalPod: V1Pod | undefined;
-          while (Date.now() < deadline) {
-            await new Promise((r) => setTimeout(r, 2000));
-            const j = await client.batch.readNamespacedJob(jobName, namespace);
-            if ((j.body.status?.succeeded ?? 0) >= 1) {
-              succeeded = true;
-              const list = await client.core.listNamespacedPod(
-                namespace,
-                undefined,
-                undefined,
-                undefined,
-                undefined,
-                `job-name=${jobName}`,
-              );
-              terminalPod = list.body.items[0];
-              break;
-            }
-            if ((j.body.status?.failed ?? 0) >= 1) break;
-          }
-          clearInterval(stop);
-
-          expect(
-            succeeded,
-            `run ${run}: expected claude-code workload to complete cleanly`,
-          ).toBe(true);
-          expect(terminalPod?.status?.phase).toBe("Succeeded");
-
-          runPeaks.push({ ...runPeak });
-          // eslint-disable-next-line no-console
-          console.log(
-            `[measure-claude] run ${run}/${NUM_RUNS}: peak CPU=${runPeak.cpuMillicores}m mem=${runPeak.memoryMi}Mi`,
-          );
-        }
-
-        // Compute aggregate stats across all 5 runs.
-        const cpuValues = runPeaks.map((p) => p.cpuMillicores).sort((a, b) => a - b);
-        const memValues = runPeaks.map((p) => p.memoryMi).sort((a, b) => a - b);
-
-        const peakCpu = Math.max(...cpuValues);
-        const medianCpu = percentile(cpuValues, 50);
-        const p95Cpu = percentile(cpuValues, 95);
-
-        const peakMem = Math.max(...memValues);
-        const medianMem = percentile(memValues, 50);
-        const p95Mem = percentile(memValues, 95);
-
-        // Sanity: peaks must fit inside M1 per-tenant envelope.
-        expect(peakMem, "peak memory must be under 1Gi limit").toBeLessThan(1024);
-        expect(peakCpu, "peak CPU must be under 2 cpu limit").toBeLessThan(2000);
-
-        // Write the sizing report, overwriting the TBD placeholders in sizing.md.
-        const sizingPath = join(
-          __dirname,
-          "..",
-          "..",
-          "..",
-          "..",
-          "..",
-          "docs",
-          "k8s-execution",
-          "sizing.md",
-        );
-        mkdirSync(dirname(sizingPath), { recursive: true });
-        writeFileSync(
-          sizingPath,
-          renderSizingMarkdown({
-            timestamp: new Date().toISOString(),
-            image: REAL_CLAUDE_IMAGE,
-            prompt: "Read README.md in /workspace and tell me the project name in one word.",
-            numRuns: NUM_RUNS,
-            peakCpu,
-            medianCpu,
-            p95Cpu,
-            peakMem,
-            medianMem,
-            p95Mem,
-            runPeaks,
-          }),
-        );
-      },
-      // 5 runs × 300s deadline + 15 min overhead for kind boot / image load.
-      2_700_000,
-    );
-  },
-);
-
-// ---------------------------------------------------------------------------
-// Statistics helpers
-// ---------------------------------------------------------------------------
-
-function percentile(sorted: number[], p: number): number {
-  if (sorted.length === 0) return 0;
-  const idx = Math.ceil((p / 100) * sorted.length) - 1;
-  return sorted[Math.max(0, Math.min(idx, sorted.length - 1))]!;
-}
-
-// ---------------------------------------------------------------------------
-// Markdown renderer
-// ---------------------------------------------------------------------------
-
-function renderSizingMarkdown(input: {
-  timestamp: string;
-  image: string;
-  prompt: string;
-  numRuns: number;
-  peakCpu: number;
-  medianCpu: number;
-  p95Cpu: number;
-  peakMem: number;
-  medianMem: number;
-  p95Mem: number;
-  runPeaks: Array<{ cpuMillicores: number; memoryMi: number }>;
-}): string {
-  const runRows = input.runPeaks
-    .map(
-      (r, i) => `| ${i + 1} | ${r.cpuMillicores} m | ${r.memoryMi} Mi |`,
-    )
-    .join("\n");
-
-  return `# Kubernetes execution target — agent sizing
-
-## Workload
-
-- Image: \`${input.image}\` (claude-code from \`@anthropic-ai/claude-code\`)
-- Prompt: \`"${input.prompt}"\`
-- Workspace: PVC seeded with a 2-file repo (README.md + .gitignore)
-- Runs: ${input.numRuns} sequential, fresh PVC each run
-- Cluster: kind v0.24.0 (Kubernetes v1.31.x), single node, on a CI runner
-
-Last measured: ${input.timestamp}
-
-## Observations
-
-| Metric    | Peak | Median | p95   |
-|-----------|------|--------|-------|
-| CPU (m)   | ${input.peakCpu} | ${input.medianCpu} | ${input.p95Cpu} |
-| Memory (Mi) | ${input.peakMem} | ${input.medianMem} | ${input.p95Mem} |
-
-### Per-run peaks
-
-| Run | CPU (m) | Memory (Mi) |
-|-----|---------|-------------|
-${runRows}
-
-## Recommended defaults
-
-\`\`\`yaml
-resources:
-  requests:
-    cpu:    200m
-    memory: 256Mi
-  limits:
-    cpu:    2
-    memory: 1Gi
-\`\`\`
-
-(M1 defaults retained until measurement justifies a bump — see "Decision".)
-
-## Recommended ResourceQuota for a 50-agent tenant
-
-\`\`\`yaml
-spec:
-  hard:
-    requests.cpu:    "10"
-    requests.memory: "12Gi"
-    limits.cpu:      "100"
-    limits.memory:   "50Gi"
-    count/jobs.batch: "50"
-    count/persistentvolumeclaims: "50"
-    count/secrets:   "200"
-    count/configmaps: "100"
-\`\`\`
-
-## Decision
-
-Threshold for raising defaults:
-- Memory: peak > 0.6 × current limit (614 Mi)
-- CPU: peak > 0.5 × current limit (1000 m)
-
-Decision: KEEP M1 defaults. Re-evaluate after first production runs surface real multi-turn workload data.
-
-## Caveats
-
-- This is a single-turn prompt. Multi-turn sessions (real agent loops) will use more memory due to accumulated context. Operators running multi-turn workloads should monitor actual usage and raise quotas accordingly.
-- Numbers from the empirical-measurement test are taken on a CI runner; production hardware may show different baselines.
-
-## How we measured
-
-\`packages/adapters/kubernetes-execution/test/integration/empirical-measurement-claude.test.ts\` provisions kind + metrics-server, runs the workload 5 times under measurement, and writes the table above. Re-run with:
-
-\`\`\`bash
-ANTHROPIC_API_KEY=... K8S_INTEGRATION=1 \\
-  pnpm --filter @paperclipai/execution-target-kubernetes exec vitest run test/integration/empirical-measurement-claude.test.ts
-\`\`\`
-
-Cost: ~$0.05–0.20 per full run.
-`;
-}

packages/adapters/kubernetes-execution/test/integration/empirical-measurement.test.ts

@@ -1,316 +0,0 @@
-import { writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import type { V1Pod } from "@kubernetes/client-node";
-import { spinUpKind, type KindCluster } from "./_harness.js";
-import {
-  installMetricsServer,
-  readPodMetrics,
-  waitForMetricsServerReady,
-} from "./_helpers/metrics-server.js";
-import {
-  createKubernetesApiClient,
-  ensureTenantNamespace,
-  type ResolvedClusterConnection,
-} from "../../src/index.js";
-import {
-  buildAgentWorkspacePvc,
-  applyAgentWorkspacePvc,
-} from "../../src/orchestrator/pvc.js";
-import {
-  buildEphemeralSecret,
-  applyEphemeralSecret,
-  patchEphemeralSecretOwnerReference,
-} from "../../src/orchestrator/secret.js";
-import { buildBusyboxTestJob } from "./_helpers/busybox-job.js";
-
-/**
- * M2 Task 28: empirical resource measurement infrastructure.
- *
- * Provisions kind + metrics-server, runs a fake-agent workload (busybox echo
- * loop) under measurement, captures peak CPU / memory observed via
- * `kubectl top pod`, and writes the numbers to
- * `docs/k8s-execution/sizing-fake-agent.md`.
- *
- * Risk #4 in the M2 design ("empirical resource defaults") is PARTIALLY
- * resolved by this test: the *infrastructure* (metrics-server bootstrap, pod
- * polling, sizing.md generation) ships with M2; the *representative numbers*
- * for real claude_local agents require the M3 agent-runtime-claude image
- * exercising real Anthropic protocol, which is out of M2's scope. M1's
- * resource defaults (256Mi requests / 1Gi limit, 200m / 2cpu) are retained
- * unchanged.
- *
- * The test therefore asserts only sanity bounds (peaks below the per-tenant
- * envelope) — not absolute values, since absolute values are only meaningful
- * once the workload is real.
- */
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-describe.skipIf(!process.env["K8S_INTEGRATION"])(
-  "empirical resource measurement on kind",
-  () => {
-    let kind: KindCluster;
-
-    beforeAll(async () => {
-      kind = spinUpKind();
-      installMetricsServer(kind.kubeconfigPath);
-      await waitForMetricsServerReady(kind.kubeconfigPath);
-    }, 360_000);
-
-    afterAll(() => {
-      kind?.cleanup();
-    });
-
-    it(
-      "measures peak CPU/memory across a busybox-load run; records numbers; asserts < tenant max",
-      async () => {
-        const connection: ResolvedClusterConnection = {
-          id: "c-1",
-          label: "kind",
-          kind: "kubeconfig",
-          kubeconfigYaml: kind.kubeconfigYaml,
-          defaultNamespacePrefix: "paperclip-",
-          allowAgentImageOverride: false,
-          capabilities: {
-            cilium: false,
-            storageClass: "standard",
-            architectures: ["amd64"],
-          },
-        };
-        const client = createKubernetesApiClient(connection);
-
-        const companyId = "55555555-5555-5555-5555-555555555555";
-        const companySlug = "measure";
-        const ensureResult = await ensureTenantNamespace(client, {
-          connection,
-          company: { id: companyId, slug: companySlug },
-          tenantPolicy: null,
-          driverServiceAccount: { name: "default", namespace: "default" },
-          controlPlane: {
-            topology: "cross-cluster",
-            namespaceLabels: {},
-            podLabels: {},
-          },
-          adapterAllowFqdns: [],
-          imagePullDockerConfigJson: null,
-        });
-        const namespace = ensureResult.namespace;
-
-        const agentSlug = "measure-agent";
-        const pvc = buildAgentWorkspacePvc({
-          namespace,
-          agentId: "66666666-6666-6666-6666-666666666666",
-          agentSlug,
-          companyId,
-          companySlug,
-          storageClass: "standard",
-          sizeGi: 1,
-          strategyKey: "none",
-        });
-        await applyAgentWorkspacePvc(client, pvc);
-
-        const runUlid = "01testempiricalmeasure00001";
-        const secret = buildEphemeralSecret({
-          namespace,
-          agentSlug,
-          runUlid,
-          runId: "test-run-empirical",
-          companyId,
-          companySlug,
-          data: { MY_KEY: "value" },
-          ownerJob: {
-            name: "placeholder",
-            uid: "00000000-0000-0000-0000-000000000000",
-          },
-        });
-        const secretName = secret.metadata!.name!;
-        secret.metadata!.ownerReferences = [];
-        await applyEphemeralSecret(client, secret);
-
-        const jobName = `agent-${agentSlug}-run-${runUlid}`;
-        // Workload: ~75s of mixed echo + arithmetic + brief allocations.
-        // metrics-server's default scrape interval is 15s, so we need a
-        // workload that runs LONG enough for 3-4 scrapes to land while the
-        // pod is alive. (A 10s busybox loop will exit before the first
-        // scrape window closes, leaving the test's assertions on `peaks`
-        // valid but the sample table empty.) This is still a SANITY workload
-        // — busybox's resident set on Alpine hovers around 1-3 MiB and CPU
-        // is near zero — but the timeline is long enough to prove the
-        // plumbing actually captured numbers.
-        const agentScript =
-          'sleep 2; ' +
-          'for round in $(seq 1 5); do ' +
-          '  echo "round $round start"; ' +
-          // 200 echoes spaced 50ms = ~10s of light I/O.
-          '  for i in $(seq 1 200); do echo "round $round line $i"; sleep 0.05; done; ' +
-          // Brief CPU spike: count primes <100k via trial division on busybox sh.
-          '  c=0; n=2; while [ $n -lt 5000 ]; do d=2; p=1; while [ $((d*d)) -le $n ]; do if [ $((n % d)) -eq 0 ]; then p=0; break; fi; d=$((d+1)); done; c=$((c+p)); n=$((n+1)); done; ' +
-          '  echo "round $round primes=$c"; ' +
-          '  sleep 1; ' +
-          'done; ' +
-          'echo done; exit 0';
-        const jobSpec = buildBusyboxTestJob({
-          namespace,
-          jobName,
-          pvcName: pvc.metadata!.name!,
-          envSecretName: secretName,
-          agentScript,
-          activeDeadlineSeconds: 180,
-          // The prime-count loop in shell is interpretation-heavy; bump the
-          // CPU limit so it doesn't get throttled into a wall-clock blowout.
-          cpuLimit: "500m",
-        });
-
-        const created = await client.batch.createNamespacedJob(namespace, jobSpec);
-        const jobUid = created.body.metadata!.uid!;
-        await patchEphemeralSecretOwnerReference(client, namespace, secretName, {
-          name: jobName,
-          uid: jobUid,
-        });
-
-        // Polling loop: every 5s while the Job is alive, scrape pod metrics
-        // for the namespace and update peaks. Guard with try/catch — metrics-
-        // server can return 503 mid-scrape and that should not fail the test.
-        const peaks = { cpuMillicores: 0, memoryMi: 0, samples: 0 };
-        const samples: Array<{ tMs: number; cpuMillicores: number; memoryMi: number }> = [];
-        const startedAt = Date.now();
-        const stop = setInterval(() => {
-          try {
-            const metrics = readPodMetrics(namespace, kind.kubeconfigPath);
-            for (const m of metrics) {
-              if (!m.name.startsWith(jobName)) continue;
-              peaks.cpuMillicores = Math.max(peaks.cpuMillicores, m.cpuMillicores);
-              peaks.memoryMi = Math.max(peaks.memoryMi, m.memoryMi);
-              peaks.samples += 1;
-              samples.push({
-                tMs: Date.now() - startedAt,
-                cpuMillicores: m.cpuMillicores,
-                memoryMi: m.memoryMi,
-              });
-            }
-          } catch {
-            /* metrics-server briefly unavailable — skip this poll */
-          }
-        }, 5000);
-
-        // Wait for terminal state. The workload runs ~75s of wall-clock; we
-        // give a generous 200s deadline to absorb kind's pull/start latency.
-        let succeeded = false;
-        const deadline = Date.now() + 200_000;
-        let terminalPod: V1Pod | undefined;
-        while (Date.now() < deadline) {
-          await new Promise((r) => setTimeout(r, 1000));
-          const j = await client.batch.readNamespacedJob(jobName, namespace);
-          if ((j.body.status?.succeeded ?? 0) >= 1) {
-            succeeded = true;
-            const list = await client.core.listNamespacedPod(
-              namespace,
-              undefined,
-              undefined,
-              undefined,
-              undefined,
-              `job-name=${jobName}`,
-            );
-            terminalPod = list.body.items[0];
-            break;
-          }
-          if ((j.body.status?.failed ?? 0) >= 1) break;
-        }
-        clearInterval(stop);
-
-        expect(succeeded, "expected fake-agent workload to complete cleanly").toBe(true);
-        expect(terminalPod?.status?.phase).toBe("Succeeded");
-
-        // Sanity: the busybox echo loop should fit comfortably under the
-        // M1 per-tenant envelope (1Gi memory, 2 CPU). The peaks may legitimately
-        // be 0 if no scrape landed during the Job's ~12s lifetime — that's fine
-        // for the infrastructure smoke; we just record what we saw.
-        expect(peaks.memoryMi).toBeLessThan(1024);
-        expect(peaks.cpuMillicores).toBeLessThan(2000);
-
-        // Write the sizing report.
-        const sizingPath = join(
-          __dirname,
-          "..",
-          "..",
-          "..",
-          "..",
-          "..",
-          "docs",
-          "k8s-execution",
-          "sizing-fake-agent.md",
-        );
-        mkdirSync(dirname(sizingPath), { recursive: true });
-        writeFileSync(
-          sizingPath,
-          renderSizingMarkdown({
-            timestamp: new Date().toISOString(),
-            agentScript,
-            peaks,
-            samples,
-          }),
-        );
-      },
-      420_000,
-    );
-  },
-);
-
-function renderSizingMarkdown(input: {
-  timestamp: string;
-  agentScript: string;
-  peaks: { cpuMillicores: number; memoryMi: number; samples: number };
-  samples: Array<{ tMs: number; cpuMillicores: number; memoryMi: number }>;
-}): string {
-  const sampleRows =
-    input.samples.length === 0
-      ? "_(no metrics scrapes landed during the Job's lifetime — the busybox\n  workload completes in ~12s, faster than metrics-server's 15s scrape\n  interval can guarantee. Re-run with a longer-lived workload to populate.)_\n"
-      : input.samples
-          .map(
-            (s) =>
-              `| ${(s.tMs / 1000).toFixed(1)}s | ${s.cpuMillicores}m | ${s.memoryMi} Mi |`,
-          )
-          .join("\n");
-
-  return `# Sizing — fake agent (busybox echo loop)
-
-Last measured: ${input.timestamp}
-
-## Workload
-
-\`\`\`sh
-${input.agentScript}
-\`\`\`
-
-## Peaks observed via metrics-server
-
-| Metric | Peak |
-|---|---|
-| CPU | ${input.peaks.cpuMillicores} m |
-| Memory | ${input.peaks.memoryMi} Mi |
-| Samples observed | ${input.peaks.samples} |
-
-## Sample timeline
-
-| t (s since Job creation) | CPU | Memory |
-|---|---|---|
-${sampleRows}
-
-## Disposition
-
-This is a **sanity-check workload**, NOT a representative sample of real
-\`claude_local\` agents. The busybox echo loop's resident set is on the order
-of 1-3 MiB and CPU is near zero — it exercises the *measurement plumbing*
-end-to-end, not the resource curve of any real agent runtime.
-
-Real measurement against the live \`claude-code\` CLI is deferred to M3, when
-the \`agent-runtime-claude\` image will be exercised against valid Anthropic
-protocol. M1's defaults (256Mi requests / 1Gi limit, 200m / 2 CPU) are
-retained until then.
-
-Risk #4 in the M2 design spec is **partially resolved** by this report:
-infrastructure ready, representative numbers pending real adapter.
-`;
-}