@inflexa-ai/harness 0.1.1

package/dist/sandbox/create-sandbox.js

@@ -0,0 +1,132 @@
+/**
+ * Backend-selected `SandboxClient` factory.
+ *
+ * Docker for local dev, K8s for production — the single place the
+ * `SANDBOX_BACKEND` env decision lives. Injected at the composition root
+ * as a construction-time dependency (see the harness-durable-runtime spec); callers do NOT import a
+ * backend module directly.
+ *
+ * Registry write/clear callbacks are wired here so the per-backend
+ * `createSandbox` / `teardown` implementations stay free of state-layer
+ * coupling (they just call the closures we hand them). `submitExec` and
+ * `awaitExec` are backend-agnostic — they only need the SandboxRef.
+ */
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { clampResources } from "../config/resource-limits.js";
+import { stepWritePrefix } from "../workspace/paths.js";
+import { tryMutation } from "../lib/db-result.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { clearSandboxRef, setSandboxRef } from "../state/index.js";
+import { awaitExec } from "./await-exec.js";
+import { createDockerSandboxOps } from "./docker-client.js";
+import { createK8sSandboxOps } from "./k8s-client.js";
+import { STEP_SUBDIRS } from "./mount-plan.js";
+import { submitExec } from "./submit-exec.js";
+import { toPersistedRef } from "./types.js";
+/**
+ * Assemble `awaitExec`'s options: the liveness probe self-wires from the
+ * backend ops (the poll loop's escalation always has its arbiter under the
+ * client), explicit seam injections in `base` win over the self-wired probe,
+ * and the transport is client-owned — never overridable through the seam bag.
+ * Exported for tests.
+ */
+export function composeAwaitOptions(base, transport, isAlive) {
+    return { isAlive, ...base, transport };
+}
+export function createSandboxClient(config) {
+    const backend = config.backend ?? config.env.backend;
+    const transport = config.transport ?? "poll";
+    const registerSandbox = async (meta, ref) => {
+        unwrapOrThrow(await setSandboxRef(config.pool, meta.runId, meta.stepId, toPersistedRef(ref), meta.execId ?? null));
+    };
+    const ops = backend === "k8s"
+        ? createK8sSandboxOps({
+            image: config.image,
+            cortexBaseUrl: config.cortexBaseUrl,
+            transport,
+            namespace: config.namespace ?? config.env.namespace,
+            sessionPvc: config.sessionPvc,
+            sessionPvcRoot: config.sessionPvcRoot,
+            resolveWorkspaceRoot: config.resolveWorkspaceRoot,
+            libStorePvc: config.libStorePvc,
+            refStorePvc: config.refStorePvc,
+            nodeSelector: config.nodeSelector,
+            tolerations: config.tolerations,
+            runtimeClassName: config.runtimeClassName,
+            registerSandbox,
+        })
+        : createDockerSandboxOps({
+            image: config.image,
+            cortexBaseUrl: config.cortexBaseUrl,
+            transport,
+            resolveWorkspaceRoot: config.resolveWorkspaceRoot,
+            libStorePath: config.libStorePath,
+            refStorePath: config.refStorePath,
+            platform: config.platform,
+            logger: config.logger,
+            registerSandbox,
+        });
+    // Backend-agnostic pre-creation of the writable step tree under the
+    // analysis's resolved workspace root. On Docker that root is the host dir
+    // the container binds; on K8s it lives under the session PVC the sandbox
+    // pod mounts via subPath. mkdir(recursive) is idempotent, so an existing
+    // tree (replay, retry) is not an error.
+    const precreateStepTree = async (meta) => {
+        // A read-only sandbox has no writable step mount — nothing to pre-create.
+        if (meta.readOnly)
+            return;
+        const stepDir = stepWritePrefix({
+            workspaceRoot: config.resolveWorkspaceRoot(meta.analysisId),
+            runId: meta.runId,
+            stepId: meta.stepId,
+        });
+        await mkdir(stepDir, { recursive: true });
+        await Promise.all(STEP_SUBDIRS.map((sub) => mkdir(join(stepDir, sub), { recursive: true })));
+    };
+    // `teardown` needs the registry-clear closure but the SandboxRef alone
+    // doesn't carry runId/stepId. Wrap the backend impl so callers pass the
+    // ref + step coordinates and the wrapper does the clear after the
+    // backend-level removal.
+    const teardown = async (ref) => {
+        unwrapOrThrow(await ops.teardown(ref));
+        // Sandboxes are 1-per-step (see `sandbox-step.ts` body — each child
+        // workflow calls `createSandbox` once then `teardown` once), so the
+        // broad WHERE clause matches exactly one row. If that invariant ever
+        // changes (e.g. a step reuses a sibling's sandbox), this clear must
+        // be scoped to (run, step) to avoid wiping prior steps' provenance.
+        unwrapOrThrow(await tryMutation("createSandbox.teardownClearSandboxRef", async () => {
+            await config.pool.query({
+                text: `UPDATE cortex_step_executions
+            SET sandbox_ref = NULL, exec_id = NULL
+            WHERE sandbox_ref->>'sandboxId' = $1`,
+                values: [ref.sandboxId],
+            });
+        }));
+    };
+    // One arbiter for both surfaces: the client's `isAlive` method and the
+    // poll loop's escalation probe are the same backend inspect.
+    const isAlive = async (ref) => unwrapOrThrow(await ops.isAlive(ref));
+    return {
+        createSandbox: async (meta, identity) => {
+            await precreateStepTree(meta);
+            // Every caller must declare resources — a sandbox with no cpu/memory
+            // request is a semantic error, not something to paper over with a
+            // default (a DBOS replay of a pre-resources workflow input lands here).
+            if (!meta.resources) {
+                throw new Error(`createSandbox: ${meta.analysisId}/${meta.runId}/${meta.stepId} has no resources — every caller must declare cpu/memoryGb`);
+            }
+            // Clamp to cluster ceilings so the pod is always quota-admissible.
+            const resources = clampResources(meta.resources, config.resourceLimits);
+            return unwrapOrThrow(await ops.createSandbox({ ...meta, resources }, identity));
+        },
+        submitExec: async (ref, body) => submitExec(ref, body, config.submitDeps),
+        awaitExec: (ref, execId, emit, deadline) => awaitExec(ref, execId, emit, deadline, composeAwaitOptions(config.awaitOptions, transport, isAlive)),
+        isAlive,
+        teardown,
+        teardownById: async (sandboxId) => unwrapOrThrow(await ops.teardownById(sandboxId)),
+        listManagedSandboxes: async () => unwrapOrThrow(await ops.listManagedSandboxes()),
+    };
+}
+/** Re-exports so consumers import once from this module. */
+export { clearSandboxRef };

