@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.9

package/out/sandbox/containerDriver.js

@@ -0,0 +1,570 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainerSandboxDriver = exports.SANDBOX_PACK_DIR = exports.SANDBOX_WORKSPACE_DIR = exports.SANDBOX_STATE_DIR = exports.SANDBOX_SOCKET_DIR_IN_SANDBOX = void 0;
+exports.strictEgressFromEnv = strictEgressFromEnv;
+exports.prepareSocketDir = prepareSocketDir;
+exports.assertOwnSocket = assertOwnSocket;
+/**
+ * The `container` driver (tier 2) — one disposable container per session.
+ *
+ * What delivers the boundary, concretely:
+ *  - `--network none` plus one explicit user-defined network per declared route. A sandbox with no
+ *    routes has no network at all; no destination is reachable because a prompt asked nicely.
+ *    The strength of the boundary for a sandbox that DOES declare routes is the topology of those
+ *    networks: `--internal` ones make everything else unroutable, a NAT'd one does not. The driver
+ *    does not create them and cannot make them internal, so it verifies and reports instead of
+ *    asserting — see `assertRouteNetworks`. An inference route to an external proxy is the case
+ *    that cannot be internal, and it is the common one; the disclosure belongs in the deployment.
+ *  - a per-sandbox unix socket bind-mounted ONLY into that container. Reaching the socket ⇔ being
+ *    the sandbox, so the channel is the sandbox's identity — no certificates needed at this tier.
+ *  - the image is pinned BY DIGEST; a mutable tag would make the signing and rollback story false.
+ *  - the container holds no secret: `spec.env` is non-secret only, and the per-sandbox model token
+ *    rides the run frame instead of the environment.
+ *
+ * The docker CLI is injected so this class is testable without a daemon; a live smoke test is
+ * the acceptance gate for the driver itself.
+ *
+ * **Platform note (verified 2026-07-25):** the socket channel requires a Linux host. On macOS
+ * Docker Desktop the sandbox binds its socket fine and connects to it from *inside* the container,
+ * but the host cannot connect through the VM's file-sharing layer (`ECONNREFUSED`) — unix
+ * sockets do not traverse virtiofs/gRPC-FUSE. Production targets (VM, Cloud Run, K8s) are all
+ * Linux, so this affects local development on macOS only; use the `process` driver there.
+ */
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const net = __importStar(require("node:net"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const types_1 = require("./types");
+/**
+ * Read the strict-egress opt-in from the environment.
+ *
+ * Env rather than a constructor argument so a deployment can turn it on without the composition
+ * root having to thread a flag; the driver still accepts an explicit override for tests.
+ */
+function strictEgressFromEnv(env = process.env) {
+    return env.AGENTHIPPO_SANDBOX_STRICT_EGRESS === '1';
+}
+/**
+ * Where per-sandbox unix sockets live on the HOST.
+ *
+ * `/run/agenthippo/sandboxes` is the right default — `/run` is tmpfs, so a killed serve leaves
+ * no stale socket files across a reboot. But `/run` is root-owned, and serve running as an
+ * ordinary user cannot create a directory there: every tier-2 turn then dies with
+ * `EACCES: mkdir '/run/agenthippo/sandboxes/…'` (observed on Amazon Linux, 2026-07-27). An
+ * unprivileged runtime must not be un-deployable for want of a directory, so fall back.
+ *
+ * Order: explicit env → `/run/agenthippo/sandboxes` if usable → `$XDG_RUNTIME_DIR` → tmpdir.
+ * Every candidate is kept SHORT on purpose: a unix socket path is capped near 104 bytes on
+ * macOS / 108 on Linux, and the sandbox id plus `/sandbox.sock` is appended to whatever we
+ * return — a deep fallback would fail at bind() with a far less obvious error than this one.
+ */
+function resolveDefaultSocketDir() {
+    const candidates = [
+        process.env.AGENTHIPPO_SANDBOX_SOCKET_DIR,
+        '/run/agenthippo/sandboxes',
+        process.env.XDG_RUNTIME_DIR ? path.join(process.env.XDG_RUNTIME_DIR, 'agenthippo-sandboxes') : undefined,
+        path.join(os.tmpdir(), 'agenthippo-sandboxes'),
+    ].filter((c) => Boolean(c));
+    for (const dir of candidates) {
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            fs.accessSync(dir, fs.constants.W_OK);
+            // Leave room for `/<sandbox-id>/sandbox.sock` (~40 chars) inside the platform limit.
+            if (dir.length > 60) {
+                continue;
+            }
+            return dir;
+        }
+        catch {
+            // Not creatable or not writable by this user — try the next candidate.
+        }
+    }
+    // Nothing worked: return the canonical path so the failure names the intended location
+    // rather than a temp dir the operator never configured.
+    return '/run/agenthippo/sandboxes';
+}
+const DEFAULT_SOCKET_DIR = resolveDefaultSocketDir();
+/** How long a sandbox may take to boot and bind. Pack sync + engine dep checks dominate this. */
+const SOCKET_WAIT_MS = 90_000;
+const SOCKET_POLL_MS = 150;
+/** Where each sandbox's socket directory appears INSIDE the sandbox. The sandbox binds `sandbox.sock` here. */
+exports.SANDBOX_SOCKET_DIR_IN_SANDBOX = '/run/sandbox';
+/**
+ * Canonical in-sandbox paths. These are the `sandbox` command's own defaults (`--state-dir /state`,
+ * so `--workspace` resolves to `/state/workspace`) and the pack directory generated deploy
+ * images use. serve mounts the host workspace and pack ONTO them, so the two sides cannot
+ * drift: without the workspace mount a sandbox's work is container-private and dies with the sandbox.
+ */
+exports.SANDBOX_STATE_DIR = '/state';
+exports.SANDBOX_WORKSPACE_DIR = '/state/workspace';
+exports.SANDBOX_PACK_DIR = '/app/pack';
+class ContainerSandboxDriver {
+    opts;
+    kind = 'container';
+    tier = 2;
+    sandboxes = new Map();
+    seq = 0;
+    /**
+     * Distinguishes THIS serve process's sandboxes from any other's. A bare counter restarts at 1 on
+     * every serve, so a restarted instance reused the previous one's container names AND socket
+     * paths — see the stale-socket note in `create`. Cheap, and it makes two serves on one host
+     * (blue/green, a stray process) safe by construction rather than by luck.
+     */
+    instance = crypto.randomBytes(2).toString('hex');
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async create(spec) {
+        assertPinnedByDigest(spec.image);
+        const id = `sandbox-${this.instance}-${++this.seq}-${sanitize(spec.sessionKey)}`;
+        // One DIRECTORY per sandbox, mounted at a fixed path inside. Docker cannot bind-mount a
+        // socket file that does not exist yet — it would create a directory in its place and the
+        // sandbox's bind() then fails (observed live). The sandbox creates the socket inside its own
+        // mounted directory, which keeps the "only this sandbox's channel" property intact.
+        const socketDir = this.opts.socketDir ?? DEFAULT_SOCKET_DIR;
+        const sandboxSocketDir = path.join(socketDir, id);
+        const socketPath = path.join(sandboxSocketDir, 'sandbox.sock');
+        // Purge first: this directory must contain THIS sandbox's socket and nothing else.
+        // A serve that is killed leaves its sandboxes' `sandbox.sock` files behind (a bound socket file
+        // outlives its process), and `mkdirSync(recursive)` happily adopts such a directory. The
+        // waiter below then sees a socket that exists but has no listener, hands back a handle
+        // immediately, and serve dials a corpse — ECONNREFUSED, reported as the useless "sandbox
+        // channel closed", with the retry landing on the NEXT stale path and failing identically.
+        // Diagnosed live: two containers per turn, both healthy, every turn failing until serve
+        // was restarted. The unique instance id above makes reuse unlikely; this makes it
+        // impossible, including across a serve that died mid-sandbox.
+        fs.rmSync(sandboxSocketDir, { recursive: true, force: true });
+        prepareSocketDir(sandboxSocketDir, this.opts.socketOwner);
+        // Default-deny: the sandbox never joins the default bridge. A sandbox with no declared routes
+        // gets `none`; otherwise it is created directly on its FIRST route's network and the
+        // rest are attached after. Docker refuses `network connect` on a container created in
+        // `none` mode ("cannot be connected to multiple networks with one of the networks in
+        // private (none) mode"), so create-then-attach only works this way — verified live.
+        const routeNetworks = spec.routes.map((r) => ({ kind: r.kind, network: routeNetwork(r.target) }));
+        const egressContained = await this.assertRouteNetworks(routeNetworks);
+        // The tier this sandbox ACTUALLY gets. Tier 2's distinguishing property over tier 1 is that
+        // the sandbox cannot reach a destination it was not routed to; a NAT'd route network hands
+        // it the internet, so the honest report is 1. This value — not `this.tier` — is what the
+        // handle carries and what is stamped into the sandbox's own environment, so no consumer
+        // downstream can claim a containment level that was never built.
+        const effectiveTier = egressContained ? this.tier : 1;
+        const primary = routeNetworks[0];
+        const args = [
+            'run', '--detach', '--name', id,
+            '--network', primary ? primary.network : 'none',
+            // Least privilege, cheap and unconditional.
+            '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges',
+            '--read-only',
+            // A read-only root REQUIRES a writable /tmp. Codex's Linux sandbox shells out to
+            // bubblewrap, which creates a mount registry under /tmp and panics without it
+            // ("failed to create synthetic bubblewrap mount registry … Read-only file system"),
+            // so every shell command and file write inside the sandbox failed. `exec` is required —
+            // bubblewrap execs from there. Observed live on tier 2.
+            '--tmpfs', '/tmp:rw,exec,nosuid,size=512m',
+            // The sandbox's state root must be writable on a read-only rootfs: it holds HOME
+            // (/state/home — engine SDKs write dot-dirs there) and per-engine caches, and the
+            // sandbox exits at boot with `EROFS: mkdir '/state/home'` without it (observed live on
+            // tier 2). mode=1777 (sticky, like /tmp) on the tmpfs form: a fresh tmpfs is
+            // root-owned 0755 and the runtime image runs NON-ROOT, so the sandbox got
+            // `EACCES: mkdir '/state/home'` instead — the same boot failure one step later.
+            //
+            // A per-SESSION host directory replaces the tmpfs when one is given, and that is what
+            // makes session continuity possible at all: `provider-sessions/` and the engines'
+            // own rollout files live under this root, so a tmpfs here means every new sandbox starts
+            // a brand-new engine thread and the conversation silently restarts (the §8.4 resume
+            // gate — it failed 100% of the time before this). Sandboxes stay disposable; the SESSION's
+            // state is what survives them.
+            ...(spec.stateDir
+                ? ['--volume', `${spec.stateDir}:${exports.SANDBOX_STATE_DIR}`]
+                : ['--tmpfs', `${exports.SANDBOX_STATE_DIR}:rw,exec,nosuid,size=512m,mode=1777`]),
+            // The channel: this sandbox's own socket directory and no other's.
+            '--volume', `${sandboxSocketDir}:${exports.SANDBOX_SOCKET_DIR_IN_SANDBOX}`,
+            '--label', `ai.agenthippo.sandbox=${id}`,
+            '--label', `ai.agenthippo.session=${spec.sessionKey}`,
+            '--label', `ai.agenthippo.tier=${spec.tier}`,
+        ];
+        for (const entry of spec.fs.readonly) {
+            args.push('--volume', mountSpec(entry, true));
+        }
+        for (const entry of spec.fs.writable) {
+            args.push('--volume', mountSpec(entry, false));
+        }
+        if (spec.limits.memMiB) {
+            args.push('--memory', `${spec.limits.memMiB}m`);
+        }
+        if (spec.limits.cpu) {
+            args.push('--cpus', spec.limits.cpu);
+        }
+        for (const [k, v] of Object.entries(spec.env ?? {})) {
+            args.push('--env', `${k}=${v}`);
+        }
+        // Last, so the driver's own tier wins over anything the caller put in `spec.env`. This is
+        // what lets an engine inside the container know a real boundary surrounds it — and what
+        // keeps the tier-0 driver from ever making the same claim.
+        args.push('--env', `${types_1.SANDBOX_TIER_ENV}=${effectiveTier}`);
+        args.push(spec.image);
+        const run = await this.opts.exec(args);
+        if (run.code !== 0) {
+            // A failed `docker run` can still leave the container OBJECT behind (e.g. created,
+            // then failed to start because a declared route network is missing). Without this
+            // sweep the name stays taken and every retry for the same session fails — observed
+            // live. Fail closed AND leave nothing behind.
+            await this.opts.exec(['rm', '--force', id]);
+            throw new Error(`failed to create sandbox ${id}: ${run.stdout.trim() || `exit ${run.code}`}`);
+        }
+        const containerId = run.stdout.trim();
+        // Exactly the declared routes, and nothing else: each route is one user-defined network
+        // the destination also sits on. The primary was attached at create; attach the rest.
+        const networks = new Map();
+        if (primary) {
+            networks.set(primary.kind, primary.network);
+        }
+        for (const route of routeNetworks.slice(1)) {
+            const attach = await this.opts.exec(['network', 'connect', route.network, id]);
+            if (attach.code !== 0) {
+                // Fail closed: a sandbox that came up without one of its declared routes is not the
+                // sandbox that was asked for — tear it down rather than run it half-wired.
+                await this.opts.exec(['rm', '--force', id]);
+                throw new Error(`failed to attach ${route.kind} route for sandbox ${id}: ${attach.stdout.trim()}`);
+            }
+            networks.set(route.kind, route.network);
+        }
+        // `docker run --detach` returns as soon as the container STARTS, but the sandbox only binds
+        // its socket after ensureDeps + pack sync — seconds later. Handing back a handle now made
+        // serve dial a socket that did not exist yet, so the first turn failed with the useless
+        // "sandbox channel closed" and the retry raced a second sandbox into existence (observed live on
+        // tier 2: two containers per turn, both healthy, turn failed). Wait for the socket, and if
+        // the sandbox dies while we wait, surface ITS error instead of a connection failure.
+        await this.waitForSocket(id, socketPath);
+        const sandbox = { containerId, socketPath, networks };
+        if (spec.limits.ttlSeconds > 0) {
+            sandbox.ttl = setTimeout(() => { void this.destroyById(id); }, spec.limits.ttlSeconds * 1000);
+            sandbox.ttl.unref?.();
+        }
+        this.sandboxes.set(id, sandbox);
+        const connect = this.opts.connectFn ?? unixSocketChannel;
+        return {
+            id,
+            tier: effectiveTier,
+            endpoint: socketPath,
+            connect: () => connect(socketPath),
+        };
+    }
+    /**
+     * Check each declared route network BEFORE `docker run`, and say what is actually wrong.
+     *
+     * Two different failures used to look identical (`docker run` exits non-zero, container object
+     * left behind, sandbox creation fails on the first turn):
+     *  - the network does not exist, because nothing in the deployment ever created it. Nothing in
+     *    this codebase creates route networks; that is the operator's job, so the error must say so.
+     *  - the network exists but is NOT internal, i.e. it is NAT'd to the internet. The sandbox then
+     *    reaches arbitrary hosts, and the tier's "unroutable by construction" property is simply
+     *    not delivered. That is a disclosure, not a refusal: an inference route to an external
+     *    proxy CANNOT be internal, so refusing here would forbid the normal deployment. Say it out
+     *    loud instead of letting the claim stand unverified.
+     *
+     * Two things changed after this was audited. First, `AGENTHIPPO_SANDBOX_STRICT_EGRESS=1` (or
+     * `opts.strictEgress`) turns the disclosure into a REFUSAL, for deployments that need the
+     * containment claim to be true rather than documented. Second — and unconditionally — a
+     * non-internal route network is now reflected in the tier the driver REPORTS
+     * (`effectiveTier`), so nothing downstream can advertise a containment level that is not
+     * being enforced. A warning nobody reads is not a boundary; a tier that reads 1 instead of 2
+     * travels into the warrant and the evidence.
+     *
+     * Returns true when every declared route network is `--internal`.
+     */
+    async assertRouteNetworks(routes) {
+        const checked = new Set();
+        let allInternal = true;
+        for (const route of routes) {
+            if (checked.has(route.network)) {
+                continue;
+            }
+            checked.add(route.network);
+            const res = await this.opts.exec(['network', 'inspect', '--format', '{{.Internal}}', route.network]);
+            if (res.code !== 0) {
+                throw new Error(`route network "${route.network}" (${route.kind}) does not exist — a tier-2 sandbox is ` +
+                    `created on its declared route networks and nothing creates them for you. Create it ` +
+                    `(\`docker network create --internal ${route.network}\`) and put the ${route.kind} ` +
+                    `service on it.`);
+            }
+            if (res.stdout.trim() !== 'true') {
+                allInternal = false;
+                const strict = this.opts.strictEgress ?? strictEgressFromEnv();
+                if (strict) {
+                    throw new Error(`route network "${route.network}" (${route.kind}) is not --internal, and strict egress ` +
+                        `containment is enabled (AGENTHIPPO_SANDBOX_STRICT_EGRESS=1). A sandbox on this network ` +
+                        `can reach any host it routes to, so the tier-2 containment claim would be false. ` +
+                        `Recreate it as internal (\`docker network rm ${route.network} && docker network create ` +
+                        `--internal ${route.network}\`), or unset AGENTHIPPO_SANDBOX_STRICT_EGRESS to accept a ` +
+                        `sandbox whose egress is bounded by the network topology instead.`);
+                }
+                this.opts.logger?.warn(`route network "${route.network}" (${route.kind}) is not --internal: this sandbox can ` +
+                    `reach any host that network routes to, so tier-2 egress is bounded by that network's ` +
+                    `topology, not by the sandbox. This sandbox is therefore reported as tier 1, not tier 2. ` +
+                    `Make the network internal (or set AGENTHIPPO_SANDBOX_STRICT_EGRESS=1 to refuse outright).`);
+            }
+        }
+        return allInternal;
+    }
+    /**
+     * Block until the sandbox has bound its socket, or fail with the reason it never did.
+     *
+     * A sandbox that dies during boot (EROFS on a read-only /state, an unwritable workspace mount,
+     * a missing pack) must report THAT, not a downstream connect error — every one of those was
+     * diagnosed live only by hand-reading `docker logs`, which no operator should have to do.
+     *
+     * Readiness is NOT "the path exists". `fs.existsSync` is true for a regular file, a symlink, or
+     * a socket some other local account bound at the predictable path first; each of those is a
+     * different sandbox answering for this one. `assertOwnSocket` decides.
+     */
+    async waitForSocket(id, socketPath) {
+        const budgetMs = this.opts.socketWaitMs ?? SOCKET_WAIT_MS;
+        // 0 disables the wait outright — for tests that stub the channel and never bind a socket.
+        if (budgetMs <= 0) {
+            return;
+        }
+        const deadline = Date.now() + budgetMs;
+        while (Date.now() < deadline) {
+            if (fs.existsSync(socketPath)) {
+                try {
+                    assertOwnSocket(socketPath, this.opts.socketOwner);
+                }
+                catch (err) {
+                    await this.opts.exec(['rm', '--force', id]);
+                    throw err;
+                }
+                return;
+            }
+            // Cheap liveness check: a dead container will never bind, so stop waiting on it.
+            const state = await this.opts.exec(['inspect', '--format', '{{.State.Running}}', id]);
+            if (state.stdout.trim() === 'false') {
+                const logs = await this.opts.exec(['logs', '--tail', '20', id]);
+                await this.opts.exec(['rm', '--force', id]);
+                throw new Error(`sandbox ${id} exited during boot: ${combinedOutput(logs)}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, SOCKET_POLL_MS));
+        }
+        const logs = await this.opts.exec(['logs', '--tail', '20', id]);
+        await this.opts.exec(['rm', '--force', id]);
+        throw new Error(`sandbox ${id} did not bind ${socketPath} within ${budgetMs / 1000}s: ${combinedOutput(logs)}`);
+    }
+    /**
+     * Detaching the route's network is a real, immediate boundary change — the sandbox's next
+     * connection to that destination fails to route. This is how a cost cap is enforced
+     * non-cooperatively: the agent cannot reach around a route it no longer has.
+     */
+    async revoke(handle, what) {
+        const sandbox = this.sandboxes.get(handle.id);
+        if (!sandbox) {
+            return;
+        }
+        if (what === 'all') {
+            return this.destroyById(handle.id);
+        }
+        const network = sandbox.networks.get(what);
+        if (!network) {
+            throw new types_1.RevocationUnsupportedError('container', what);
+        }
+        const res = await this.opts.exec(['network', 'disconnect', '--force', network, handle.id]);
+        if (res.code !== 0) {
+            throw new Error(`failed to revoke ${what} for sandbox ${handle.id}: ${res.stdout.trim()}`);
+        }
+        sandbox.networks.delete(what);
+    }
+    async destroy(handle) {
+        await this.destroyById(handle.id);
+    }
+    async destroyById(id) {
+        const sandbox = this.sandboxes.get(id);
+        if (!sandbox) {
+            return;
+        }
+        this.sandboxes.delete(id);
+        if (sandbox.ttl) {
+            clearTimeout(sandbox.ttl);
+        }
+        await this.opts.exec(['rm', '--force', id]);
+        // The socket directory is this sandbox's; it dies with the sandbox.
+        try {
+            fs.rmSync(path.dirname(sandbox.socketPath), { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+exports.ContainerSandboxDriver = ContainerSandboxDriver;
+/**
+ * Create this sandbox's socket directory with the tightest mode that still lets the sandbox bind.
+ *
+ * What was wrong with the previous `0o733`: write+execute for OTHER, no sticky bit, at a
+ * PREDICTABLE path. Any local unprivileged account could therefore create `sandbox.sock` in that
+ * directory before the sandbox did, win the bind, and receive the `run` frame — which carries the
+ * ES256 inference warrant (`modelToken`) and `turnEnv` with `AGENTHIPPO_TURN_NONCE`, the acting
+ * user's data-plane capability. That is: spend the user's inference budget, call their connectors,
+ * and return arbitrary text as the agent's answer.
+ *
+ * Two modes, in order of preference:
+ *
+ *  - **0o700 owned by the sandbox uid** (when the image's uid is known). Nothing but the sandbox
+ *    and root can traverse, list, or create here, so the race has no participants. This is the
+ *    right answer and the reason `resolveSandboxImageUser` exists.
+ *  - **0o1733** otherwise. Still write+execute for other — the container's non-root uid has to be
+ *    able to create the socket and we do not know which uid that is — but the STICKY bit (0o1000)
+ *    means only the file's owner (or root) may delete or rename an entry in the directory. An
+ *    attacker can no longer replace a socket the sandbox already bound; combined with the
+ *    post-bind ownership check in `assertOwnSocket`, a pre-created hostile socket is detected
+ *    instead of dialled. `0o700` unconditionally is not an option: the image runs non-root, so
+ *    bind() fails and the sandbox exits (observed live on Linux).
+ */
+function prepareSocketDir(dir, owner) {
+    fs.mkdirSync(dir, { recursive: true });
+    if (owner && owner.uid !== 0) {
+        try {
+            fs.chownSync(dir, owner.uid, owner.gid);
+            fs.chmodSync(dir, 0o700);
+            return;
+        }
+        catch {
+            // Not permitted to chown (serve is not root) — fall through to the sticky mode.
+        }
+    }
+    fs.chmodSync(dir, 0o1733);
+}
+/**
+ * Verify the thing we are about to dial is the sandbox's own socket.
+ *
+ * `lstat` (never `stat`): a symlink planted at the expected path would otherwise be followed to
+ * whatever the attacker chose. Three conditions, all required:
+ *  - it is a socket, not a symlink/file/fifo;
+ *  - it is owned by us or by the sandbox's uid — not by some third local account;
+ *  - it lives in the directory we just created for this sandbox.
+ */
+function assertOwnSocket(socketPath, owner, self = typeof process.getuid === 'function' ? process.getuid() : undefined) {
+    const st = fs.lstatSync(socketPath);
+    if (st.isSymbolicLink()) {
+        throw new Error(`sandbox socket ${socketPath} is a symlink — refusing to connect`);
+    }
+    if (!st.isSocket()) {
+        throw new Error(`sandbox socket ${socketPath} is not a unix socket — refusing to connect`);
+    }
+    const acceptable = new Set();
+    if (self !== undefined) {
+        acceptable.add(self);
+    }
+    if (owner) {
+        acceptable.add(owner.uid);
+    }
+    // Root-owned is always acceptable: a rootful container runtime binds as root.
+    acceptable.add(0);
+    if (!acceptable.has(st.uid)) {
+        throw new Error(`sandbox socket ${socketPath} is owned by uid ${st.uid}, which is neither this process ` +
+            `nor the sandbox — another local user may have raced the bind. Refusing to connect.`);
+    }
+}
+/**
+ * An fs entry is either a plain path (bound at the same path inside the sandbox) or an explicit
+ * `hostPath:sandboxPath` mapping. The mapping form is required in practice: a pack lives at an
+ * arbitrary host path but must appear at a fixed path inside the sandbox.
+ */
+function mountSpec(entry, readOnly) {
+    const idx = entry.indexOf(':');
+    const [src, dst] = idx === -1 ? [entry, entry] : [entry.slice(0, idx), entry.slice(idx + 1)];
+    return `${src}:${dst}${readOnly ? ':ro' : ''}`;
+}
+/**
+ * The image must be pinned by digest. A mutable tag makes pack signing and version rollback
+ * unverifiable — the deployment could silently run different bytes than the ones that were
+ * signed (`credential-provenance` conformance check).
+ */
+function assertPinnedByDigest(image) {
+    // Two immutable forms are accepted: a registry digest ref (`repo@sha256:…`, the normal
+    // production case) and a bare image ID (`sha256:…`), which is what a locally built or
+    // air-gapped image is addressed by. Both name exact bytes; a tag does not.
+    const registryDigest = /@sha256:[a-f0-9]{64}$/.test(image);
+    const bareImageId = /^sha256:[a-f0-9]{64}$/.test(image);
+    if (!registryDigest && !bareImageId) {
+        throw new Error(`sandbox image must be pinned by digest (got "${image}") — a mutable tag makes signing and rollback unverifiable`);
+    }
+}
+/** A sandbox reports boot failures on stderr; show both streams or the diagnostic is blank. */
+function combinedOutput(r) {
+    return `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() || '(no output)';
+}
+/**
+ * Loopback means "this container" inside a container, never "the host that configured me".
+ *
+ * A route to 127.0.0.1 is therefore not a route at all: it names a service that cannot exist at
+ * that address from inside the sandbox. Left alone it produced `--network agenthippo-127.0.0.1`,
+ * a network nothing creates, and the whole tier failed at `docker run` with a message about a
+ * missing network rather than about the actual misconfiguration — the in-process data plane and
+ * a local LiteLLM are both loopback by default, so this is the DEFAULT configuration, not a
+ * corner. Refuse at the seam that knows why, and say what to do instead.
+ */
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '0.0.0.0', '[::1]']);
+/** Route target `host:port` → the user-defined network named for that host. */
+function routeNetwork(target) {
+    const host = target.replace(/^\w+:\/\//, '').split(/[:/]/)[0];
+    if (LOOPBACK_HOSTS.has(host.toLowerCase())) {
+        throw new Error(`route target "${target}" is loopback, which inside a sandbox means the sandbox itself — ` +
+            `a tier-2 sandbox cannot reach a service on the host this way. Give the service a name ` +
+            `the sandbox can resolve (a compose service name, or host.docker.internal) on a network ` +
+            `named agenthippo-<host>, or run this deployment with --sandbox process.`);
+    }
+    return `agenthippo-${host}`;
+}
+function unixSocketChannel(socketPath) {
+    const socket = net.createConnection(socketPath);
+    const closed = new Promise((resolve, reject) => {
+        socket.once('close', () => resolve());
+        // REJECT, so the reason survives. Swallowing this turned every socket-level failure
+        // (ECONNREFUSED on a stale socket, EACCES from a uid mismatch, ENOENT) into the same
+        // blank "sandbox channel closed" — the diagnostic that cost a live debugging session.
+        // The message keeps that prefix because the retry-once path matches on it.
+        socket.once('error', (err) => reject(new Error(`sandbox channel closed: ${err.message}`)));
+    });
+    return {
+        input: socket,
+        output: { write: (chunk) => socket.write(chunk) },
+        closed,
+    };
+}
+function sanitize(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 32) || 'session';
+}