@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.9

package/out/cli/commands/pack.js

@@ -44,6 +44,10 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const pack_loader_1 = require("../pack-loader");
 const branding_1 = require("../../branding");
+const warrant_1 = require("../../authority/warrant");
+const signature_1 = require("../../pack/signature");
+const store_1 = require("./store");
+const pack_install_ref_1 = require("../pack-install-ref");
 const BANNER_LINE = '-'.repeat(62);
 async function packCommand(options) {
     const workspace = options.workspace;
@@ -65,9 +69,20 @@ async function packCommand(options) {
             }
             await showPackInfo(options.name, workspace);
             break;
+        case 'sign':
+            await signPackCommand(options);
+            break;
+        case 'verify':
+            await verifyPackCommand(options);
+            break;
+        case 'digest':
+            await digestCommand(options);
+            break;
+        case 'keygen':
+            keygenCommand(options);
+            break;
         case 'install':
-            console.log('Pack installation is not yet implemented.');
-            console.log(`   For now, manually copy your pack to ~/${branding_1.AGENTIDE_DIR_NAME}/agents/<name>/`);
+            await installPackCommand(options);
             break;
         case 'export':
             console.log('Pack export is not yet implemented.');
@@ -79,11 +94,44 @@ async function packCommand(options) {
             console.log('  list      List installed packs');
             console.log('  validate  Validate a pack');
             console.log('  info      Show pack details');
-            console.log('  install   Install a pack (coming soon)');
+            console.log('  sign      Sign a pack so a fleet can verify it before running');
+            console.log('  verify    Verify a pack against trusted public keys');
+            console.log('  digest    Print the pack content digest (what a signature covers)');
+            console.log('  keygen    Generate an ES256 signing keypair');
+            console.log('  install   Install a pack from the store to a folder');
             console.log('  export    Export a pack (coming soon)');
             process.exit(1);
     }
 }