package/dist/sandbox/deliver-exec-event.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Ingress-side delivery of a sandbox-server callback onto the per-exec DBOS
+ * topic (`awaitExec`'s recv loop, `await-exec.ts`).
+ *
+ * Exists so an embedder hosting the HTTP callback endpoint never touches the
+ * DBOS SDK itself: `DBOS` is module-singleton state, and an embedder with its
+ * own `node_modules` would import a SECOND, un-launched SDK instance whose
+ * `send` writes nowhere. Routing delivery through the harness pins the call to
+ * the same instance `launchDbos` initialized — and keeps the topic-name format
+ * beside its consumer instead of duplicated in every host.
+ *
+ * HMAC verification is deliberately NOT done here: `awaitExec` verifies inside
+ * the workflow body against the per-sandbox `callbackSecret`, so the ingress
+ * stays secret-free and a forged POST is rejected where the secret lives.
+ */
+import type { ExecEventMessage } from "./types.js";
+/** Topic `awaitExec` listens on for one exec's events and done-marker. */
+export declare function execEventTopic(execId: string): string;
+/**
+ * Send one callback envelope (an event, or a `DoneMarker`-shaped completion
+ * payload) to the workflow awaiting `execId`. The caller derives
+ * `workflowId` via `workflowIdFromExec` and owns HTTP status mapping:
+ * a rejection here is retryable (5xx), a malformed execId is not (4xx).
+ */
+export declare function deliverExecEvent(workflowId: string, execId: string, message: ExecEventMessage): Promise<void>;

package/dist/sandbox/deliver-exec-event.js

@@ -0,0 +1,29 @@
+/**
+ * Ingress-side delivery of a sandbox-server callback onto the per-exec DBOS
+ * topic (`awaitExec`'s recv loop, `await-exec.ts`).
+ *
+ * Exists so an embedder hosting the HTTP callback endpoint never touches the
+ * DBOS SDK itself: `DBOS` is module-singleton state, and an embedder with its
+ * own `node_modules` would import a SECOND, un-launched SDK instance whose
+ * `send` writes nowhere. Routing delivery through the harness pins the call to
+ * the same instance `launchDbos` initialized — and keeps the topic-name format
+ * beside its consumer instead of duplicated in every host.
+ *
+ * HMAC verification is deliberately NOT done here: `awaitExec` verifies inside
+ * the workflow body against the per-sandbox `callbackSecret`, so the ingress
+ * stays secret-free and a forged POST is rejected where the secret lives.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+/** Topic `awaitExec` listens on for one exec's events and done-marker. */
+export function execEventTopic(execId) {
+    return `exec-event:${execId}`;
+}
+/**
+ * Send one callback envelope (an event, or a `DoneMarker`-shaped completion
+ * payload) to the workflow awaiting `execId`. The caller derives
+ * `workflowId` via `workflowIdFromExec` and owns HTTP status mapping:
+ * a rejection here is retryable (5xx), a malformed execId is not (4xx).
+ */
+export async function deliverExecEvent(workflowId, execId, message) {
+    await DBOS.send(workflowId, message, execEventTopic(execId));
+}

package/dist/sandbox/docker-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Docker-backed `createSandbox` / `teardown` / `isAlive`.
+ *
+ * Thin wrapper around `dockerode`. Storage is wired via `HostConfig.Binds`:
+ * a flat read-only mount of the analysis tree at `/{resourceId}`, a nested
+ * read-write mount of the step's artifact dir, and the lib/ref stores at
+ * `/mnt/libs` / `/mnt/refs` when their host paths are configured. Container
+ * paths and lib-store env come from the shared mount plan (`mount-plan.ts`).
+ *
+ * ## Transport and confinement
+ *
+ * The container joins the default bridge and publishes sandbox-server's port to
+ * `127.0.0.1` only, so the host can reach `/exec` but the LAN cannot. What the
+ * sandbox may do *outbound* depends on the transport:
+ *
+ *   - **poll** (default): the sandbox initiates nothing, so it needs no egress.
+ *     The container is created as root with `CAP_NET_ADMIN` and the
+ *     `SANDBOX_EGRESS_FIREWALL` flag; the image's root entrypoint installs
+ *     `iptables -P OUTPUT DROP` (allowing loopback and established return
+ *     traffic) and then `setpriv`-drops to the uid-1000 workload, which can
+ *     neither reach the network nor flush the rules. The host polls
+ *     `GET /exec/{execId}?since={cursor}` over the published port; the reply
+ *     rides the established connection, so polling works with egress hard-blocked.
+ *   - **callback**: the sandbox is *allowed* egress and POSTs signed callbacks to
+ *     `CORTEX_BASE_URL`. It runs as uid 1000 throughout with no `NET_ADMIN` and
+ *     no firewall.
+ *
+ * Either way the workload ends as uid 1000 with `no-new-privileges` and no
+ * effective capabilities.
+ */
+import Docker from "dockerode";
+import type pino from "pino";
+import { ResultAsync } from "neverthrow";
+import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
+import { type SandboxError } from "./sandbox-error.js";
+import type { CreateSandboxMeta, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport } from "./types.js";
+export interface DockerClientConfig {
+    image: string;
+    /** Cortex base URL injected into the sandbox env in callback mode so callbacks land here. Unused in poll mode. */
+    cortexBaseUrl: string;
+    /** Result transport. `poll` (default) confines the sandbox with the egress firewall; `callback` permits egress. */
+    transport?: SandboxTransport;
+    /** Workspace-root resolution seam; each analysis's resolved root is the bind source for its tree mounts. */
+    resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** Host lib store; bind-mounted read-only at `/mnt/libs` when set. */
+    libStorePath?: string;
+    /** Host ref store; bind-mounted read-only at `/mnt/refs` when set. */
+    refStorePath?: string;
+    /**
+     * Force the container platform (e.g. `linux/amd64`). Set by hosts that mount
+     * a lib store so the container's arch always matches the store's native
+     * binaries; a local image built for a different arch then fails loudly at
+     * create rather than crashing inside the sandbox.
+     */
+    platform?: string;
+    /** Injected for tests. */
+    docker?: Docker;
+    /** Injected for tests so `/health` polling can be stubbed. */
+    fetch?: typeof fetch;
+    /**
+     * Optional logger so a lib-store degradation (a configured store whose `current`
+     * vanished or went incomplete by sandbox-create time) is observable instead of a
+     * silent libs-mount drop. Matches the `reaper`/`watchdog` logger seam.
+     */
+    logger?: Pick<pino.Logger, "info" | "warn" | "error">;
+    /** Hook called after the registry row is written. */
+    registerSandbox: (meta: CreateSandboxMeta, ref: SandboxRef) => Promise<void>;
+}
+export declare function createDockerSandboxOps(config: DockerClientConfig): {
+    createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
+    teardown(ref: SandboxRef): ResultAsync<void, SandboxError>;
+    teardownById(sandboxId: string): ResultAsync<void, SandboxError>;
+    isAlive(ref: SandboxRef): ResultAsync<SandboxLiveness, SandboxError>;
+    listManagedSandboxes(): ResultAsync<ManagedSandbox[], SandboxError>;
+};

package/dist/sandbox/docker-client.js

@@ -0,0 +1,315 @@
+/**
+ * Docker-backed `createSandbox` / `teardown` / `isAlive`.
+ *
+ * Thin wrapper around `dockerode`. Storage is wired via `HostConfig.Binds`:
+ * a flat read-only mount of the analysis tree at `/{resourceId}`, a nested
+ * read-write mount of the step's artifact dir, and the lib/ref stores at
+ * `/mnt/libs` / `/mnt/refs` when their host paths are configured. Container
+ * paths and lib-store env come from the shared mount plan (`mount-plan.ts`).
+ *
+ * ## Transport and confinement
+ *
+ * The container joins the default bridge and publishes sandbox-server's port to
+ * `127.0.0.1` only, so the host can reach `/exec` but the LAN cannot. What the
+ * sandbox may do *outbound* depends on the transport:
+ *
+ *   - **poll** (default): the sandbox initiates nothing, so it needs no egress.
+ *     The container is created as root with `CAP_NET_ADMIN` and the
+ *     `SANDBOX_EGRESS_FIREWALL` flag; the image's root entrypoint installs
+ *     `iptables -P OUTPUT DROP` (allowing loopback and established return
+ *     traffic) and then `setpriv`-drops to the uid-1000 workload, which can
+ *     neither reach the network nor flush the rules. The host polls
+ *     `GET /exec/{execId}?since={cursor}` over the published port; the reply
+ *     rides the established connection, so polling works with egress hard-blocked.
+ *   - **callback**: the sandbox is *allowed* egress and POSTs signed callbacks to
+ *     `CORTEX_BASE_URL`. It runs as uid 1000 throughout with no `NET_ADMIN` and
+ *     no firewall.
+ *
+ * Either way the workload ends as uid 1000 with `no-new-privileges` and no
+ * effective capabilities.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import Docker from "dockerode";
+import { ResultAsync, err, ok } from "neverthrow";
+import { stepWritePrefix } from "../workspace/paths.js";
+import { trySandbox } from "./sandbox-error.js";
+import { buildMountPlan } from "./mount-plan.js";
+/** Read the originating HTTP status off any `SandboxError` variant that carries one. */
+function statusOf(e) {
+    return "status" in e ? e.status : undefined;
+}
+const SANDBOX_SERVER_PORT = 8765;
+const HEALTH_TIMEOUT_MS = 30_000;
+/** Only this process dials the published port; binding it on every host interface would expose `/exec` to the LAN. */
+const SANDBOX_PORT_HOST_IP = "127.0.0.1";
+/** Matches `USER sandbox` (uid/gid 1000) in the sandbox images — the callback-mode workload user. */
+const SANDBOX_USER = "1000:1000";
+/**
+ * Poll mode starts the container as root so the entrypoint can install the
+ * egress firewall; the entrypoint then `setpriv`-drops to uid 1000, so the
+ * workload still runs unprivileged. sandbox-server refuses to start as root
+ * when the firewall flag is set, so an image whose entrypoint skips the drop
+ * fails at create time rather than running privileged and unconfined.
+ */
+const SANDBOX_ROOT_USER = "0:0";
+const HEALTH_POLL_MS = 250;
+const MANAGED_BY_LABEL = "app.kubernetes.io/managed-by";
+const MANAGED_BY_VALUE = "cortex";
+const OWNER_WORKFLOW_LABEL = "cortex/owner-workflow-id";
+const RUN_ID_LABEL = "cortex/run-id";
+const STEP_ID_LABEL = "cortex/step-id";
+/**
+ * Whether the lib store's `current` resolves to a COMPLETE, usable version, not merely a
+ * present symlink. By sandbox-create time `current` may be gone (concurrent prune/`rm`), a
+ * dangling symlink (its target pruned), or an incomplete tree. Binding a missing source
+ * makes Docker auto-create a root-owned dir (bricking a later store refresh); binding a broken
+ * one mounts broken content. Require a resolved directory carrying both completeness
+ * markers `activate` writes before it flips the pointer.
+ */
+function libStoreUsable(libStorePath) {
+    const current = join(libStorePath, "current");
+    try {
+        // statSync FOLLOWS the symlink, so a dangling `current` throws here and is rejected.
+        if (!statSync(current).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return existsSync(join(current, "packages.txt")) && existsSync(join(current, "meta.json"));
+}
+async function pollHealth(fetchImpl, url, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastErr;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetchImpl(url);
+            if (res.status === 200)
+                return;
+            lastErr = new Error(`/health returned ${res.status}`);
+        }
+        catch (err) {
+            lastErr = err;
+        }
+        await new Promise((r) => setTimeout(r, HEALTH_POLL_MS));
+    }
+    throw new Error(`sandbox /health did not return 200 within ${timeoutMs}ms: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+}
+/**
+ * Create the container, or adopt the one already standing under this
+ * checkpointed name (a recovery re-run, see the harness-sandbox-exec spec). A
+ * running container is adopted as-is; a stopped prior attempt is removed and
+ * recreated. A 409 whose container belongs to a different workflow is a refused
+ * name collision — never adopt or remove someone else's container.
+ */
+async function createOrAdopt(docker, createOpts, name, ownerWorkflowId, createFailed) {
+    const created = await trySandbox(() => docker.createContainer(createOpts), createFailed);
+    if (created.isOk())
+        return ok({ container: created.value, alreadyRunning: false });
+    if (statusOf(created.error) !== 409)
+        return err(created.error);
+    const existing = docker.getContainer(name);
+    const inspected = await trySandbox(() => existing.inspect(), createFailed);
+    if (inspected.isErr())
+        return err(inspected.error);
+    const info = inspected.value;
+    const owner = info.Config?.Labels?.[OWNER_WORKFLOW_LABEL];
+    if (owner !== ownerWorkflowId) {
+        return err({ type: "name_conflict", op: "docker.createSandbox", sandboxId: name, owner: owner ?? null });
+    }
+    if (info.State.Running)
+        return ok({ container: existing, alreadyRunning: true });
+    const removed = await removeContainerIgnoreMissing(docker, name);
+    if (removed.isErr())
+        return err(removed.error);
+    const recreated = await trySandbox(() => docker.createContainer(createOpts), createFailed);
+    if (recreated.isErr())
+        return err(recreated.error);
+    return ok({ container: recreated.value, alreadyRunning: false });
+}
+function removeContainerIgnoreMissing(docker, sandboxId) {
+    return trySandbox(async () => {
+        const container = docker.getContainer(sandboxId);
+        await container.stop({ t: 5 }).catch(() => { });
+        await container.remove({ force: true, v: true }).catch(() => { });
+    }, (status, cause) => ({
+        type: "teardown_failed",
+        op: "docker.teardown",
+        sandboxId,
+        status,
+        cause,
+    })).orElse((e) => 
+    // A 404 means the container is already gone — an idempotent success.
+    statusOf(e) === 404 ? ok(undefined) : err(e));
+}
+export function createDockerSandboxOps(config) {
+    const docker = config.docker ?? new Docker();
+    const fetchImpl = config.fetch ?? fetch;
+    const transport = config.transport ?? "poll";
+    const pollMode = transport === "poll";
+    return {
+        createSandbox(meta, identity) {
+            return new ResultAsync((async () => {
+                const { sandboxId, callbackSecret } = identity;
+                // Re-check AT sandbox-creation time: `config.libStorePath` was fixed at CLI
+                // boot and the store may have gone away since (see libStoreUsable). Not
+                // usable → skip the mount (sandbox degrades to available:false) and log it,
+                // since an otherwise-silent libs-mount drop is invisible to operators.
+                const libsMounted = !!config.libStorePath && libStoreUsable(config.libStorePath);
+                if (config.libStorePath && !libsMounted) {
+                    config.logger?.warn({ libStorePath: config.libStorePath, sandboxId }, "[docker-client] lib store configured but `current` is missing or incomplete at sandbox creation — mounting no library store (sandbox degrades to available:false)");
+                }
+                const plan = buildMountPlan(meta, {
+                    libs: libsMounted,
+                    refs: !!config.refStorePath,
+                });
+                const hostTreePath = config.resolveWorkspaceRoot(meta.analysisId);
+                // `stepWritePrefix` (not a raw `join`) so the RW bind source runs through
+                // the same id validation as the pre-created step tree — a crafted stepId
+                // cannot escape the resolved root into the container.
+                const hostStepPath = stepWritePrefix({ workspaceRoot: hostTreePath, runId: meta.runId, stepId: meta.stepId });
+                const binds = [
+                    `${hostTreePath}:${plan.readonlyTreePath}:ro`,
+                    ...(plan.writableStepPath ? [`${hostStepPath}:${plan.writableStepPath}:rw`] : []),
+                    ...(libsMounted && config.libStorePath ? [`${config.libStorePath}:${plan.libsPath}:ro`] : []),
+                    ...(config.refStorePath ? [`${config.refStorePath}:${plan.refsPath}:ro`] : []),
+                ];
+                const createFailed = (status, cause) => ({
+                    type: "container_create_failed",
+                    op: "docker.createSandbox",
+                    sandboxId,
+                    status,
+                    cause,
+                });
+                const image = meta.image ?? config.image;
+                // Poll mode never dials out and carries no CORTEX_BASE_URL; it sets the
+                // firewall flag so the root entrypoint installs the egress block before
+                // dropping to uid 1000. Callback mode is the inverse.
+                const env = [
+                    `SANDBOX_TRANSPORT=${transport}`,
+                    `SANDBOX_CALLBACK_SECRET=${callbackSecret}`,
+                    ...(pollMode ? ["SANDBOX_EGRESS_FIREWALL=1"] : [`CORTEX_BASE_URL=${config.cortexBaseUrl}`]),
+                    ...Object.entries(plan.env).map(([k, v]) => `${k}=${v}`),
+                    ...Object.entries(meta.extraEnv ?? {}).map(([k, v]) => `${k}=${v}`),
+                ];
+                const spec = meta.resources;
+                const createOpts = {
+                    name: sandboxId,
+                    ...(config.platform !== undefined && { platform: config.platform }),
+                    Image: image,
+                    Env: env,
+                    User: pollMode ? SANDBOX_ROOT_USER : SANDBOX_USER,
+                    WorkingDir: plan.workingDir,
+                    Labels: {
+                        [MANAGED_BY_LABEL]: MANAGED_BY_VALUE,
+                        [OWNER_WORKFLOW_LABEL]: meta.childWorkflowId,
+                        [RUN_ID_LABEL]: meta.runId,
+                        [STEP_ID_LABEL]: meta.stepId,
+                        role: "sandbox",
+                        "cortex/sandbox-id": sandboxId,
+                    },
+                    ExposedPorts: { [`${SANDBOX_SERVER_PORT}/tcp`]: {} },
+                    HostConfig: {
+                        Binds: binds,
+                        // Published to loopback only: the host reaches `/exec`, the LAN cannot.
+                        PortBindings: {
+                            [`${SANDBOX_SERVER_PORT}/tcp`]: [{ HostIp: SANDBOX_PORT_HOST_IP, HostPort: "0" }],
+                        },
+                        CapDrop: ["ALL"],
+                        // Poll mode grants the ROOT entrypoint exactly what its privileged
+                        // setup needs: NET_ADMIN to install the egress iptables rules,
+                        // SETUID/SETGID for the setpriv uid/gid drop to the workload user
+                        // (setresuid/setresgid fail EPERM without them), and SETPCAP to apply
+                        // setpriv's `--bounding-set=-all`. The entrypoint drops all of them
+                        // before the workload runs — the workload's capability sets end empty
+                        // — and `no-new-privileges` prevents regaining any.
+                        ...(pollMode ? { CapAdd: ["NET_ADMIN", "SETUID", "SETGID", "SETPCAP"] } : {}),
+                        SecurityOpt: ["no-new-privileges"],
+                        NanoCpus: Math.round(spec.cpu * 1e9),
+                        Memory: spec.memoryGb * 1024 ** 3,
+                        AutoRemove: false,
+                    },
+                };
+                const sandbox = await createOrAdopt(docker, createOpts, sandboxId, meta.childWorkflowId, createFailed);
+                if (sandbox.isErr())
+                    return err(sandbox.error);
+                if (!sandbox.value.alreadyRunning) {
+                    const started = await trySandbox(() => sandbox.value.container.start(), createFailed);
+                    if (started.isErr())
+                        return err(started.error);
+                }
+                const inspected = await trySandbox(() => sandbox.value.container.inspect(), createFailed);
+                if (inspected.isErr())
+                    return err(inspected.error);
+                const hostPort = inspected.value.NetworkSettings.Ports?.[`${SANDBOX_SERVER_PORT}/tcp`]?.[0]?.HostPort;
+                if (!hostPort) {
+                    // A container we cannot reach is useless; stop and remove it so a retry
+                    // starts clean rather than colliding with an unroutable name.
+                    (await removeContainerIgnoreMissing(docker, sandboxId)).unwrapOr(undefined);
+                    return err(createFailed(undefined, new Error(`DockerSandbox: no host port mapped for ${SANDBOX_SERVER_PORT}/tcp on ${sandboxId}`)));
+                }
+                const host = SANDBOX_PORT_HOST_IP;
+                const port = Number(hostPort);
+                const healthy = await trySandbox(() => pollHealth(fetchImpl, `http://${host}:${port}/health`, HEALTH_TIMEOUT_MS), createFailed);
+                if (healthy.isErr())
+                    return err(healthy.error);
+                const ref = {
+                    sandboxId,
+                    host,
+                    port,
+                    backend: "docker",
+                    callbackSecret,
+                };
+                const registered = await trySandbox(() => config.registerSandbox(meta, ref), createFailed);
+                if (registered.isErr())
+                    return err(registered.error);
+                return ok(ref);
+            })());
+        },
+        teardown(ref) {
+            return removeContainerIgnoreMissing(docker, ref.sandboxId);
+        },
+        teardownById(sandboxId) {
+            return removeContainerIgnoreMissing(docker, sandboxId);
+        },
+        listManagedSandboxes() {
+            return trySandbox(() => docker.listContainers({
+                all: true,
+                filters: { label: [`${MANAGED_BY_LABEL}=${MANAGED_BY_VALUE}`] },
+            }), (status, cause) => ({
+                type: "liveness_failed",
+                op: "docker.listManagedSandboxes",
+                status,
+                cause,
+            })).map((containers) => containers
+                .map((c) => {
+                const labels = c.Labels ?? {};
+                return {
+                    sandboxId: labels["cortex/sandbox-id"] ?? "",
+                    ownerWorkflowId: labels[OWNER_WORKFLOW_LABEL] ?? null,
+                    // Docker reports `Created` as unix seconds.
+                    createdAtMs: typeof c.Created === "number" ? c.Created * 1000 : null,
+                };
+            })
+                .filter((s) => s.sandboxId.length > 0));
+        },
+        isAlive(ref) {
+            return trySandbox(async () => {
+                const info = await docker.getContainer(ref.sandboxId).inspect();
+                const oomKilled = info.State.OOMKilled === true;
+                // A running container is a reachable sandbox: the host dials its
+                // published loopback port directly.
+                return { alive: info.State.Running === true, oomKilled };
+            }, (status, cause) => ({
+                type: "liveness_failed",
+                op: "docker.isAlive",
+                sandboxId: ref.sandboxId,
+                status,
+                cause,
+            })).orElse((e) => 
+            // dockerode throws 404 for a missing container — observably dead.
+            statusOf(e) === 404 ? ok({ alive: false, oomKilled: false }) : err(e));
+        },
+    };
+}

