@namzu/sandbox 1.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @namzu/sandbox
+
+Pluggable sandbox provider for [`@namzu/sdk`](../sdk). Four tiers,
+each backed by the industrial-standard primitive for that
+deployment shape. Same `SandboxProvider` surface the SDK consumes
+across all of them — swapping tiers is a config change, not an
+integration rewrite.
+
+## Tier matrix (2026 industrial standard)
+
+| Tier | Use case | Primitive | Cold-start | Local dev |
+|---|---|---|---|---|
+| `process` | Agent runs on the developer's own host (Claude Code-style "don't read `~/.ssh`") | bubblewrap (Linux/WSL2) or Seatbelt (macOS), via [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) | Process spawn (~ms) | Native — no infra |
+| `container` (`docker`) | App in `docker compose` locally or single-tenant prod replica | OCI container, seccomp default profile, tmpfs workdir, no-network default | 0.5–2s | `docker compose up` |
+| `container` (`runsc`) | Trusted-tenant SaaS — what OpenAI Code Interpreter and [Modal](https://modal.com/blog/gvisor-savings-article) ship | Google [gVisor](https://gvisor.dev/docs) userspace kernel as Docker runtime | container start + ~100ms | Linux Docker only (no Docker Desktop on macOS) |
+| `microvm` (`e2b`) | Adversarial multi-tenant SaaS, Python-REPL workloads | Firecracker microVM via [E2B](https://e2b.dev/docs/sandbox) managed service | ~150ms (snapshot/restore) | E2B API key from any laptop |
+| `microvm` (`fly-machines`) | Adversarial multi-tenant SaaS, arbitrary tool-call workloads | Firecracker microVM via [Fly Machines](https://fly.io/docs/machines) | 250ms–1s | Fly API token from any laptop |
+| `microvm` (`self-hosted`) | Same threat model, host insists on owning the scheduler | [`firecracker-containerd`](https://github.com/firecracker-microvm/firecracker-containerd) on KVM-enabled Linux | <300ms with snapshot restore | Lima/Colima Linux VM on macOS |
+| `passthrough` | Tests and explicitly trusted environments | Direct host process — no isolation | n/a | n/a |
+
+## Why these tiers (and not others)
+
+The 2026 consensus across production agent platforms (AWS
+Lambda/Fargate, Fly Machines, Replit, E2B, Modal, OpenAI Code
+Interpreter, Anthropic Code Execution, Daytona) bifurcates cleanly
+along the **trust boundary**:
+
+- **Adversarial multi-tenant code execution → Firecracker microVMs.**
+  AWS, Fly, Replit, E2B, Daytona all converged here. The argument
+  is in [Fly's "Sandboxing and Workload Isolation"](https://fly.io/blog/sandboxing-and-workload-isolation)
+  and the [original Firecracker paper](https://www.usenix.org/conference/nsdi20/presentation/agache):
+  KVM-backed VMs are the only mainstream primitive with a
+  kernel-level trust boundary, and `jailer` plus snapshot/restore
+  makes them boot in 125ms.
+- **Trusted-tenant or first-party workloads → gVisor.** Google's
+  GKE Sandbox, Modal, OpenAI Code Interpreter run gVisor's `runsc`.
+  Near-zero cold-start, runs on commodity Linux without nested
+  virt. Tradeoff: a userspace-kernel CVE is a tenant escape; a
+  Firecracker CVE generally is not.
+- **Single-user dev workstation → bubblewrap / Seatbelt.** What
+  Anthropic itself ships with Claude Code via
+  `@anthropic-ai/sandbox-runtime`. The threat model is "don't let
+  the agent read `~/.ssh` or run `rm -rf ~`," not "tenant A vs
+  tenant B." Process-spawn cold-start.
+- **Single-tenant or co-trusted tenants → plain Docker + seccomp.**
+  Northflank, Railway, Render, Compass-platform, GitHub Actions
+  runners. Adequate when the model is your model and the user is
+  your customer; insufficient when the prompt is the attacker.
+
+`@namzu/sandbox` exposes all four as separate tiers so the host
+picks the trust boundary that matches its threat model.
+
+**What we deliberately do NOT build** is yet-another Firecracker
+scheduler. That is E2B's and Fly's entire product, and writing
+our own would be a years-long detour. We adapt to theirs and
+reserve the `self-hosted` option for hosts that need to own the
+scheduler for compliance or air-gap reasons.
+
+## Cloud portability
+
+The interface is cloud-agnostic. `docker` works on every cloud,
+`e2b` and `fly-machines` are managed services not tied to any
+cloud, `runsc` and `firecracker:self-hosted` need infrastructure
+the host chooses (GKE Sandbox, AWS Fargate, self-hosted KVM, etc.).
+Picking a stronger backend may imply picking a different cloud —
+that's the host's call, not the SDK's.
+
+## Egress allowlist policy
+
+Every backend supports the same `EgressPolicy` shape:
+
+```ts
+type EgressPolicy =
+  | { kind: 'deny-all' }                                              // default
+  | { kind: 'allow-all' }                                             // tests only
+  | { kind: 'static'; allowedHosts: readonly string[] }
+  | { kind: 'resolver'; resolve: () => Promise<readonly string[]> }
+```
+
+The `resolver` shape is **parameterless on purpose**. Hosts that
+need per-tenant policies bake the tenant identity into the closure
+that constructs the provider — exactly how compass-platform's
+JWT-minting flow already works (the server knows the tenant when
+it issues the JWT, the allowlist claim is baked in there). This
+avoids the "where does the resolver get its context from"
+plumbing problem; the host owns the closure, the SDK runtime
+doesn't have to forward identity through `provider.create`.
+
+## Status
+
+This package is being built out across the `ses_004-native-agentic-runtime-and-sandbox`
+design session in phases. Each phase ships one tier, fully
+implemented + tested + documented:
+
+- ✅ **P3.0** — Public surface (this commit). Backend interfaces,
+  tier discriminator, egress policy. Factory throws
+  `SandboxBackendNotImplementedError` until backends land.
+- ⏳ **P3.1** — `container:docker` backend. Universal local-dev
+  default; ships first.
+- ⏳ **P3.2** — `EgressPolicy` plumbing + reference egress proxy
+  (compass-platform pattern: HTTP CONNECT tunnel + JWT-claim
+  allowlist).
+- ⏳ **P3.3** — `microvm:e2b` and `microvm:fly-machines` adapters.
+  Phase 2 production tier.
+- ⏳ **P3.4** — `process` backend (Anthropic sandbox-runtime
+  adapter — bubblewrap/Seatbelt).
+- ⏳ **P3.5** — `container:runsc` (gVisor) and
+  `microvm:self-hosted` (firecracker-containerd). Phase 3
+  adversarial-multi-tenant.
+
+The interface here is what every backend implements; the staged
+rollout is purely about turning each tier on, not about reshaping
+the contract.
+
+## Usage (post-implementation)
+
+```ts
+import { createSandboxProvider } from '@namzu/sandbox'
+
+// Phase 1: ship now, works on every dev's laptop
+const sandbox = createSandboxProvider({
+  backend: { tier: 'container', runtime: 'docker', image: 'namzu-worker:latest' },
+  defaultEgress: { kind: 'static', allowedHosts: ['api.openai.com', 'api.anthropic.com'] },
+})
+
+// Phase 2: production, adversarial multi-tenant, managed Firecracker
+const sandbox = createSandboxProvider({
+  backend: { tier: 'microvm', service: 'e2b', apiKey: process.env.E2B_API_KEY! },
+  defaultEgress: {
+    kind: 'resolver',
+    resolve: async () => fetchAllowlistForTenant(tenantId),
+  },
+})
+
+// Phase 3: adversarial multi-tenant, self-hosted Firecracker on KVM
+const sandbox = createSandboxProvider({
+  backend: {
+    tier: 'microvm',
+    service: 'self-hosted',
+    firecrackerBinary: '/usr/local/bin/firecracker',
+    kernelImage: '/var/lib/namzu/vmlinux',
+    rootfsImage: '/var/lib/namzu/rootfs.ext4',
+  },
+})
+
+// Wire into drainQuery / agent run config:
+//   sandboxProvider: sandbox
+```

package/dist/backends/aci-standby-pool/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Azure Container Instances Standby Pool backend.
+ *
+ * Sibling of `docker/` — same {@link SandboxBackend} surface, same
+ * worker-HTTP contract, different shipping mechanism. Where docker
+ * `docker run`s a container on a local daemon, this backend PUTs an
+ * `Microsoft.ContainerInstance/containerGroups` resource that
+ * references a pre-warmed `Microsoft.StandbyPool/standbyContainerGroupPools`
+ * resource — Azure hands back a warm ACI in ~1.5 s instead of a
+ * cold 10-30 s spawn. Refill is automatic per the pool's
+ * `refillPolicy`.
+ *
+ * Workspace shipping:
+ *  - Docker uses bind-mounts (`hostDir` source variant).
+ *  - ACI has no host filesystem; this backend ONLY accepts
+ *    `azureFileShare` source variants and translates them to ACI's
+ *    `properties.volumes[] + container.properties.volumeMounts[]`
+ *    shape. The Vandal-side (or any host) provisions per-task
+ *    shares upstream and hands them in via the layout.
+ *
+ * Authentication:
+ *  - Caller supplies a `getArmToken()` async function. Sandbox
+ *    keeps zero auth dependencies (`@azure/identity` etc.) — the
+ *    consumer's runtime owns Managed-Identity / AzureCLI / federated
+ *    credential picking. Token is fetched on every ARM call so a
+ *    short-lived token survives a long-running sandbox.
+ *
+ * Trust model:
+ *  - ACI runs the container in a Microsoft-owned isolation host;
+ *    inside, the worker is a non-root user (image's `USER namzu`).
+ *  - The container group can be subnet-injected (no public IP) when
+ *    `subnetId` is supplied. Without it the IP is public — fine for
+ *    benchmarking, NOT acceptable for production. Caller decides.
+ *  - The Confidential variant of Standby Pools (AMD SEV-SNP TEE) is
+ *    a pool-side knob, not a backend knob — the backend never
+ *    chooses; it just PUTs against whichever pool the caller named.
+ */
+import type { ResolvedContainerSandboxLayout } from '@namzu/sdk';
+import type { SandboxBackend } from '../../index.js';
+/**
+ * Authentication callback. Caller returns a fresh Azure Resource
+ * Manager bearer token (audience `https://management.azure.com/`).
+ * Backend invokes this on every ARM call so a long-running sandbox
+ * survives token rotation.
+ */
+export type ArmTokenProvider = () => Promise<string>;
+export interface ACIStandbyPoolBackendInternalConfig {
+    readonly subscriptionId: string;
+    readonly resourceGroup: string;
+    readonly location: string;
+    /**
+     * Fully-qualified resource ID of the Standby Pool to claim from.
+     * Example:
+     *   /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.StandbyPool/standbyContainerGroupPools/<pool>
+     */
+    readonly standbyPoolResourceId: string;
+    /**
+     * Fully-qualified resource ID of the Container Group Profile the
+     * pool was created against.
+     */
+    readonly containerGroupProfileResourceId: string;
+    /**
+     * Container Group Profile revision the pool's warm instances were
+     * built from. Defaults to 1.
+     */
+    readonly containerGroupProfileRevision?: number;
+    /**
+     * Pre-resolved layout. The backend requires every mount source to
+     * be `azureFileShare`; any other variant throws.
+     */
+    readonly layout: ResolvedContainerSandboxLayout;
+    /**
+     * Authentication callback (see {@link ArmTokenProvider}).
+     */
+    readonly getArmToken: ArmTokenProvider;
+    /**
+     * Optional subnet to inject the container group into (no public IP).
+     * Strongly recommended for production. When omitted, ACI assigns a
+     * public IP — fine for benchmarks, attack-surface for prod.
+     */
+    readonly subnetId?: string;
+    readonly readyPollIntervalMs?: number;
+    readonly readyTimeoutMs?: number;
+    /**
+     * Worker HTTP port (matches the image's listening port). Default 2024.
+     */
+    readonly workerPort?: number;
+    readonly armApiVersion?: string;
+    /**
+     * Prefix for the ACI container group name and the inner worker
+     * container. Defaults to a Namzu-branded label; consumers (e.g.
+     * Vandal) override via env / config to brand their own
+     * deployments. The runtime appends a sandbox id suffix; the
+     * combined name is sanitised to ARM's allowed character set.
+     */
+    readonly containerNamePrefix?: string;
+}
+/**
+ * Build a {@link SandboxBackend} backed by Azure Container Instances
+ * Standby Pool. Construction is synchronous; the ARM PUT happens on
+ * the first `create()`.
+ */
+export declare function buildAciStandbyPoolBackend(config: ACIStandbyPoolBackendInternalConfig): SandboxBackend;
+//# sourceMappingURL=index.d.ts.map

package/dist/backends/aci-standby-pool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/backends/aci-standby-pool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAEX,8BAA8B,EAQ9B,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,cAAc,EAAyB,MAAM,gBAAgB,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;AAEpD,MAAM,WAAW,mCAAmC;IACnD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;IACtC;;;OAGG;IACH,QAAQ,CAAC,+BAA+B,EAAE,MAAM,CAAA;IAChD;;;OAGG;IACH,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAA;IAC/C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAA;IAC/C;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAA;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACrC;AASD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,mCAAmC,GACzC,cAAc,CAQhB"}

package/dist/backends/aci-standby-pool/index.js

@@ -0,0 +1,425 @@
+/**
+ * Azure Container Instances Standby Pool backend.
+ *
+ * Sibling of `docker/` — same {@link SandboxBackend} surface, same
+ * worker-HTTP contract, different shipping mechanism. Where docker
+ * `docker run`s a container on a local daemon, this backend PUTs an
+ * `Microsoft.ContainerInstance/containerGroups` resource that
+ * references a pre-warmed `Microsoft.StandbyPool/standbyContainerGroupPools`
+ * resource — Azure hands back a warm ACI in ~1.5 s instead of a
+ * cold 10-30 s spawn. Refill is automatic per the pool's
+ * `refillPolicy`.
+ *
+ * Workspace shipping:
+ *  - Docker uses bind-mounts (`hostDir` source variant).
+ *  - ACI has no host filesystem; this backend ONLY accepts
+ *    `azureFileShare` source variants and translates them to ACI's
+ *    `properties.volumes[] + container.properties.volumeMounts[]`
+ *    shape. The Vandal-side (or any host) provisions per-task
+ *    shares upstream and hands them in via the layout.
+ *
+ * Authentication:
+ *  - Caller supplies a `getArmToken()` async function. Sandbox
+ *    keeps zero auth dependencies (`@azure/identity` etc.) — the
+ *    consumer's runtime owns Managed-Identity / AzureCLI / federated
+ *    credential picking. Token is fetched on every ARM call so a
+ *    short-lived token survives a long-running sandbox.
+ *
+ * Trust model:
+ *  - ACI runs the container in a Microsoft-owned isolation host;
+ *    inside, the worker is a non-root user (image's `USER namzu`).
+ *  - The container group can be subnet-injected (no public IP) when
+ *    `subnetId` is supplied. Without it the IP is public — fine for
+ *    benchmarking, NOT acceptable for production. Caller decides.
+ *  - The Confidential variant of Standby Pools (AMD SEV-SNP TEE) is
+ *    a pool-side knob, not a backend knob — the backend never
+ *    chooses; it just PUTs against whichever pool the caller named.
+ */
+const DEFAULT_READY_POLL_MS = 500;
+const DEFAULT_READY_TIMEOUT_MS = 60_000;
+const DEFAULT_WORKER_PORT = 2024;
+const DEFAULT_ARM_API_VERSION = '2024-05-01-preview';
+const ARM_BASE = 'https://management.azure.com';
+const DEFAULT_CONTAINER_NAME_PREFIX = 'namzu-task';
+/**
+ * Build a {@link SandboxBackend} backed by Azure Container Instances
+ * Standby Pool. Construction is synchronous; the ARM PUT happens on
+ * the first `create()`.
+ */
+export function buildAciStandbyPoolBackend(config) {
+    return {
+        tier: 'container',
+        name: 'aci-standby-pool',
+        async create(options) {
+            return await spawnAciSandbox(config, options);
+        },
+    };
+}
+/**
+ * Interpret one mount source. ACI accepts two source variants:
+ *   - `azureFileShare` → emit an ACI `volume.azureFile` + matching `volumeMount`.
+ *   - `inImage` → emit NOTHING; the container's own filesystem carries the path.
+ *
+ * Standby-Pool-warm flows MUST use `inImage` because Standby Pool's
+ * claim-time API rejects every `volumes[]` override (the volume set
+ * is profile-baked across all warm instances). Cold-spawn ACI flows
+ * can use either.
+ *
+ * The `hostDir` variant is for docker backends and is rejected here.
+ */
+function interpretSource(source, label) {
+    if (source.type === 'azureFileShare') {
+        return {
+            kind: 'azureFile',
+            source: {
+                storageAccountName: source.storageAccountName,
+                shareName: source.shareName,
+                storageAccountKey: source.storageAccountKey,
+            },
+        };
+    }
+    if (source.type === 'inImage') {
+        return { kind: 'inImage' };
+    }
+    throw new Error(`aci-standby-pool backend cannot consume mount source type ${JSON.stringify(source.type)} for ${label}; expected 'azureFileShare' or 'inImage'. The hostDir variant belongs to the docker backend.`);
+}
+function buildAzureFileVolumesFromLayout(layout) {
+    const volumes = [];
+    const volumeMounts = [];
+    let counter = 0;
+    function add(mount, label, readOnly) {
+        const interpreted = interpretSource(mount.source, label);
+        // `inImage` is a no-op — the image's own filesystem provides
+        // the path. The Standby-Pool-warm flow lives on this branch.
+        if (interpreted.kind === 'inImage')
+            return;
+        const source = interpreted.source;
+        const name = `vol-${label}-${counter++}`;
+        volumes.push({
+            name,
+            azureFile: {
+                shareName: source.shareName,
+                storageAccountName: source.storageAccountName,
+                storageAccountKey: source.storageAccountKey,
+                readOnly,
+            },
+        });
+        volumeMounts.push({
+            name,
+            mountPath: mount.containerPath,
+            readOnly,
+        });
+    }
+    add(layout.outputs, 'outputs', false);
+    if (layout.uploads)
+        add(layout.uploads, 'uploads', true);
+    if (layout.scratch)
+        add(layout.scratch, 'scratch', false);
+    if (layout.toolResults)
+        add(layout.toolResults, 'toolResults', true);
+    if (layout.transcripts)
+        add(layout.transcripts, 'transcripts', true);
+    if (layout.skills) {
+        for (const skill of layout.skills) {
+            add({ source: skill.source, containerPath: skill.containerPath }, `skill-${skill.id}`, true);
+        }
+    }
+    return { volumes, volumeMounts };
+}
+function detectEnvironment() {
+    // ACI containers run Linux. The SandboxEnvironment enum is host-
+    // platform shape, not container internals — we pick the variant
+    // the consumer's code paths expect for a Linux namespace-isolated
+    // worker.
+    return 'linux-namespace';
+}
+let _sandboxIdCounter = 0;
+function generateSandboxId() {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 8);
+    _sandboxIdCounter += 1;
+    return `sbx_${ts}_${rand}_${_sandboxIdCounter}`;
+}
+async function armCall(url, method, getToken, body) {
+    const token = await getToken();
+    const init = {
+        method,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'content-type': 'application/json',
+        },
+    };
+    if (body !== undefined) {
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`ARM ${method} ${url} → ${res.status}: ${text}`);
+    }
+    if (res.status === 204 || res.status === 202)
+        return undefined;
+    const ct = res.headers.get('content-type') ?? '';
+    if (ct.includes('application/json')) {
+        return (await res.json());
+    }
+    return undefined;
+}
+async function spawnAciSandbox(config, _options) {
+    const id = generateSandboxId();
+    const prefix = config.containerNamePrefix ?? DEFAULT_CONTAINER_NAME_PREFIX;
+    const cgName = `${prefix}-${id
+        .replace(/[^a-z0-9-]/gi, '')
+        .toLowerCase()
+        .slice(0, 50)}`;
+    const apiVersion = config.armApiVersion ?? DEFAULT_ARM_API_VERSION;
+    const workerPort = config.workerPort ?? DEFAULT_WORKER_PORT;
+    const armUrl = `${ARM_BASE}/subscriptions/${config.subscriptionId}/resourceGroups/${config.resourceGroup}/providers/Microsoft.ContainerInstance/containerGroups/${cgName}?api-version=${apiVersion}`;
+    const { volumes, volumeMounts } = buildAzureFileVolumesFromLayout(config.layout);
+    // Standby Pool's claim API rejects every property override that
+    // is NOT a `configMap`. The empty / no-mount cases (every source
+    // is `inImage`) MUST therefore omit `containers`, `volumes`, and
+    // `volumeMounts` entirely from the PUT body — even an empty
+    // array trips the BadRequest "ContainerGroup properties other
+    // than config map are not allowed" check. The fields land only
+    // when something real needs to ride through (e.g. cold-spawn ACI
+    // with per-task azureFileShare mounts, future flow).
+    const properties = {
+        containerGroupProfile: {
+            id: config.containerGroupProfileResourceId,
+            revision: config.containerGroupProfileRevision ?? 1,
+        },
+        standbyPoolProfile: {
+            id: config.standbyPoolResourceId,
+        },
+        ...(config.subnetId ? { subnetIds: [{ id: config.subnetId }] } : {}),
+    };
+    if (volumes.length > 0) {
+        properties.volumes = volumes;
+        properties.containers = [
+            {
+                name: `${prefix}-worker`,
+                properties: { volumeMounts },
+            },
+        ];
+    }
+    const body = {
+        location: config.location,
+        properties,
+    };
+    let claimed;
+    try {
+        claimed = await armCall(armUrl, 'PUT', config.getArmToken, body);
+    }
+    catch (err) {
+        throw new Error(`aci-standby-pool: failed to claim from pool — ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const initialIp = claimed?.properties?.ipAddress?.ip;
+    let ip = initialIp;
+    try {
+        if (!ip) {
+            ip = await pollForRunningIp(armUrl, config.getArmToken, config.readyPollIntervalMs ?? DEFAULT_READY_POLL_MS, config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+        }
+        const baseUrl = `http://${ip}:${workerPort}`;
+        await waitForWorkerReady(baseUrl, config.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, config.readyPollIntervalMs ?? DEFAULT_READY_POLL_MS);
+        let status = 'ready';
+        const rootDir = config.layout.outputs.containerPath;
+        return {
+            id,
+            get status() {
+                return status;
+            },
+            rootDir,
+            environment: detectEnvironment(),
+            async exec(command, argv, opts) {
+                status = 'busy';
+                try {
+                    return await execViaWorker(baseUrl, command, argv, opts);
+                }
+                finally {
+                    status = 'ready';
+                }
+            },
+            async writeFile(path, content) {
+                const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+                const res = await fetch(`${baseUrl}/write-file`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({
+                        path,
+                        content: buf.toString('base64'),
+                        encoding: 'base64',
+                    }),
+                });
+                if (!res.ok) {
+                    throw new Error(`write-file failed: HTTP ${res.status} ${await res.text()}`);
+                }
+            },
+            async readFile(path) {
+                const res = await fetch(`${baseUrl}/read-file`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ path, encoding: 'base64' }),
+                });
+                if (!res.ok) {
+                    throw new Error(`read-file failed: HTTP ${res.status} ${await res.text()}`);
+                }
+                const json = (await res.json());
+                if (!json.ok || typeof json.content !== 'string') {
+                    throw new Error(json.error ?? 'read-file: no content');
+                }
+                return Buffer.from(json.content, 'base64');
+            },
+            async listFiles(rootPath) {
+                return await listFilesViaWorker(baseUrl, rootPath);
+            },
+            async destroy() {
+                status = 'destroyed';
+                // ARM DELETE — let failures propagate. The Vandal-side
+                // lifecycle wraps this in its own try/catch with logging,
+                // so a silently swallowed error here means orphan ACI
+                // container groups pile up under the resource group with
+                // no observability handle. The Standby Pool's refill keeps
+                // the WARM side topped up; that has nothing to do with
+                // cleaning up a CLAIMED instance, which is exclusively the
+                // claimer's responsibility.
+                await armCall(armUrl, 'DELETE', config.getArmToken);
+            },
+        };
+    }
+    catch (err) {
+        try {
+            await armCall(armUrl, 'DELETE', config.getArmToken);
+        }
+        catch {
+            // Preserve the readiness failure as the primary error; the
+            // caller cannot use a Sandbox handle yet, so best-effort ARM
+            // cleanup is the only reliable orphan-prevention hook here.
+        }
+        throw err;
+    }
+}
+async function pollForRunningIp(armUrl, getToken, pollIntervalMs, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const cg = await armCall(armUrl, 'GET', getToken);
+        const state = cg?.properties?.provisioningState;
+        const ip = cg?.properties?.ipAddress?.ip;
+        if (state === 'Succeeded' && ip)
+            return ip;
+        if (state === 'Failed') {
+            throw new Error('aci-standby-pool: container group provisioning failed');
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new Error(`aci-standby-pool: timed out waiting for container group IP (${timeoutMs}ms)`);
+}
+async function waitForWorkerReady(baseUrl, timeoutMs, pollIntervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`${baseUrl}/healthz`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            if (res.ok)
+                return;
+        }
+        catch {
+            // Network not ready yet, try again.
+        }
+        await new Promise((r) => setTimeout(r, pollIntervalMs));
+    }
+    throw new Error(`aci-standby-pool: worker /healthz never responded (${timeoutMs}ms)`);
+}
+async function execViaWorker(baseUrl, command, argv, opts) {
+    const start = Date.now();
+    const res = await fetch(`${baseUrl}/execute`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            command,
+            args: argv ?? [],
+            cwd: opts?.cwd,
+            env: opts?.env,
+            timeoutMs: opts?.timeout,
+        }),
+    });
+    if (!res.ok || !res.body) {
+        throw new Error(`execute failed: HTTP ${res.status} ${await res.text()}`);
+    }
+    let stdout = '';
+    let stderr = '';
+    let exitCode = -1;
+    let timedOut = false;
+    const decoder = new TextDecoder();
+    const reader = res.body.getReader();
+    let buffered = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buffered += decoder.decode(value, { stream: true });
+        let newlineIdx = buffered.indexOf('\n');
+        while (newlineIdx !== -1) {
+            const line = buffered.slice(0, newlineIdx).trim();
+            buffered = buffered.slice(newlineIdx + 1);
+            if (line) {
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'stdout_delta')
+                        stdout += event.data;
+                    else if (event.type === 'stderr_delta')
+                        stderr += event.data;
+                    else if (event.type === 'result') {
+                        exitCode = event.exitCode;
+                        timedOut = event.timedOut;
+                    }
+                    else if (event.type === 'error') {
+                        throw new Error(event.error);
+                    }
+                }
+                catch (err) {
+                    if (!(err instanceof SyntaxError))
+                        throw err;
+                }
+            }
+            newlineIdx = buffered.indexOf('\n');
+        }
+    }
+    return {
+        stdout,
+        stderr,
+        exitCode,
+        timedOut,
+        durationMs: Date.now() - start,
+    };
+}
+/**
+ * Recursively list regular files under `rootPath` by shelling out to
+ * the worker's `find` (GNU find on the Debian-based reference image).
+ * `-printf` emits one `<path>\t<size>` line per file; any other
+ * non-zero exit (notably `find: '<root>': No such file or directory`)
+ * is mapped to "empty listing" because the agent legitimately may not
+ * have produced anything in `rootPath` yet.
+ */
+async function listFilesViaWorker(baseUrl, rootPath) {
+    const result = await execViaWorker(baseUrl, 'find', [rootPath, '-type', 'f', '-printf', '%p\t%s\n'], undefined);
+    if (result.exitCode !== 0) {
+        return [];
+    }
+    const entries = [];
+    for (const rawLine of result.stdout.split('\n')) {
+        if (!rawLine)
+            continue;
+        const tab = rawLine.indexOf('\t');
+        if (tab < 0)
+            continue;
+        const path = rawLine.slice(0, tab);
+        const size = Number.parseInt(rawLine.slice(tab + 1), 10);
+        if (!path || !Number.isFinite(size))
+            continue;
+        entries.push({ path, size });
+    }
+    return entries;
+}
+//# sourceMappingURL=index.js.map