+async function installPackCommand(options) {
+    if (!options.name?.trim()) {
+        console.error('Error: pack slug required.');
+        console.log('Usage: agenthippo pack install <slug>[@version] --to <dir>');
+        console.log('');
+        console.log('Examples:');
+        console.log('  agenthippo pack install joker1 --to ./packs/joker1');
+        console.log('  agenthippo pack install code-reviewer@1.0.0 --to ./packs/code-reviewer');
+        process.exit(1);
+    }
+    const dest = options.to?.trim();
+    if (!dest) {
+        console.error('Error: --to <dir> is required.');
+        console.log('Usage: agenthippo pack install <slug>[@version] --to <dir>');
+        console.log('');
+        console.log('Same download as `agenthippo store install pack/<slug>`, extracted flat for serve/deploy.');
+        process.exit(1);
+    }
+    const { slug, version } = (0, pack_install_ref_1.parsePackInstallRef)(options.name);
+    await (0, store_1.installFromStore)({
+        action: 'install',
+        query: `pack/${slug}${version ? `@${version}` : ''}`,
+        workspace: options.workspace,
+        version,
+        force: options.force,
+        installDir: path.resolve(dest),
+        verbose: options.verbose,
+    });
+}
 async function listPacks(workspace) {
     const packs = (0, pack_loader_1.listAvailablePacks)(workspace);
     if (packs.length === 0) {
@@ -218,3 +266,134 @@ async function showPackInfo(nameOrPath, workspace) {
         process.exit(1);
     }
 }
+// -----------------------------------------------------------------------------
+// Signing
+//
+// Publishing has to be a one-liner before `--require-signed-pack` can be turned
+// on in anger: a requirement nobody can satisfy just gets switched off again.
+// -----------------------------------------------------------------------------
+/** Resolve a pack path and its declared identity — a signature binds both, not just bytes. */
+async function loadForSigning(nameOrPath, workspace) {
+    if (!nameOrPath) {
+        console.error('Error: pack name or path required');
+        process.exit(1);
+    }
+    const packPath = (0, pack_loader_1.resolvePackPath)(nameOrPath, workspace);
+    if (!packPath) {
+        console.error(`Error: pack not found: ${nameOrPath}`);
+        process.exit(1);
+    }
+    const loaded = await (0, pack_loader_1.loadAgentPack)(packPath, workspace);
+    return {
+        packPath: loaded.packPath,
+        name: loaded.manifest.metadata.name,
+        version: loaded.manifest.metadata.version ?? '0.0.0',
+    };
+}
+function keygenCommand(options) {
+    const kid = options.kid || `sign-${new Date().toISOString().slice(0, 10)}`;
+    const key = (0, warrant_1.generateWarrantKeypair)(kid);
+    const out = options.output;
+    if (out) {
+        fs.writeFileSync(out, key.privateKeyPem, { mode: 0o600 });
+        console.log(`Private key written to ${out} (mode 0600) — keep it off shared disks.`);
+    }
+    else {
+        console.log(key.privateKeyPem);
+    }
+    console.log('');
+    console.log(`kid: ${kid}`);
+    console.log('Public half — publish this to the control plane so instances can verify:');
+    console.log(key.publicKeyPem.trim());
+    console.log('');
+    console.log(`  curl -X POST "$CONTROL/api/keys" -H 'content-type: application/json' \\`);
+    console.log(`    -d '{"kid":"${kid}","publicPem":"…"}'`);
+}
+async function signPackCommand(options) {
+    const { packPath, name, version } = await loadForSigning(options.name, options.workspace);
+    if (!options.key) {
+        console.error('Error: --key <private-key.pem> required. Generate one with: agenthippo pack keygen -o key.pem');
+        process.exit(1);
+    }
+    let privateKeyPem;
+    try {
+        privateKeyPem = fs.readFileSync(options.key, 'utf8');
+    }
+    catch (err) {
+        console.error(`Error: cannot read key ${options.key}: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+        return;
+    }
+    const kid = options.kid;
+    if (!kid) {
+        console.error('Error: --kid <id> required — it is how a verifier finds the public half in JWKS.');
+        process.exit(1);
+    }
+    const { digest } = (0, signature_1.signPack)({ packDir: packPath, pack: name, packVersion: version, privateKeyPem, kid: kid });
+    console.log(`Signed ${name}@${version}`);
+    console.log(`  digest    ${digest}`);
+    console.log(`  key       ${kid}`);
+    console.log(`  written   ${path.join(packPath, signature_1.PACK_SIGNATURE_FILE)}`);
+    console.log('');
+    console.log('Commit pack.sig with the pack: it travels WITH the artifact, and a fleet that');
+    console.log('requires signatures refuses anything whose contents no longer match it.');
+}
+async function verifyPackCommand(options) {
+    const { packPath, name, version } = await loadForSigning(options.name, options.workspace);
+    const token = (0, signature_1.readPackSignature)(packPath);
+    if (!token) {
+        console.error(`UNSIGNED: no ${signature_1.PACK_SIGNATURE_FILE} at ${packPath}`);
+        console.error((0, signature_1.describePackRefusal)({ kind: 'unsigned', detail: `no ${signature_1.PACK_SIGNATURE_FILE}`, pack: name, packVersion: version, packDir: packPath }));
+        process.exit(1);
+    }
+    let keys = {};
+    if (options.keys) {
+        try {
+            keys = JSON.parse(fs.readFileSync(options.keys, 'utf8'));
+        }
+        catch (err) {
+            console.error(`Error: cannot read keys ${options.keys}: ${err instanceof Error ? err.message : err}`);
+            process.exit(1);
+        }
+    }
+    else {
+        const trust = await (0, signature_1.loadPackTrustRoot)({
+            env: options.jwks ? { ...process.env, [signature_1.PACK_JWKS_URL_ENV]: options.jwks } : process.env,
+            leaseUrl: process.env.AGENTHIPPO_LEASE_URL,
+        });
+        for (const w of trust.warnings) {
+            console.error(`Warning: ${w}`);
+        }
+        if (trust.status === 'unavailable') {
+            // Distinct from "no keys configured", and with a different fix. Collapsing the two into
+            // an empty keyring is finding A4 — a 503 read exactly like an unmanaged install.
+            console.error(`REFUSED: a trust root is configured but could not be loaded — ${trust.reason}`);
+            console.error((0, signature_1.describePackRefusal)({
+                kind: 'trust-root-unavailable', detail: trust.reason ?? 'unavailable', pack: name, packVersion: version,
+                packDir: packPath, trustRootHint: trust.url ? `Trust root: ${trust.url}` : undefined,
+            }));
+            process.exit(1);
+        }
+        keys = trust.keys;
+    }
+    if (Object.keys(keys).length === 0) {
+        // "No keys" is a refusal, never a pass: verifying against an empty keyring would report
+        // success for any signature at all.
+        console.error('REFUSED: no trusted public keys. Pass --keys <file>, --jwks <url>, or set AGENTHIPPO_PACK_SIGNING_KEYS.');
+        process.exit(1);
+    }
+    const res = (0, signature_1.verifyPack)(token, keys, { packDir: packPath, pack: name, packVersion: version });
+    if (!res.ok) {
+        console.error(`INVALID: ${res.reason}`);
+        console.error((0, signature_1.describePackRefusal)({ kind: res.kind, detail: res.reason, pack: name, packVersion: version, packDir: packPath }));
+        process.exit(1);
+    }
+    console.log(`OK: ${name}@${version} verified`);
+    console.log(`  digest ${res.claims.digest}`);
+    console.log(`  NOTE: .claude/, .codex/ and .agent-hippo/ ARE covered by this digest — they carry hooks`);
+    console.log('        and other executable content, and were previously outside the signature.');
+}
+async function digestCommand(options) {
+    const { packPath, name, version } = await loadForSigning(options.name, options.workspace);
+    console.log(`${(0, signature_1.computePackDigest)(packPath)}  ${name}@${version}`);
+}

package/out/cli/commands/sandbox.js

@@ -0,0 +1,332 @@
+"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.resolveSandboxWorkspace = resolveSandboxWorkspace;
+exports.isForeignWorkspace = isForeignWorkspace;
+exports.sandboxCommand = sandboxCommand;
+/**
+ * `agenthippo sandbox` — the in-sandbox runner entrypoint (PLAN/serve-v4-clean.md §3–§4).
+ *
+ * This is the process that runs INSIDE a sandbox. It owns the real engine and speaks the frame
+ * protocol out over either a unix socket (the `container` driver) or stdio (the `process`
+ * driver). It holds no credential: the model is reached through `baseUrl` + the per-sandbox
+ * `modelToken` that arrives on each run frame, and data through the gateway URL with a
+ * per-turn nonce. Nothing here can mint authority.
+ */
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const path = __importStar(require("path"));
+const headless_1 = require("../../headless");
+const utils_1 = require("../utils");
+const pack_loader_1 = require("../pack-loader");
+const pack_runtime_1 = require("../pack-runtime");
+const deps_1 = require("../deps");
+const serve_hardening_1 = require("../serve-hardening");
+const runtime_1 = require("../runtime");
+const host_1 = require("../../runner/host");
+/**
+ * The sandbox's OWN workspace is authoritative — never the one on the wire.
+ *
+ * serve sends its HOST workspace path on every run frame. Across a container boundary that path
+ * is meaningless, and honouring it was the bug behind "codex discards the write": the sandbox
+ * mkdir'd serve's host path INSIDE the sandbox and ran the engine there, so every file the engine
+ * wrote landed in a container-private directory — present via ls/cat inside the sandbox during the
+ * turn, absent on the host, gone when the sandbox died. The engine also ran in a directory holding
+ * none of the synced pack content. Proven with a probe: a sandbox handed a workspaceRoot that
+ * exists on no host created it and worked there.
+ *
+ * At tier 0 the two are the same path (serve passes `--workspace`), so nothing changes there.
+ */
+function resolveSandboxWorkspace(_wireRoot, sandboxWorkspace) {
+    return sandboxWorkspace;
+}
+/** True when the wire asked for a workspace this sandbox will not use — worth saying out loud once. */
+function isForeignWorkspace(wireRoot, sandboxWorkspace) {
+    if (!wireRoot) {
+        return false;
+    }
+    return path.resolve(wireRoot) !== path.resolve(sandboxWorkspace);
+}
+/**
+ * Adapts the headless runner to `AgentEngine` so `startRunnerHost` can drive it. The model
+ * credential is *per-run*: the sandbox rebuilds its runner if the token changes (rotation), and
+ * never persists a provider key of its own.
+ */
+class SandboxEngine {
+    defaults;
+    id = 'sandbox';
+    displayName = 'Sandbox runner';
+    runner;
+    builtWith;
+    /** Log the wire/sandbox workspace mismatch once, not once per turn. */
+    warnedWorkspace = false;
+    /** Last native engine session id — rides the terminal frame for resume after sandbox death. */
+    nativeSessionId;
+    constructor(defaults) {
+        this.defaults = defaults;
+    }
+    ensureRunner(opts) {
+        const key = `${opts.baseUrl ?? ''}|${opts.modelToken ?? ''}`;
+        if (this.runner && this.builtWith === key) {
+            return this.runner;
+        }
+        this.runner?.dispose();
+        // The same factory serve builds its own runner with — engine executables, bundled base
+        // prompts and the child env patch all resolve identically on both sides of the boundary.
+        this.runner = (0, pack_runtime_1.createPackRunner)({
+            storagePath: this.defaults.storagePath,
+            analyticsSessionsDir: this.defaults.analyticsSessionsDir,
+            packId: this.defaults.packId,
+            packVersion: this.defaults.packVersion,
+            provenance: () => (0, runtime_1.readProvenanceEnvFromProcess)(),
+            workspaceRoot: this.defaults.workspace,
+            credentials: {
+                baseUrl: opts.baseUrl,
+                litellmApiKey: opts.modelToken,
+                useLiteLLM: Boolean(opts.baseUrl),
+            },
+            claudeCheapModel: this.defaults.claudeCheapModel,
+            omitGatewayToken: true,
+        });
+        this.builtWith = key;
+        return this.runner;
+    }
+    async stream(message, options, emitter, _runtime, signal) {
+        const wire = options;
+        const wireRoot = wire.workspaceRoot;
+        const workspaceRoot = resolveSandboxWorkspace(wireRoot, this.defaults.workspace);
+        if (isForeignWorkspace(wireRoot, workspaceRoot) && !this.warnedWorkspace) {
+            this.warnedWorkspace = true;
+            console.warn(`[sandbox] ignoring workspaceRoot ${wireRoot} from the wire — this sandbox works in ${workspaceRoot}`);
+        }
+        try {
+            fs.mkdirSync(workspaceRoot, { recursive: true });
+            // A sandbox hosts exactly one session, so its working directory IS that session's
+            // workspace. Without the chdir the engine inherits the sandbox process's cwd and a tool
+            // that writes a RELATIVE path (codex runs `sh -lc 'printf ... > proof.txt'`) lands the
+            // file outside the workspace — it exits 0, the agent reports success, work is lost.
+            process.chdir(workspaceRoot);
+        }
+        catch (err) {
+            throw new Error(`sandbox cannot use workspace ${workspaceRoot}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const runner = this.ensureRunner(wire);
+        // Permissions MUST cross: they decide the ENGINE's own sandbox mode (codex maps
+        // workspace-write → sandboxMode=workspace-write, read-only → read-only). Dropping them
+        // silently downgraded every sandbox turn to the default, so codex's shell exited 0 while its
+        // sandbox discarded the write — reads and commands worked, files never appeared.
+        // Observed live on tier 2. Accept either serve's nested `permissions` or a bare
+        // `fileAccess` on the options.
+        const loose = wire;
+        // Last resort is the PACK's own declared fileAccess, not the engine default: a frame that
+        // somehow arrives without permissions must not hand the engine more access than the
+        // manifest asks for.
+        const perms = loose.permissions
+            ?? (loose.fileAccess ? { fileAccess: loose.fileAccess } : { fileAccess: this.defaults.fileAccess });
+        const result = await runner.run({
+            engineId: wire.engineId ?? this.defaults.engineId,
+            modelId: wire.modelId ?? this.defaults.modelId,
+            message,
+            workspaceRoot,
+            additionalDirectories: wire.additionalDirectories,
+            sessionId: wire.sessionId,
+            permissions: perms,
+            // Parity with serve's in-process runner: attribution for evidence, the per-turn
+            // data-plane nonce (without which a sandbox cannot reach the data gateway at all), and
+            // the bound gateway session.
+            analyticsUserId: wire.analyticsUserId,
+            turnEnv: wire.turnEnv,
+            gatewaySessionKey: wire.gatewaySessionKey,
+            emitter,
+            signal,
+        });
+        // A failed run must reject so the host emits `failed`, not `result` — otherwise serve
+        // would record a successful turn for a turn that errored.
+        if (!result.success && result.error) {
+            throw new Error(result.error);
+        }
+    }
+    onMaintenance() { }
+    dispose() { this.runner?.dispose(); }
+}
+/**
+ * A sandbox hosts ONE session for its whole life, so an engine-side async error must not take the
+ * process down — that would lose the session, not just the turn. Vendor SDKs reject outside the
+ * `engine.stream()` await chain (observed: the Claude SDK's `streamInput` rejecting after its
+ * child process dies), which Node treats as fatal by default. Log and stay up; the turn's own
+ * catch still emits `failed`, and serve can always destroy the sandbox if it wants it gone.
+ *
+ * `uncaughtException` is NOT swallowed: after one the process state is unreliable, so exit and
+ * let the driver create a fresh sandbox.
+ */
+function installSandboxResilience() {
+    process.on('unhandledRejection', (reason) => {
+        const msg = reason instanceof Error ? reason.message : String(reason);
+        console.error(`[sandbox] unhandled rejection (session kept alive): ${msg}`);
+    });
+    process.on('uncaughtException', (err) => {
+        console.error(`[sandbox] uncaught exception — exiting so the driver recreates this sandbox: ${err.message}`);
+        process.exit(1);
+    });
+}
+async function sandboxCommand(options) {
+    // Every other command does this in its action; a sandbox needs it too, or a dev-box sandbox has no
+    // engine SDKs at all. In a self-contained image AGENTHIPPO_NO_AUTO_INSTALL=1 makes it a no-op.
+    await (0, deps_1.ensureDeps)(false);
+    const stateDir = options.stateDir ?? '/state';
+    const workspaceForLoad = options.workspace ?? path.join(stateDir, 'workspace');
+    fs.mkdirSync(workspaceForLoad, { recursive: true });
+    // The real loader, exactly as serve uses it — and `--agent` is a name-OR-path for the same
+    // reason it is everywhere else. The previous code resolved it as a path and demanded
+    // agent.yaml there, so `serve --agent joker1 --sandbox process` handed the sandbox a bare name
+    // it turned into <cwd>/joker1 and every turn died with "No agent.yaml". The hand-rolled regex
+    // before that only matched block-style YAML, so a flow-style manifest (`metadata: { name: x }`)
+    // silently fell back to 'default' — which is how CODEX_HOME ended up at agents/default instead
+    // of agents/<pack>, breaking per-pack engine isolation inside sandboxes.
+    const pack = await (0, pack_loader_1.loadAgentPack)(options.agent, workspaceForLoad);
+    const manifest = {
+        name: pack.manifest.metadata.name,
+        version: pack.manifest.metadata.version,
+        engine: pack.manifest.spec?.engine ?? 'claude',
+    };
+    // A sandbox runs on a read-only root by design, so every writable path must live under the one
+    // mounted state directory. `--state-dir` is authoritative here and OVERRIDES the image's
+    // baked AGENTHIPPO_HOME (the runtime image sets /state, which is read-only unless mounted);
+    // otherwise the engine's cache lands on the read-only root and the first turn dies with
+    // EROFS — observed live on Linux.
+    if (options.stateDir) {
+        process.env.AGENTHIPPO_HOME = stateDir;
+    }
+    else {
+        process.env.AGENTHIPPO_HOME = process.env.AGENTHIPPO_HOME ?? stateDir;
+    }
+    // HOME too, not just AGENTHIPPO_HOME: engine SDKs write to dot-directories under $HOME
+    // (the Cursor SDK uses ~/.cursor, codex/claude keep caches there), and the image's default
+    // HOME sits on the read-only root — so every such write fails with ENOENT/EROFS inside a
+    // sandbox. Observed live on tier 2 with the Cursor SDK.
+    // Declare that a sandbox surrounds this process. This says WHERE we are, not how confined we
+    // are: whether an engine may stand its own boundary down is answered by AGENTHIPPO_SANDBOX_TIER
+    // (see sandbox/types.ts), which only the driver sets and only tier 2 satisfies. Deriving
+    // "unconfined is safe" from this flag is what made `--sandbox process` weaker than no sandbox.
+    process.env.AGENTHIPPO_SANDBOX = '1';
+    const sandboxHome = path.join(stateDir, 'home');
+    fs.mkdirSync(sandboxHome, { recursive: true });
+    process.env.HOME = sandboxHome;
+    // Hydrate the workspace from the mounted pack — the SAME call serve makes at boot. A sandbox
+    // holds exactly one user's session, so it should look exactly like the single-user case:
+    // pack content (skills, rules, engine config) lives IN the workspace, and every downstream
+    // path (`getSkillsSignature(workspaceRoot)`, engine homes) resolves off that one root.
+    // Without this the pack stayed a read-only mount the engines never looked at, so no pack
+    // skill was ever visible inside a sandbox — observed live on tier 2.
+    const workspace = workspaceForLoad;
+    await (0, headless_1.syncPackToWorkspace)(workspace, pack.packPath, manifest.name, manifest.engine, console, (0, utils_1.findBundledBasePromptsDir)());
+    console.log(`[sandbox] pack ${manifest.name}@${manifest.version ?? '?'} synced into ${workspace} (engine ${manifest.engine})`);
+    // Only NOW: everything above is boot, and a boot failure must be fatal so the driver sees a
+    // dead sandbox and reports the real error. Swallowing it would leave a sandbox that answers every
+    // turn with "channel closed" and no cause.
+    installSandboxResilience();
+    const rawCheapModel = pack.manifest.spec?.cheapModel?.trim();
+    const engine = new SandboxEngine({
+        storagePath: stateDir,
+        // Land evidence where serve and Spotlight already scan, rather than the headless default.
+        analyticsSessionsDir: (0, serve_hardening_1.resolveAnalyticsSessionsDir)(stateDir, false),
+        packId: manifest.name,
+        packVersion: manifest.version,
+        engineId: manifest.engine,
+        // serve normally sends modelId on every frame; this is the fallback, and it comes from the
+        // pack the same way serve's does instead of a hardcoded alias.
+        modelId: (0, headless_1.resolveModelAlias)(pack.manifest.spec?.model?.trim() || 'ah-auto'),
+        claudeCheapModel: rawCheapModel ? (0, headless_1.resolveModelAlias)(rawCheapModel) : undefined,
+        fileAccess: (0, pack_loader_1.getFileAccess)(pack),
+        workspace,
+    });
+    const runtime = { logger: console };
+    if (options.stdio) {
+        const host = (0, host_1.startRunnerHost)({
+            engine, runtime,
+            input: process.stdin,
+            output: { write: (c) => process.stdout.write(c) },
+            nativeSessionId: () => engine.nativeSessionId,
+        });
+        await host.done;
+        return;
+    }
+    const socketPath = options.socket;
+    if (!socketPath) {
+        throw new Error('sandbox requires --socket <path> or --stdio');
+    }
+    // A stale socket from a previous sandbox would make bind fail; the sandbox owns this path.
+    try {
+        fs.unlinkSync(socketPath);
+    }
+    catch { /* not there — fine */ }
+    const server = net.createServer((conn) => {
+        (0, host_1.startRunnerHost)({
+            engine, runtime,
+            input: conn,
+            output: { write: (c) => conn.write(c) },
+            nativeSessionId: () => engine.nativeSessionId,
+        });
+    });
+    // Binding is fatal: a sandbox nobody can reach is useless, and exiting 0 would tell the driver
+    // the sandbox is healthy while every turn fails on a dead channel (observed live).
+    try {
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(socketPath, () => resolve());
+        });
+    }
+    catch (err) {
+        console.error(`[sandbox] FATAL: cannot listen at ${socketPath}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    // 0o660: the sandbox owns the socket; serve connects from the host. serve manages the container
+    // runtime (already root-equivalent), so it can connect; no other local uid can. Only the
+    // sandbox's own mount namespace has this path at all — the mode is defence in depth.
+    try {
+        fs.chmodSync(socketPath, 0o660);
+    }
+    catch { /* best effort */ }
+    console.log(`[sandbox] ${options.sandboxId ?? 'sandbox'} listening on ${socketPath} (pack ${manifest.name}@${manifest.version ?? '?'})`);
+    await new Promise((resolve) => {
+        const shutdown = () => { server.close(() => resolve()); engine.dispose(); };
+        process.once('SIGTERM', shutdown);
+        process.once('SIGINT', shutdown);
+        server.once('close', () => resolve());
+    });
+}