package/dist/sandbox/estimate-data-profile-resources.d.ts

@@ -0,0 +1,5 @@
+import type { ResourceSpec } from "../config/resource-limits.js";
+export declare function estimateDataProfileResources(files: ReadonlyArray<{
+    relativePath: string;
+    size: number;
+}>): ResourceSpec;

package/dist/sandbox/estimate-data-profile-resources.js

@@ -0,0 +1,73 @@
+const EXPANSION = {
+    csv: 8,
+    tsv: 8,
+    txt: 8,
+    json: 8,
+    jsonl: 8,
+    ndjson: 8,
+    xlsx: 15,
+    xls: 15,
+    gz: 12,
+    bz2: 12,
+    zip: 12,
+    xz: 12,
+    zst: 12,
+    parquet: 4,
+    feather: 4,
+    arrow: 4,
+    orc: 4,
+    h5: 4,
+    hdf5: 4,
+    nc: 4,
+    mat: 4,
+    npy: 4,
+    npz: 4,
+    bam: 2,
+    cram: 2,
+    sam: 2,
+    vcf: 2,
+    bcf: 2,
+    bed: 2,
+    gff: 2,
+    gtf: 2,
+    fastq: 2,
+    fasta: 2,
+    fa: 2,
+    fq: 2,
+    rds: 6,
+    rdata: 6,
+    rda: 6,
+    pdf: 1,
+    png: 1,
+    jpg: 1,
+    jpeg: 1,
+    svg: 1,
+    html: 1,
+    md: 1,
+};
+// Unknown / extensionless files default to 6× in-memory expansion.
+const DEFAULT_FACTOR = 6;
+function factorFor(relativePath) {
+    const base = relativePath.slice(relativePath.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    if (dot <= 0)
+        return DEFAULT_FACTOR;
+    return EXPANSION[base.slice(dot + 1).toLowerCase()] ?? DEFAULT_FACTOR;
+}
+export function estimateDataProfileResources(files) {
+    if (files.length === 0)
+        return { cpu: 1, memoryGb: 2 };
+    let largest = files[0];
+    let totalBytes = 0;
+    for (const f of files) {
+        totalBytes += f.size;
+        if (f.size > largest.size)
+            largest = f;
+    }
+    const memoryGb = Math.max(2, Math.ceil(2 + (largest.size * factorFor(largest.relativePath)) / 1e9));
+    let cpu = totalBytes < 100 * 1e6 ? 1 : totalBytes < 1e9 ? 2 : totalBytes < 10 * 1e9 ? 4 : 8;
+    if (files.length >= 8)
+        cpu += 1;
+    cpu = Math.max(1, cpu);
+    return { cpu, memoryGb };
+}

package/dist/sandbox/exec-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `execId` parsing — execId is `${workflowId}:${stepId}:${fnId}` where the
+ * workflowId portion itself contains exactly one colon (child workflow ids
+ * are `${analysisId}:${runId}-${stepIdx}`, parent ids are
+ * `${analysisId}:${runId}`). `indexOf(":")` / `split(":")[0]` over an
+ * execId would stop INSIDE the workflowId and return only the analysisId,
+ * which `DBOS.send` would treat as a wrong-workflow target. Strip the last
+ * two colon-delimited segments (`:${stepId}:${fnId}`) to recover the
+ * workflowId. `stepId` is a plan-defined slug and `fnId` is `fn-${n.toString(36)}`,
+ * neither of which can contain colons.
+ */
+export declare function workflowIdFromExec(execId: string): string | null;