@agenthippo-ai/agenthippo 1.110.11 → 1.110.20

package/out/cli/commands/serve.js

@@ -1,1950 +0,0 @@
-"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.serveCommand = serveCommand;
-exports.resolveGatewaySessionKey = resolveGatewaySessionKey;
-exports.runGatewayTurn = runGatewayTurn;
-exports.runBridgeTurn = runBridgeTurn;
-/**
- * Serve Command - HTTP Server
- */
-const crypto = __importStar(require("crypto"));
-const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
-const http = __importStar(require("http"));
-const path = __importStar(require("path"));
-const node_crypto_1 = require("node:crypto");
-const sandboxRunner_1 = require("../../sandbox/sandboxRunner");
-const deps_1 = require("../deps");
-const signature_1 = require("../../pack/signature");
-const reconcile_1 = require("../../pack/reconcile");
-const index_1 = require("../../store/index");
-const lease_1 = require("../../pack/lease");
-const caps_1 = require("../../pack/caps");
-const governor_1 = require("../../pack/governor");
-const containerDriver_1 = require("../../sandbox/containerDriver");
-const processDriver_1 = require("../../sandbox/processDriver");
-const support_1 = require("../../sandbox/support");
-const headless_1 = require("../../headless");
-const pack_loader_1 = require("../pack-loader");
-const utils_1 = require("../utils");
-const pack_runtime_1 = require("../pack-runtime");
-const sessionShip_1 = require("../../evidence/sessionShip");
-const serve_hardening_1 = require("../serve-hardening");
-const credential_context_1 = require("../credential-context");
-const lease_2 = require("../../pack/lease");
-const identity_1 = require("../../analytics/identity");
-const data_plane_1 = require("../data-plane");
-const runtime_1 = require("../runtime");
-const outboundSend_1 = require("../../gateway/outboundSend");
-const sessionEvents_1 = require("../../analytics/sessionEvents");
-const base_1 = require("../../engines/base");
-const state_sync_1 = require("../state-sync");
-const cli_agent_id_js_1 = require("../../gateway/cli-agent-id.js");
-const openclaw_channel_routing_js_1 = require("../../gateway/openclaw-channel-routing.js");
-const customRegistry_1 = require("../../engines/customRegistry");
-const BANNER_LINE = '-'.repeat(62);
-async function serveCommand(options) {
-    const apiConfig = (0, pack_loader_1.getApiConfig)();
-    if (apiConfig.useLiteLLM && !apiConfig.litellmApiKey) {
-        // Loud, because the failure mode it replaces was silent: traffic reached the gateway
-        // authenticated with whatever sat in the provider-key slot, with analytics disabled.
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} AGENTHIPPO_LITELLM_BASE_URL is set without AGENTHIPPO_LITELLM_API_KEY — gateway calls will authenticate as 'sk-dummy' (a strict gateway will 401). Provider keys are never sent to the gateway.`);
-    }
-    // Load agent pack (required)
-    let pack;
-    const syncLogger = options.verbose ? new headless_1.ConsoleLogger('[Sync]') : new headless_1.NoOpLogger();
-    try {
-        pack = await (0, pack_loader_1.loadAgentPack)(options.agent, options.workspace);
-    }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
-    }
-    const packId = pack.manifest.metadata.name;
-    const gatewayAgentId = (0, cli_agent_id_js_1.resolveCliGatewayAgentId)(packId);
-    const defaultEngine = (options.engine || pack.manifest.spec.engine || (0, pack_loader_1.getDefaultConfig)().engine).trim().toLowerCase();
-    const customEngineDefaultModel = !['claude', 'codex'].includes(defaultEngine)
-        ? (0, customRegistry_1.tryResolveCustomEngineManifest)(options.workspace, defaultEngine)?.model?.defaultModel
-        : undefined;
-    // Custom engine manifest defaultModel beats the global AGENTHIPPO_DEFAULT_MODEL
-    // so --engine gemini without --model uses gemini's manifest default, not the
-    // user's global Claude/Codex fallback.
-    const rawModel = options.model || pack.manifest.spec.model || customEngineDefaultModel || (0, pack_loader_1.getEnvDefaultModel)() || (0, pack_loader_1.getDefaultConfig)().model;
-    const defaultModel = (0, headless_1.resolveModelAlias)(rawModel);
-    const rawCheapModel = pack.manifest.spec.cheapModel?.trim();
-    const claudeCheapModel = rawCheapModel ? (0, headless_1.resolveModelAlias)(rawCheapModel) : undefined;
-    // Engine-aware: a codex deploy needs an OpenAI (or LiteLLM) key; a claude deploy needs an
-    // Anthropic (or LiteLLM) key. Fail loudly at boot rather than 401 at the first model call.
-    if (!(0, pack_loader_1.hasCredentialForEngine)(defaultEngine, apiConfig)) {
-        const need = defaultEngine === 'claude' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY';
-        console.error(`Error: No usable API key for engine "${defaultEngine}". Set ${need}, or configure the LiteLLM proxy (AGENTHIPPO_LITELLM_API_KEY + AGENTHIPPO_LITELLM_BASE_URL).`);
-        for (const line of (0, utils_1.getLiteLLMQuickstartHintLines)()) {
-            console.error(line);
-        }
-        process.exit(1);
-    }
-    const logger = options.verbose ? new headless_1.ConsoleLogger('[Server]') : new headless_1.NoOpLogger();
-    // ---------------------------------------------------------------------------------------
-    // Pack admission — BEFORE anything from the pack reaches the workspace.
-    //
-    // `syncPackToWorkspace` used to run here, hundreds of lines before the signature was checked,
-    // so a pack that was about to be refused had already materialised its skills, AGENTS.md and
-    // MCP server definitions into the workspace and into the derived .claude/.codex directories.
-    // The refusal then stopped the turn while the content it was refusing sat on disk, reachable
-    // by anything else pointed at that workspace. Verification moves ahead of the write.
-    // ---------------------------------------------------------------------------------------
-    let activePackDir = pack.packPath;
-    let activeVersion = pack.manifest.metadata.version ?? '0.0.0';
-    let packDigestValue;
-    /**
-     * Trusted pack-signing keys. NOT frozen at boot.
-     *
-     * A trust root that is CONFIGURED BUT UNREACHABLE (a 503 during a rolling restart, a DNS blip)
-     * is now distinguishable from one that was never configured, and it is retried on the lease
-     * poll — one transient fetch at the wrong second must fail the turn, not brick the process.
-     */
-    let packTrust = await (0, signature_1.loadPackTrustRoot)({ leaseUrl: process.env.AGENTHIPPO_LEASE_URL });
-    const reportTrustRoot = (t, label = 'pack') => {
-        for (const w of t.warnings) {
-            console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${w}`);
-        }
-        if (t.status === 'unavailable') {
-            console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${label} trust root is configured but unusable: ${t.reason}`);
-        }
-    };
-    reportTrustRoot(packTrust);
-    /**
-     * Verified per turn, with a cheap change probe — see `createPackVerifier`. The RESULT is
-     * cached only as long as the pack tree looks untouched and never longer than the full-reverify
-     * interval; the REQUIREMENT is re-read from the lease on every poll, so an operator can turn
-     * enforcement on for a fleet already running.
-     */
-    const packVerifier = (0, signature_1.createPackVerifier)();
-    let packSignature = { ok: false, kind: 'no-pack', reason: 'not verified' };
-    const verifyPackAt = (packDir, version) => {
-        packSignature = packVerifier.refresh({ packDir, pack: packId, packVersion: version, keys: packTrust.keys });
-        packDigestValue = packSignature.ok ? packSignature.claims.digest : undefined;
-        logger.info(packSignature.ok
-            ? `[Pack] signature verified for ${packId}`
-            : `[Pack] unverified — ${packSignature.reason}`);
-        return packSignature;
-    };
-    /** The refusal an operator sees, with the remedy for THIS failure rather than a generic one. */
-    const packRefusalText = (result) => {
-        if (result.ok) {
-            return '';
-        }
-        // "Configured but unreachable" outranks whatever the verifier concluded: with no usable
-        // keys every signature fails as `no-trust-root`, and telling an operator to configure a
-        // trust root they already configured is the least useful thing we could say.
-        const kind = packTrust.status === 'unavailable' && result.kind === 'no-trust-root' ? 'trust-root-unavailable' : result.kind;
-        return (0, signature_1.describePackRefusal)({
-            kind,
-            detail: kind === 'trust-root-unavailable' ? (packTrust.reason ?? result.reason) : result.reason,
-            pack: packId,
-            packVersion: activeVersion,
-            packDir: activePackDir,
-            trustRootHint: packTrust.url ? `Trust root: ${packTrust.url} (${packTrust.reason ?? 'unavailable'})` : packTrust.reason,
-        });
-    };
-    verifyPackAt(activePackDir, activeVersion);
-    /**
-     * Signing REQUIRED by default.
-     *
-     * This is a deliberate break with the previous shipped behaviour, which logged
-     * `[Pack] unsigned or unverifiable — …` and then ran the pack anyway. Warn-and-run is not a
-     * gate; it is a log line next to an ungated code path, and it meant the default deployment
-     * shape executed whatever was in the pack directory.
-     *
-     * Tighten-only survives intact: the escape hatch below relaxes only this INSTANCE's default,
-     * and `resolveRequireSignedPack` checks the lease's demand first, so a control plane that sets
-     * `requireSignedPack` cannot be opted out of locally.
-     */
-    const allowUnsignedPack = Boolean(options.allowUnsignedPack) || (0, signature_1.allowUnsignedPackFromEnv)();
-    if (!packSignature.ok) {
-        if (!allowUnsignedPack) {
-            console.error(`${utils_1.COLORS.red}Error: ${packRefusalText(packSignature)}${utils_1.COLORS.reset}`);
-            process.exit(1);
-        }
-        // Unmissable, every boot, at warn level regardless of --verbose.
-        console.warn(BANNER_LINE);
-        console.warn(`${utils_1.COLORS.yellow}!! RUNNING AN UNVERIFIED PACK — signature checking is DISABLED on this instance.${utils_1.COLORS.reset}`);
-        console.warn(`${utils_1.COLORS.yellow}!! ${packSignature.reason}${utils_1.COLORS.reset}`);
-        console.warn(`${utils_1.COLORS.yellow}!! Whatever is in ${activePackDir} will be executed, verified by nobody.${utils_1.COLORS.reset}`);
-        console.warn(`${utils_1.COLORS.yellow}!! This is a LOCAL DEVELOPMENT setting (AGENTHIPPO_ALLOW_UNSIGNED_PACK). Do not ship it.${utils_1.COLORS.reset}`);
-        console.warn(BANNER_LINE);
-    }
-    // Sync pack content to workspace — only now that the pack has been admitted.
-    const bundledPromptsDir = (0, utils_1.findBundledBasePromptsDir)();
-    await (0, headless_1.syncPackToWorkspace)(options.workspace, pack.packPath, packId, defaultEngine, syncLogger, bundledPromptsDir);
-    console.log(`OK: Loaded agent: ${pack.manifest.metadata.name} v${pack.manifest.metadata.version}`);
-    // Structural attribution (pack-standard WS2) — greppable for CISO/SRE boot audits.
-    console.log(`agenthippo pack=${pack.manifest.metadata.name}@${pack.manifest.metadata.version} engine=${defaultEngine}`);
-    // Resolve persistent session state (serve-v3 §A1: replaces the tmpdir default).
-    const { dir: storagePath, ephemeral } = (0, serve_hardening_1.resolveStateDir)(options.stateDir);
-    const bindHost = (0, serve_hardening_1.resolveBindHost)(options.host);
-    // Who serve believes a caller to be decides whose session state and whose data credentials they
-    // reach, so an unpinned identity header is not a detail to leave in a docstring.
-    for (const line of (0, serve_hardening_1.identityHeaderAdvice)(process.env, bindHost)) {
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${line}`);
-    }
-    // A pinned header means multiple users; a tier-0 or sandbox-less serve means one filesystem for
-    // all of them. That pairing had no boot-time signal at all, while the strictly SAFER container
-    // case (--shared-workspace) has warned since it shipped.
-    const tenantIsolation = (0, serve_hardening_1.tenantIsolationAdvice)({
-        sandbox: options.sandbox,
-        sharedWorkspace: Boolean(options.sharedWorkspace),
-        workspace: options.workspace,
-        stateDir: storagePath,
-    });
-    if (tenantIsolation.level === 'refuse') {
-        for (const line of tenantIsolation.lines) {
-            console.error(`${utils_1.COLORS.red}Error:${utils_1.COLORS.reset} ${line}`);
-        }
-        console.error(`Refusing to start because ${serve_hardening_1.REQUIRE_TENANT_ISOLATION_ENV} is set. Unset it to downgrade this to a warning.`);
-        process.exit(1);
-    }
-    for (const line of tenantIsolation.lines) {
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${line}`);
-    }
-    // Passed to createPackRunner below so the runner's own SessionEventWriter uses the same
-    // root — a fail-closed warrant denial lands in the same per-session JSONL as the tool events
-    // it precedes. The denial happens before runner.run() is ever called, so it needs its own
-    // writer here too. See resolveAnalyticsSessionsDir's docstring for the precedence.
-    const analyticsSessionsDir = (0, serve_hardening_1.resolveAnalyticsSessionsDir)(storagePath, ephemeral);
-    const sessionEventWriter = new sessionEvents_1.SessionEventWriter(analyticsSessionsDir);
-    const logWarrantDenied = (sessionKey) => (reason) => sessionEventWriter.append(sessionKey, (0, base_1.generateRequestId)(), 'warrant_denied', { reason });
-    // Data-plane gateway (secure-obo-design §3): when the pack declares spec.dataPlane,
-    // serve runs the connector broker-side and engines get a per-turn nonce instead of the
-    // credential. The raw data credential never crosses into the agent's trust domain.
-    const dataPlaneCfg = (0, data_plane_1.resolveDataPlaneConfig)(pack.manifest.spec, pack.packPath);
-    // EDGE-registration mode (P1 fix, obo-inprogress §2): the trusted edge (IdP Caddy)
-    // registers each turn with the sidecar and injects the nonce as a request header; serve
-    // merely adopts it. serve holds NO registration credential at all — nothing in this
-    // container's /proc can mint a nonce for an arbitrary userId. Takes precedence over the
-    // token-based sidecar mode below.
-    const edgeCfg = (0, data_plane_1.resolveEdgeDataPlane)();
-    const edgeDataPlane = edgeCfg ? new data_plane_1.EdgeDataPlane(edgeCfg) : null;
-    // Data-plane SIDECAR mode (secure-obo-design §7.6): when the connector runs in its OWN
-    // container, AGENTHIPPO_DATA_PLANE_CONTROL_URL/TOKEN + AGENTHIPPO_DATA_MCP_URL are set and
-    // serve holds NO backend base credential — it registers turns with the sidecar and hands the
-    // engine only the nonce. Takes precedence over an in-process connector.
-    const remoteCfg = edgeDataPlane ? null : (0, data_plane_1.resolveRemoteDataPlane)();
-    const remoteDataPlane = remoteCfg ? new data_plane_1.RemoteDataPlane(remoteCfg) : null;
-    // One shared registry: a single per-turn nonce grants BOTH the data-plane and egress
-    // capabilities (secure-obo-design §7.6 step 2). Created when either LOCAL broker will run.
-    const turnRegistry = ((dataPlaneCfg && !remoteDataPlane && !edgeDataPlane) || options.gatewayBridge) ? new data_plane_1.TurnRegistry() : null;
-    /**
-     * Every data-plane audit row carries BOTH principals (PLAN/agent-identity.md §1 failure 3,
-     * §10).
-     *
-     * The user dimension was already on these rows. The agent was not, so evidence could answer
-     * "which user touched which rows" but not "via which agent" — the auditor's second question,
-     * and the one the whole design exists to make answerable. It was only ever *implied*, by which
-     * deployment happened to write the file, and that implication breaks entirely the moment two
-     * serves share a connector (§4.4).
-     *
-     * Read at emit time, not captured once: `activeVersion` and `packDigestValue` both change on a
-     * pack hot-swap, and a row must name the pack that actually served it.
-     *
-     * The digest is carried in full rather than truncated — it is not a secret, and a prefix cannot
-     * be checked against a signed artifact, which is the entire point of recording it.
-     */
-    const auditEvent = (sessionKey, event, fields) => sessionEventWriter.append(sessionKey, (0, base_1.generateRequestId)(), event, {
-        ...fields,
-        agent: { pack: packId, version: activeVersion, digest: packDigestValue ?? null },
-    });
-    let dataPlane = null;
-    if (edgeDataPlane) {
-        process.env[data_plane_1.DATA_MCP_URL_ENV] = edgeDataPlane.url;
-        // Belt-and-braces: edge mode must never see a register token, but if one leaked into the
-        // deploy env anyway, strip it before any engine child inherits it.
-        delete process.env.AGENTHIPPO_DATA_PLANE_TOKEN;
-        delete process.env.AGENTHIPPO_DATA_PLANE_CONTROL_URL;
-        console.log(`OK: Data plane EDGE-registered — gateway ${edgeDataPlane.url}; turn nonces are minted at the edge, serve holds no registration credential`);
-    }
-    else if (remoteDataPlane) {
-        process.env[data_plane_1.DATA_MCP_URL_ENV] = remoteDataPlane.url;
-        // The control-API token is captured in the RemoteDataPlane (serve memory). Strip it from
-        // the process env so no engine child inherits it — otherwise the agent could register a
-        // turn as ANY user and read their rows (forge-identity escalation). The engine keeps the
-        // gateway URL + its own per-turn nonce, which is all it needs (secure-obo-design §7.6).
-        delete process.env.AGENTHIPPO_DATA_PLANE_TOKEN;
-        console.log(`OK: Data plane SIDECAR — gateway ${remoteDataPlane.url}; base credentials stay in the connector container, not here`);
-    }
-    else if (dataPlaneCfg) {
-        try {
-            dataPlane = await data_plane_1.DataPlane.start(dataPlaneCfg, {
-                logger: options.verbose ? new headless_1.ConsoleLogger('[DataPlane]') : new headless_1.NoOpLogger(),
-                audit: auditEvent,
-                registry: turnRegistry ?? undefined,
-            });
-            // Boot-stable process env: engines resolve ${env:AGENTHIPPO_DATA_MCP_URL} from it,
-            // so codex's config.toml stays byte-identical across turns. The NONCE is never set
-            // here — it rides the per-spawn child env only.
-            process.env[data_plane_1.DATA_MCP_URL_ENV] = dataPlane.url;
-            console.log(`OK: Data gateway (provider=${dataPlane.broker.provider.name}) on loopback — connector: ${dataPlaneCfg.connectorPath}`);
-        }
-        catch (err) {
-            console.error(`${utils_1.COLORS.red}Error: failed to start the data-plane gateway:${utils_1.COLORS.reset} ${err instanceof Error ? err.message : err}`);
-            process.exit(1);
-        }
-    }
-    // Egress broker (secure-obo-design §7.6): capture the gateway token broker-side BEFORE any
-    // engine spawns, so it can be stripped from the process env the children inherit. The broker
-    // starts alongside the gateway bridge below; the token is held only in this closure.
-    // Captured UNCONDITIONALLY, and the env strip is immediate (serve-v4 §10 hole 2): the strip
-    // used to live inside the broker branch, so a serve without --gateway-bridge kept the token
-    // in process.env and every engine child (they all spread it) inherited a credential nothing
-    // in this deployment would ever legitimately use.
-    const brokerGatewayToken = (0, runtime_1.readOpenClawGatewayToken)();
-    delete process.env.OPENCLAW_GATEWAY_TOKEN;
-    let egressBroker = null;
-    // Mint one nonce per turn and assemble the per-spawn child env. Returns null outside any
-    // broker (no capability to grant). The URLs ride process.env (boot-stable) for config
-    // invariance; only the nonce is per-spawn.
-    const registerServeTurn = async (reg) => {
-        // Edge mode: the trusted edge already registered this turn and injected the nonce as a
-        // request header — adopt it. No edge nonce (misrouted request, or a channel turn that
-        // never traversed the edge) ⇒ no data capability, fail closed at the gateway.
-        if (edgeDataPlane) {
-            const edgeNonce = reg.edgeNonce?.trim();
-            if (!edgeNonce) {
-                console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} edge data plane active but no ${data_plane_1.TURN_NONCE_HEADER} header on this turn — data tools will fail closed (check the edge route's forward_auth)`);
-                return null;
-            }
-            const r = edgeDataPlane.adoptTurn(edgeNonce);
-            const env = { ...r.env };
-            if (egressBroker) {
-                env[data_plane_1.EGRESS_URL_ENV] = egressBroker.url;
-            }
-            return { nonce: r.nonce, env, release: r.release };
-        }
-        // Sidecar: register with the connector container; serve never sees a base credential.
-        if (remoteDataPlane) {
-            // Name the agent on every registration (PR-8). Asserted, not proven — the sidecar
-            // records it and flags a mismatch against the pack it loaded, which is how "one
-            // connector, one agent" (§4.4) becomes observable rather than merely assumed.
-            const r = await remoteDataPlane.registerTurn({
-                ...reg,
-                agent: { pack: packId, version: activeVersion, digest: packDigestValue },
-            });
-            const env = { ...r.env };
-            if (egressBroker) {
-                env[data_plane_1.EGRESS_URL_ENV] = egressBroker.url;
-            }
-            return { nonce: r.nonce, env, release: r.release };
-        }
-        if (!turnRegistry) {
-            return null;
-        }
-        const { nonce, release } = turnRegistry.register(reg);
-        const env = { [data_plane_1.TURN_NONCE_ENV]: nonce };
-        if (dataPlane) {
-            env[data_plane_1.DATA_MCP_URL_ENV] = dataPlane.url;
-        }
-        if (egressBroker) {
-            env[data_plane_1.EGRESS_URL_ENV] = egressBroker.url;
-        }
-        return { nonce, env, release };
-    };
-    // Edge-registered turn nonce, injected by the trusted edge per chat request (edge mode only —
-    // otherwise ignored). Trusted like the pinned identity header: only the in-network edge can
-    // reach serve, and a forged value fails closed at the gateway (unknown nonce ⇒ 401).
-    const edgeTurnNonce = (headers) => {
-        if (!edgeDataPlane) {
-            return undefined;
-        }
-        const v = headers[data_plane_1.TURN_NONCE_HEADER];
-        return Array.isArray(v) ? v[0] : v;
-    };
-    const turnLimiter = new serve_hardening_1.TurnLimiter(options.maxTurnsPerSession ?? 0);
-    // Per-identity request-rate cap (req/min). Keyed on the trusted user id (falling back to
-    // client IP) so rotating session_id can't bypass it. AGENTHIPPO_SERVE_RATE_LIMIT=0 disables.
-    const rateLimitPerMin = Number(process.env.AGENTHIPPO_SERVE_RATE_LIMIT ?? 120);
-    const rateLimiter = new serve_hardening_1.RateLimiter(Number.isFinite(rateLimitPerMin) ? rateLimitPerMin : 120);
-    // Process-wide inflight cap (serve-v4 P0.1). Prevents a burst from spawning N engine
-    // subprocesses and OOMing the container. AGENTHIPPO_MAX_CONCURRENT_TURNS=0 disables.
-    const turnGate = (0, serve_hardening_1.createTurnGateFromEnv)();
-    const warnGateReject = (0, serve_hardening_1.createRejectionWarner)();
-    let landingPageHtml;
-    if (options.wwwDir?.trim()) {
-        const indexPath = path.join(path.resolve(options.wwwDir.trim()), 'index.html');
-        try {
-            landingPageHtml = fs.readFileSync(indexPath, 'utf8');
-        }
-        catch {
-            console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} --www-dir set but unreadable: ${indexPath}`);
-        }
-    }
-    if (ephemeral) {
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} Session state is in a tmpdir (ephemeral). Pass --state-dir or set AGENTHIPPO_HOME to persist sessions across restarts.`);
-    }
-    // Q1 + serve-v4 P1.2: object-store state sync (no-op unless AGENTHIPPO_STATE_S3_URI is set).
-    // Multi-replica: AGENTHIPPO_STATE_RESTORE_BOOT=none + restore-on-miss per session.
-    // Single-instance default: boot-restore the whole prefix (backward compatible).
-    const s3State = (0, state_sync_1.resolveS3StateConfig)();
-    const restoreBoot = (0, state_sync_1.resolveRestoreBootMode)();
-    if (s3State) {
-        // Preflight: state sync shells out to `aws`. If it's missing, sessions would
-        // silently never persist — fail fast since durable state was explicitly opted into.
-        if (!(await (0, state_sync_1.isAwsCliAvailable)())) {
-            console.error(`${utils_1.COLORS.red}Error: AGENTHIPPO_STATE_S3_URI is set but the \`aws\` CLI was not found.${utils_1.COLORS.reset}`);
-            console.error('   State sync requires the AWS CLI (S3-compatible via --endpoint-url). Install it or unset AGENTHIPPO_STATE_S3_URI.');
-            process.exit(1);
-        }
-        if (restoreBoot === 'all') {
-            console.log(`State sync: boot-restore from ${s3State.uri} …`);
-            await (0, state_sync_1.restoreState)(s3State, storagePath, (m) => console.log(`  ${m}`));
-        }
-        else {
-            console.log(`State sync: restore-on-miss from ${s3State.uri} (boot restore disabled)`);
-        }
-    }
-    const statePusher = s3State ? (0, state_sync_1.makeStatePusher)(s3State, storagePath, options.verbose ? (m) => console.error(m) : undefined) : null;
-    const stateLog = options.verbose ? (m) => console.error(m) : undefined;
-    const prepareSession = async (sessionKey) => {
-        if (s3State) {
-            await (0, state_sync_1.ensureSessionLocal)(s3State, storagePath, sessionKey, stateLog);
-        }
-    };
-    // Find SDK CLI paths
-    const claudeCodePath = (0, utils_1.findClaudeCodePath)();
-    const codexPath = (0, utils_1.findCodexPath)();
-    // Validate required CLI is available — but ONLY when this process will run the engine.
-    // A container sandbox runs the engine inside its own image, so requiring the SDK on the host
-    // is wrong and refuses to boot on exactly the minimal host a tier-2 deployment wants
-    // (observed live: a Linux host with no npm/codex could not start `--sandbox container`).
-    // The process driver shares this host, so it still needs the CLI present.
-    const engineRunsInSandbox = options.sandbox === 'container';
-    if (!engineRunsInSandbox && defaultEngine === 'claude' && !claudeCodePath) {
-        console.error(`${utils_1.COLORS.red}Error: Claude Code CLI not found.${utils_1.COLORS.reset}`);
-        console.error('   Install: npm install -g @anthropic-ai/claude-code');
-        console.error('   Or set CLAUDE_CODE_PATH environment variable');
-        process.exit(1);
-    }
-    if (!engineRunsInSandbox && defaultEngine === 'codex' && !codexPath) {
-        console.error(`${utils_1.COLORS.red}Error: Codex CLI not found.${utils_1.COLORS.reset}`);
-        console.error('   Install: npm install -g @openai/codex');
-        console.error('   Or set CODEX_PATH environment variable');
-        process.exit(1);
-    }
-    // V1 permissions are non-interactive in server mode.
-    const permissionHandler = new headless_1.AutoApprovePermissionHandler();
-    const permissions = {
-        fileAccess: (0, pack_loader_1.getFileAccess)(pack),
-    };
-    // R-3 policy provenance (PLAN/compliance.md §3.1): remember WHICH policy is in force and
-    // announce changes. `policy_applied` marks the boundary; every turn between two boundaries
-    // carries the version via the runner's provenance stamp below, so "was the cap enforced?"
-    // stays answerable after anyone edits a cap.
-    let lastPolicyVersion;
-    let provenanceAnnounced = false;
-    const notePolicy = (lease) => {
-        const v = (0, lease_1.policyVersion)(lease);
-        // Announce once at boot even with no lease (unmanaged deployments still have a digest,
-        // an engine build and a tier), then again on every policy change. This event is the
-        // PROVENANCE DIMENSION: turns don't repeat these facts — the evidence index joins a
-        // turn to the latest announcement for its instance at or before the turn's timestamp.
-        if (provenanceAnnounced && v === lastPolicyVersion) {
-            return;
-        }
-        provenanceAnnounced = true;
-        lastPolicyVersion = v;
-        void sessionEventWriter.append('serve', (0, base_1.generateRequestId)(), 'policy_applied', {
-            instance_id: instanceId,
-            policy_version: v ?? null,
-            pack_digest: packDigestValue ?? null,
-            engine_version: (0, deps_1.installedEngineVersion)(defaultEngine) ?? null,
-            tier: options.sandbox === 'container' ? 2 : options.sandbox ? 0 : null,
-            enabled: lease?.enabled ?? null,
-            pinned_version: lease?.version ?? null,
-            caps: lease?.caps ?? null,
-            deny_count: lease?.deny?.length ?? 0,
-        });
-    };
-    // Same factory a sandbox uses (cli/pack-runtime.ts) — built after activeVersion is known.
-    let inProcessRunner;
-    /**
-     * Where sandboxes read the pack from.
-     *
-     * With --pull-packs this is a SYMLINK (`<state>/packs/current`), never the resolved directory:
-     * the sandbox drivers capture this path once at construction, so a stable name whose target is
-     * swapped is what lets a later version reach new sandboxes without rebuilding the runner. A
-     * sandbox already starting keeps the directory it opened, which is exactly the drain semantics
-     * version convergence already has.
-     */
-    const packsRoot = path.join(storagePath, 'packs');
-    const storeDownloader = async (slug, version) => {
-        const files = await (0, index_1.downloadFromStore)({ type: 'pack', slug, version });
-        return files.map((f) => ({ path: f.path, content: f.content }));
-    };
-    /** Converge to the pinned version if we can; never take the fleet down trying. */
-    const reconcileToPin = async (pinned) => {
-        if (!options.pullPacks || !pinned || pinned === activeVersion) {
-            return;
-        }
-        const res = await (0, reconcile_1.reconcilePinnedPack)({
-            pack: packId,
-            currentVersion: activeVersion,
-            pinnedVersion: pinned,
-            packsRoot,
-            download: storeDownloader,
-            publicKeysByKid: packTrust.keys,
-            logger: { info: (m) => logger.info(m), warn: (m) => logger.info(m) },
-        });
-        if (res.ok) {
-            activeVersion = res.version;
-            activePackDir = res.packDir;
-            verifyPackAt(activePackDir, activeVersion);
-            logger.info(`[Pack] now serving ${packId}@${activeVersion} from ${res.packDir}`);
-            return;
-        }
-        // Deliberately not fatal: the lease fails OPEN on transport, and a bad tag or a store
-        // outage must not become a fleet-wide stop. The instance keeps reporting the version it is
-        // really running, so the console shows "pinned to X, running Y" rather than an outage.
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} cannot converge to ${packId}@${pinned}: ${res.reason}. Still serving @${activeVersion}.`);
-    };
-    const warrantKey = (0, support_1.loadWarrantKeypair)(logger);
-    // Lease: kill switch + version pin. No URL configured ⇒ unmanaged deployment, always admits.
-    /** Set once the sandbox runner exists; the lease-poll identity reads it lazily. */
-    let sandboxRunnerRef;
-    // Stable across restarts, unique per instance: an operator watching the console must see one
-    // row per instance that survives a redeploy, not a new row each boot (and not one row per NAT
-    // address for a whole fleet). Persisted beside the instance's own state.
-    const instanceId = (() => {
-        try {
-            const file = path.join((0, serve_hardening_1.resolveStateDir)(options.stateDir).dir, 'instance-id');
-            if (fs.existsSync(file)) {
-                return fs.readFileSync(file, 'utf-8').trim();
-            }
-            const id = `${os.hostname()}-${crypto.randomBytes(4).toString('hex')}`;
-            fs.mkdirSync(path.dirname(file), { recursive: true });
-            fs.writeFileSync(file, id);
-            return id;
-        }
-        catch {
-            // Never let bookkeeping stop a boot; a per-process id still beats collapsing by address.
-            return `${os.hostname()}-${crypto.randomBytes(4).toString('hex')}`;
-        }
-    })();
-    /** Lazily read by the lease-poll identity, which is built before the pack path is resolved. */
-    const activeVersionRef = { get: () => pack?.manifest.metadata.version };
-    // ONE constant for the poll interval and everything derived from it. The cache used to default
-    // to 60s while every poll defaulted to 30s and the banner printed 30 — so the real kill latency
-    // was up to 3x what an operator was told.
-    const leasePollSeconds = (0, lease_1.resolveLeasePollSeconds)(options.leasePollSeconds);
-    /**
-     * Trusted LEASE-signing keys — a separate root from the pack one.
-     *
-     * These used to be the same keyring (`signingKeys: () => packTrust.keys`), which made signed
-     * leases unreachable end to end: the control plane publishes the lease public key under purpose
-     * `lease-signing` and refuses to register one kid under two purposes, so a correctly-configured
-     * plane and a correctly-configured serve could never name the same key. With `requireSignedLease`
-     * sticky and no plane-side undo, that disagreement latches an instance into refusing turns.
-     *
-     * A DERIVED root that comes back `unavailable` is the normal state of every plane that publishes
-     * no lease-signing key, so it is only reported at boot when an operator named one outright.
-     * Otherwise `leaseSigningKeys` says everything there is to say, and only once a signed lease has
-     * actually arrived.
-     */
-    let leaseTrust = await (0, signature_1.loadLeaseTrustRoot)({ leaseUrl: process.env.AGENTHIPPO_LEASE_URL });
-    if (leaseTrust.explicitlyConfigured) {
-        reportTrustRoot(leaseTrust, 'lease');
-    }
-    let leaseTrustFallbackWarned = false;
-    /**
-     * BACK-COMPAT, deliberately not a cutover.
-     *
-     * A deployment that verifies signed leases against the pack keyring today keeps working: with no
-     * lease root named outright, the pack keys stay in play and the (possibly empty) derived lease
-     * keys are added to them. The warning fires ONCE, and only when a signed lease is actually being
-     * verified, so a deployment that never uses signed leases never sees it.
-     *
-     * Not a hard switch because `requireSignedLease` latches per instance and the plane has no undo:
-     * an instance that stopped recognising its lease key would refuse turns and could not be talked
-     * out of it from the console.
-     */
-    const leaseSigningKeys = () => {
-        const selected = (0, signature_1.selectLeaseSigningKeys)(leaseTrust, packTrust);
-        if (selected.packFallback && !leaseTrustFallbackWarned) {
-            leaseTrustFallbackWarned = true;
-            console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} verifying signed leases against the PACK trust root — ` +
-                'no lease trust root is configured on this instance. The control plane publishes lease keys under ' +
-                'purpose `lease-signing` and refuses to register one kid under two purposes, so this stops working ' +
-                'the moment the plane rotates to a dedicated lease key — and requireSignedLease is sticky with no ' +
-                'plane-side undo, so that failure cannot be fixed from the console. Set ' +
-                `${signature_1.LEASE_JWKS_URL_ENV}=https://<plane>/.well-known/jwks.json?purpose=lease-signing ` +
-                `(or ${signature_1.LEASE_SIGNING_KEYS_ENV} with inline {"<kid>":"<public PEM>"} for an air-gapped install).` +
-                (leaseTrust.reason ? ` The derived lease trust root is unusable: ${leaseTrust.reason}` : ''));
-        }
-        return selected.keys;
-    };
-    const leaseSource = (0, lease_1.createLeaseSource)({
-        url: process.env.AGENTHIPPO_LEASE_URL,
-        // The poll IS the registration — see LeaseSourceOptions.identity.
-        identity: () => ({
-            instance: instanceId,
-            pack: packId,
-            // The version actually being served: after a pull this is the pinned one, and the
-            // console's whole convergence view depends on it being the truth rather than boot state.
-            version: activeVersionRef.get(),
-            tier: options.sandbox === 'container' ? 2 : options.sandbox ? 0 : undefined,
-            sandboxes: sandboxRunnerRef?.sandboxes().length,
-            // Which engine, and which BUILD of it. Pack version alone cannot explain a fleet-wide
-            // behaviour change that came from an engine upgrade, and the CLI is not engine-version
-            // agnostic, so the console needs both to answer "what is actually running?".
-            engine: defaultEngine,
-            engineversion: (0, deps_1.installedEngineVersion)(defaultEngine),
-        }),
-        // Derived from the poll interval by ONE function, so the two can no longer drift. Worst-case
-        // kill latency is poll + cache, and that is the number the boot banner prints.
-        cacheSeconds: (0, lease_1.leaseCacheSecondsFor)(leasePollSeconds),
-        // Signed-lease verification uses the LEASE trust root, falling back to the pack one while no
-        // lease root is configured. Read through a closure so a keyring that arrives on a later poll
-        // is picked up without rebuilding this.
-        signingKeys: () => leaseSigningKeys(),
-        requireSignedLease: options.requireSignedLease,
-        instanceId,
-        ...(options.leaseMaxStalenessSeconds !== undefined ? { maxStalenessSeconds: options.leaseMaxStalenessSeconds } : {}),
-        logger: {
-            // Lease warnings are security-relevant (unsigned lease, staleness ceiling, insecure URL)
-            // and must not be hidden behind --verbose.
-            info: (m) => logger.info(m),
-            warn: (m) => console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${m}`),
-        },
-    });
-    /**
-     * Retry the trust root while it is missing, and re-verify once it arrives.
-     *
-     * Only while MISSING: a loaded trust root is not re-fetched, so key rotation still needs the
-     * documented restart and a compromised plane cannot swap the trust root under a running
-     * instance mid-flight. This exists solely so a transient failure at boot is transient — the
-     * `unavailable` status is exactly what makes "transient" distinguishable from "not configured".
-     */
-    const retrySigningKeys = async () => {
-        if (packTrust.status !== 'configured') {
-            const next = await (0, signature_1.loadPackTrustRoot)({ leaseUrl: process.env.AGENTHIPPO_LEASE_URL });
-            if (next.status === 'configured') {
-                packTrust = next;
-                reportTrustRoot(next);
-                logger.info(`[Pack] signing keys now available (${Object.keys(next.keys).length}); re-verifying`);
-                verifyPackAt(activePackDir, activeVersion);
-            }
-        }
-        // The lease root gets the SAME rule, not a better one: retried only while missing, never
-        // re-fetched once configured. Improving one and not the other would leave two roots with two
-        // rotation stories, which is how the rotation runbook silently stops being true for half of it.
-        if (leaseTrust.status !== 'configured') {
-            const next = await (0, signature_1.loadLeaseTrustRoot)({ leaseUrl: process.env.AGENTHIPPO_LEASE_URL });
-            if (next.status === 'configured') {
-                leaseTrust = next;
-                if (next.explicitlyConfigured) {
-                    reportTrustRoot(next, 'lease');
-                }
-                logger.info(`[Lease] lease-signing keys now available (${Object.keys(next.keys).length})`);
-            }
-        }
-    };
-    // Record the boot policy and watch for changes on the lease-poll cadence. The lease source
-    // caches, so this adds no extra fetches — it re-reads whatever the poll already trusts.
-    void leaseSource.get().then(notePolicy).catch(() => undefined);
-    {
-        const everyMs = leasePollSeconds * 1000;
-        const policyTimer = setInterval(() => {
-            void leaseSource.get().then(notePolicy).catch(() => undefined);
-            void retrySigningKeys().catch(() => undefined);
-        }, everyMs);
-        policyTimer.unref?.();
-    }
-    if (options.pullPacks) {
-        fs.mkdirSync(packsRoot, { recursive: true });
-        // Materialise whatever we boot with, so `current` is valid before any pin is considered and
-        // the drivers can capture one stable path.
-        const bootDir = path.join(packsRoot, activeVersion);
-        if (!fs.existsSync(bootDir)) {
-            fs.cpSync(pack.packPath, bootDir, { recursive: true });
-        }
-        (0, reconcile_1.promoteCurrent)(packsRoot, bootDir);
-        activePackDir = path.join(packsRoot, reconcile_1.CURRENT_LINK);
-        await reconcileToPin((await leaseSource.get())?.version);
-        // The pack is now read through `current`, which is a different path than the one verified
-        // above. Re-verify so `packSignature` describes the tree that will actually run.
-        verifyPackAt(activePackDir, activeVersion);
-    }
-    activeVersionRef.get = () => activeVersion;
-    inProcessRunner = (0, pack_runtime_1.createPackRunner)({
-        storagePath,
-        analyticsSessionsDir,
-        packId,
-        packVersion: activeVersion,
-        provenance: () => ({
-            policyVersion: lastPolicyVersion,
-            packDigest: packDigestValue,
-            engineVersion: (0, deps_1.installedEngineVersion)(defaultEngine),
-            tier: options.sandbox === 'container' ? 2 : options.sandbox ? 0 : undefined,
-            instanceId,
-        }),
-        workspaceRoot: options.workspace,
-        credentials: {
-            apiKey: apiConfig.apiKey,
-            baseUrl: apiConfig.baseUrl,
-            useLiteLLM: apiConfig.useLiteLLM,
-            litellmApiKey: apiConfig.litellmApiKey,
-            openaiApiKey: apiConfig.openaiApiKey,
-            anthropicApiKey: apiConfig.anthropicApiKey,
-        },
-        logger,
-        permissionHandler,
-        claudeCheapModel,
-        omitGatewayToken: true,
-    });
-    // Converge on the same cadence the fleet already polls, so pinning a version in the console
-    // reaches instances without a redeploy. Errors are swallowed by reconcileToPin itself.
-    if (options.pullPacks) {
-        const every = leasePollSeconds * 1000;
-        const timer = setInterval(() => {
-            void leaseSource.get().then((l) => reconcileToPin(l?.version)).catch(() => undefined);
-        }, every);
-        timer.unref?.();
-    }
-    // Container sandboxes got NO filesystem mounts at all — the driver honours `fs`, but serve never
-    // passed it, so a sandbox's `/state/workspace` was container-private storage. Everything the
-    // agent wrote was invisible on the host and lost when the sandbox died. The process driver needs
-    // no mounts: tier 0 shares this host's filesystem already.
-    //
-    // The workspace is PER SESSION unless --shared-workspace says otherwise. One host directory
-    // mounted writable into every session's sandbox is a shared disk between users of the same
-    // agent: whatever session A writes (a query export, a downloaded file), session B reads on its
-    // next turn. That silently contradicts "one disposable sandbox per session" for everything that
-    // matters, since the container boundary does not extend to a directory both containers mount.
-    const sharedWorkspace = Boolean(options.sharedWorkspace);
-    // One sandbox per conversation unless told otherwise. Every key below derives from this, and
-    // setting it back to `session` is the whole rollback.
-    const sandboxScope = options.sandboxScope === 'user' ? 'user' : 'session';
-    const sandboxMounts = options.sandbox === 'container'
-        ? {
-            // serve's resolved pack, not the image's baked copy — the two cannot then disagree
-            // about which pack version is running.
-            readonly: [`${activePackDir}:${containerDriver_1.SANDBOX_PACK_DIR}`],
-            writable: [`${options.workspace}:${containerDriver_1.SANDBOX_WORKSPACE_DIR}`],
-        }
-        : undefined;
-    if (sandboxMounts && sharedWorkspace) {
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} --shared-workspace: every session's sandbox mounts ` +
-            `${options.workspace} read-write, so sessions can read and overwrite each other's files. ` +
-            `Only safe when all sessions belong to one trust domain.`);
-    }
-    // serve wrote that workspace as root; the sandbox runs non-root and must be able to write it too.
-    // Boot-time and once, before the first turn can arrive.
-    let sandboxImageUser;
-    if (sandboxMounts && options.sandboxImage) {
-        await (0, support_1.alignSandboxWorkspaceOwnership)({
-            exec: support_1.dockerExec,
-            image: options.sandboxImage,
-            writable: sandboxMounts.writable,
-            // A failure here is what an operator must see even without --verbose; success is noise.
-            logger: { info: (m) => logger.info(m), warn: (m) => console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${m}`) },
-        });
-        sandboxImageUser = await (0, support_1.resolveSandboxImageUser)(support_1.dockerExec, options.sandboxImage);
-    }
-    // Engine state must outlive the sandboxes that use it or the conversation restarts every time a
-    // sandbox is reaped (serve-v4-sandbox §8.4). Keyed at SANDBOX scope, under serve's own state
-    // dir: one directory per session by default, or one per user under `--sandbox-scope user`,
-    // where the sessions sharing it stay separate beneath in `provider-sessions/`.
-    const sandboxStateDirFor = (sandboxKey) => (0, support_1.ensureSandboxStateDir)(path.join(storagePath, 'sandbox-state', (0, state_sync_1.safeSessionId)(sandboxKey)), sandboxImageUser);
-    /**
-     * Mounts for ONE sandbox: the pack read-only, and a workspace only that sandbox sees.
-     *
-     * The workspace lives beside the engine state it belongs to, so the same reap/prune machinery
-     * already covers it and the agent's output stays visible on the host — the property the shared
-     * mount was added for — without being visible to every other sandbox.
-     *
-     * Keyed at sandbox scope, never narrower: the in-sandbox host chdir's here on every turn, and
-     * that is only safe while every session sharing a sandbox resolves the same directory (see the
-     * INVARIANT note in cli/commands/sandbox.ts). Under user scope this means a user's own sessions
-     * share a workspace — same trust domain, on the same terms their engine homes already shared.
-     */
-    const sandboxFsFor = async (sandboxKey) => {
-        if (!sandboxMounts) {
-            return { readonly: [], writable: [] };
-        }
-        if (sharedWorkspace) {
-            return sandboxMounts;
-        }
-        const dir = (0, support_1.ensureSandboxStateDir)(path.join(storagePath, 'sandbox-workspace', (0, state_sync_1.safeSessionId)(sandboxKey)), sandboxImageUser);
-        return { readonly: sandboxMounts.readonly, writable: [`${dir}:${containerDriver_1.SANDBOX_WORKSPACE_DIR}`] };
-    };
-    /**
-     * "May this pack run, at this version, for this session?" — signature requirement, version pin,
-     * image digest and scoped deny rules, in ONE place.
-     *
-     * Both gates call this: sandbox creation (where it decides whether a sandbox may be born) and,
-     * on deployments with no sandbox, the per-turn governor gate. Two copies of these four checks
-     * is exactly the drift this codebase keeps paying for, and the no-sandbox path having no copy
-     * at all is why `requireSignedPack` and a version pin could be switched on in the console and
-     * enforce nothing on the default deployment shape.
-     */
-    const assertPackAdmitted = (currentLease, sessionKey, userId) => {
-        const required = (0, signature_1.resolveRequireSignedPack)({
-            // The lease's demand is read FIRST and cannot be waived by any local setting — that is
-            // what keeps the requirement tighten-only now that the local default is "required".
-            lease: currentLease?.requireSignedPack,
-            localRequire: options.requireSignedPack,
-            localAllowUnsigned: allowUnsignedPack,
-        });
-        if (required) {
-            // RE-VERIFIED, not read off a boot-time boolean. In the default no-sandbox shape the
-            // engine runs in THIS process against a pack scaffolded with `fileAccess: full`, so the
-            // agent can edit its own pack directory between turns; a cached "verified once at boot"
-            // would pass every one of those later turns. `createPackVerifier` keeps this cheap — a
-            // stat-only probe in the common case, a full digest when the tree looks touched or the
-            // re-verify interval has elapsed.
-            const result = packVerifier.verify({
-                packDir: activePackDir, pack: packId, packVersion: activeVersion, keys: packTrust.keys,
-            });
-            if (result !== packSignature) {
-                packSignature = result;
-                packDigestValue = result.ok ? result.claims.digest : undefined;
-            }
-            if (!result.ok) {
-                throw new lease_1.LeaseDeniedError(packRefusalText(result));
-            }
-        }
-        // sessionKey makes admission SCOPED: a deny rule naming this session or its user refuses
-        // at the same gate that enforces the fleet-wide switch.
-        (0, lease_1.assertAdmitted)(currentLease, {
-            pack: packId,
-            version: activeVersion,
-            image: options.sandboxImage,
-            sessionKey,
-            userHash: serve_hardening_1.userNamespaceHash,
-            userId,
-        });
-    };
-    // Assigned just below; the identity closure above reads it lazily so a poll can report live
-    // sandbox count without forcing the runner to be constructed before the lease source.
-    // eslint-disable-next-line prefer-const
-    // Sandbox mode: the same HeadlessRunner shape, body relocated into a per-session sandbox.
-    // serve's turn loop below is untouched — see sandbox/sandboxRunner.ts.
-    const sandboxRunner = options.sandbox
-        ? (0, sandboxRunner_1.createSandboxRunner)({
-            driver: options.sandbox === 'container'
-                // A non-internal route network is a real weakening of the tier-2 claim, so its warning
-                // must reach an operator who did not pass --verbose.
-                ? new containerDriver_1.ContainerSandboxDriver({
-                    exec: support_1.dockerExec,
-                    socketOwner: sandboxImageUser,
-                    logger: {
-                        info: (m) => logger.info(m),
-                        warn: (m) => console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${m}`),
-                    },
-                })
-                : new processDriver_1.ProcessSandboxDriver({
-                    command: process.execPath,
-                    // --workspace is REQUIRED, not optional: a tier-0 sandbox shares this host's
-                    // filesystem, and serve sends this same path as `workspaceRoot` on every run
-                    // frame. Omitting it left the sandbox on the container-image default
-                    // (/state/workspace), so a serve-launched process sandbox died at boot with
-                    // ENOENT: mkdir '/state/workspace'.
-                    // pack.packPath, not options.agent: serve has ALREADY resolved the pack (a
-                    // name resolves against ~/.agent-hippo/agents and the workspace), and the
-                    // sandbox must run that exact directory rather than re-resolve a name from a
-                    // different cwd and possibly land on a different pack.
-                    args: [
-                        // Only forward the script path when the process actually HAS one. A
-                        // single-file build reports `process.argv[1]` as a path inside its own
-                        // virtual filesystem (`/$bunfs/root/index.js` for `bun build --compile`,
-                        // `/snapshot/...` for pkg / node SEA). Passing that made the child parse
-                        // it as the subcommand and die with `unknown command '/$bunfs/...'`, so
-                        // every tier-0 sandbox failed with a blank "sandbox channel closed".
-                        // An existence check is NOT enough to detect this: those runtimes mount
-                        // the virtual path, so `fs.existsSync` cheerfully returns true for it.
-                        ...(0, support_1.sandboxScriptArg)(),
-                        'sandbox', '--agent', activePackDir, '--stdio',
-                        '--state-dir', storagePath, '--workspace', options.workspace,
-                    ],
-                    // PID/user-namespace wrap where the host allows it (residual P4: on a
-                    // single-uid host, a concurrent tenant reads a turn's nonce from
-                    // /proc/<pid>/environ — and the claude CLI's argv from /proc/<pid>/cmdline,
-                    // which is world-readable). Default 'auto': hardened where possible, honest
-                    // warning where not; 'require' makes multi-tenant hosts fail closed.
-                    namespaceIsolation: (0, processDriver_1.namespaceIsolationFromEnv)(),
-                    logger: {
-                        info: (m) => logger.info(m),
-                        warn: (m) => console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${m}`),
-                    },
-                }),
-            image: options.sandboxImage ?? '',
-            tier: options.sandbox === 'container' ? 2 : 0,
-            ...(sandboxMounts ? { fs: sandboxMounts, fsFor: sandboxFsFor, stateDirFor: sandboxStateDirFor } : {}),
-            // The only routes a sandbox may reach. Everything else is unroutable, not merely denied.
-            routes: [
-                ...(process.env.AGENTHIPPO_DATA_MCP_URL ? [{ kind: 'data', target: process.env.AGENTHIPPO_DATA_MCP_URL }] : []),
-                ...(apiConfig.baseUrl ? [{ kind: 'inference', target: apiConfig.baseUrl }] : []),
-            ],
-            limits: { ttlSeconds: options.sandboxTtlSeconds ?? 30 * 60 },
-            provenanceEnv: () => (0, runtime_1.buildProvenanceEnv)({
-                policyVersion: lastPolicyVersion,
-                packDigest: packDigestValue,
-                engineVersion: (0, deps_1.installedEngineVersion)(defaultEngine),
-                tier: options.sandbox === 'container' ? 2 : options.sandbox ? 0 : undefined,
-                instanceId,
-            }),
-            // Kill switch + rollback, checked before a sandbox can exist. Revoking the lease stops
-            // new work fleet-wide immediately; TTL bounds the sandboxes already running.
-            // sessionKey, not sandboxKey: deny rules can name a SESSION, and under user scope the
-            // sandbox key names the user instead — checking that would stop matching them.
-            admit: async ({ sessionKey }) => {
-                const currentLease = await leaseSource.get();
-                assertPackAdmitted(currentLease, sessionKey);
-            },
-            inferenceBaseUrl: apiConfig.baseUrl,
-            // Per-sandbox inference warrant — signed, audience-bound, and naming the sandbox it was
-            // minted for. The provider key never enters a sandbox; the proxy verifies with a public
-            // key and can never mint, so a sandbox cannot re-issue itself more budget.
-            //
-            // `user` is the verified end user from the turn's credential scope, not the pack: the
-            // gateway strips caller-supplied x-litellm-metadata-user-id and re-stamps it from this
-            // claim, so the warrant is the only attribution channel that survives it — stamping
-            // packId here made every downstream user_id (LiteLLM, spend rows, evidence provenance)
-            // the pack. Every mint runs inside runWithCredential (create-time on first-turn
-            // acquire, then per-turn re-mints in RemoteEngine.stream), so the ambient credential is
-            // the turn's own. An unidentified turn gets a sandbox-scoped marker rather than
-            // silently borrowing the pack's name — the sandbox key is user-namespaced under either
-            // scope, so the marker cannot collide across identified users.
-            mintModelToken: (sandboxId, sandboxKey) => (0, support_1.mintSandboxInferenceWarrant)(warrantKey, {
-                user: (0, credential_context_1.currentCredential)()?.userId?.trim() || `anon:${sandboxKey}`,
-                pack: packId,
-                packVersion: activeVersion,
-                sandboxId,
-                tier: options.sandbox === 'container' ? 2 : 0,
-                // A sandbox outlives one turn, so its model warrant gets the full cap rather than a
-                // turn-length TTL; the spend cap, not the clock, is what bounds it.
-                ttlSeconds: 300,
-            }),
-            logger,
-            runtime: { logger, editTracker: undefined, configProvider: undefined, permissionHandler },
-        })
-        : undefined;
-    sandboxRunnerRef = sandboxRunner ?? undefined;
-    // Caps + kill switch. Enforcement is non-cooperative — it revokes a route or destroys the
-    // sandbox — so it exists only where there ARE sandboxes. Without --sandbox we say so rather than
-    // pretending a cap is in force.
-    // 0 / NaN mean "unlimited" for every one of these — `--max-turns-per-session` has documented
-    // that meaning since before caps existed, and passing its default 0 through as a real cap
-    // refused the very first turn (`turn cap reached (1/0)`, observed live).
-    const positive = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : undefined;
-    const localCaps = {
-        ...(0, caps_1.capsFromEnv)(),
-        ...(positive(options.maxTurnsPerSession) !== undefined ? { maxTurnsPerSession: options.maxTurnsPerSession } : {}),
-        ...(positive(options.maxSessionSeconds) !== undefined ? { maxSessionSeconds: options.maxSessionSeconds } : {}),
-        ...(positive(options.maxConcurrentSandboxes) !== undefined ? { maxConcurrentSandboxes: options.maxConcurrentSandboxes } : {}),
-        ...(options.capOnBreach ? { onBreach: options.capOnBreach } : {}),
-    };
-    const capsRequested = localCaps.maxTurnsPerSession !== undefined
-        || localCaps.maxSessionSeconds !== undefined
-        || localCaps.maxConcurrentSandboxes !== undefined;
-    // A deployment must be governable whether or not it runs sandboxes. Gating the governor on
-    // `sandboxRunner` meant a plain `serve` never polled its lease at all: invisible to the control
-    // plane AND immune to the kill switch, which is the opposite of what an operator configuring
-    // a lease URL is asking for. Without sandboxes the enforcement that needs one degrades (no route
-    // revocation, no concurrency bound) but the substance survives — the turn is still refused.
-    const nullSandboxes = {
-        sandboxes: () => [],
-        destroySession: async () => undefined,
-        revokeRoute: async () => undefined,
-        // There is nothing here that can stop a turn already executing in this process, so a
-        // `kill` deny rule degrades to `drain`. The governor now says so loudly instead of
-        // sweeping an empty list and reporting the rule as applied.
-        supportsInFlightTermination: false,
-    };
-    const governed = Boolean(sandboxRunner || process.env.AGENTHIPPO_LEASE_URL || capsRequested);
-    const governor = governed
-        ? (0, governor_1.createGovernor)({
-            // The lease's caps bind; local flags may tighten them and never loosen them.
-            caps: (0, caps_1.mergeCaps)((await leaseSource.get())?.caps, localCaps),
-            sandboxes: sandboxRunner ?? nullSandboxes,
-            getLease: () => leaseSource.get(),
-            pollSeconds: leasePollSeconds,
-            // Scope for deny rules: the pack this instance runs, and the same hash that namespaces
-            // session keys — so the console can name a user by email without serve holding a roster.
-            pack: packId,
-            userHash: serve_hardening_1.userNamespaceHash,
-            // Only when there is no sandbox: with one, the same checks gate a sandbox's BIRTH and
-            // running sandboxes are meant to drain on TTL. Without one, this is the only gate that
-            // exists, so an unsigned pack or an unpinned version would otherwise keep serving.
-            ...(sandboxRunner ? {} : {
-                admitPack: (sessionKey, lease) => {
-                    try {
-                        // No userId here on purpose: the governor has ALREADY evaluated the deny rules for
-                        // this turn (with its followed-user map, which this call site cannot see), so the
-                        // only thing left for this gate is the signature/pin/digest half.
-                        assertPackAdmitted(lease, sessionKey);
-                        return { allowed: true };
-                    }
-                    catch (err) {
-                        return { allowed: false, reason: err instanceof Error ? err.message : String(err) };
-                    }
-                },
-            }),
-            logger,
-            audit: (event, fields) => auditEvent(String(fields.sessionKey ?? 'instance'), event, fields),
-        })
-        : undefined;
-    if (capsRequested && !sandboxRunner) {
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} caps are configured but --sandbox is not set. Turn and duration caps still refuse the turn; the concurrency cap and route revocation need sandboxes, so those are IGNORED.`);
-    }
-    const baseRunner = sandboxRunner ?? inProcessRunner;
-    const runner = governor ? (0, governor_1.withGovernor)(baseRunner, governor) : baseRunner;
-    if (governor) {
-        governor.start();
-        const p = governor.policy();
-        // The banner prints the number an operator will be held to: worst-case kill latency is
-        // poll + cache, not the poll alone. It used to print "lease poll 30s" while the cache
-        // defaulted to 60, so a kill could take three times as long as advertised.
-        const killLatency = (0, lease_1.effectiveKillLatencySeconds)(leasePollSeconds);
-        logger.info(`[Serve] control plane: caps turns=${p.maxTurnsPerSession ?? '∞'} session=${p.maxSessionSeconds ?? '∞'}s sandboxes=${p.maxConcurrentSandboxes ?? '∞'} onBreach=${p.onBreach ?? 'revoke-inference'}; lease poll ${leasePollSeconds}s (worst-case kill latency ${killLatency}s; an admin refresh is immediate)`);
-        if (!sandboxRunner) {
-            logger.info('[Serve] no sandbox driver: a deny rule with mode=kill takes effect as DRAIN — the in-flight turn finishes and only the next one is refused.');
-        }
-        const leaseStatus = leaseSource.status();
-        if (process.env.AGENTHIPPO_LEASE_URL && !leaseStatus.requireSignedLease) {
-            logger.info('[Serve] lease signature is NOT required — set --require-signed-lease (or lease.requireSignedLease) once the control plane signs leases.');
-        }
-    }
-    /**
-     * Unattended runs (PLAN/agent-identity.md §5). Two gates, BOTH operator-side, plus a third
-     * that needs no code here: the identity must be mapped in the connector's role map or the
-     * connector fails the call closed exactly as it does for an unmapped human.
-     *
-     * Nothing in the pack participates. Enabling or disabling this never requires a re-sign.
-     */
-    const serviceIdentity = (0, serve_hardening_1.resolveServiceIdentity)();
-    if (serviceIdentity.error) {
-        // A malformed value must not degrade to "anonymous": that shape looks configured and runs
-        // every scheduled job with no identity at all.
-        console.error(`${utils_1.COLORS.red}Error:${utils_1.COLORS.reset} ${serviceIdentity.error}`);
-        process.exit(1);
-    }
-    if (serviceIdentity.warning) {
-        console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${serviceIdentity.warning}`);
-    }
-    const serviceTurnsManaged = Boolean(process.env.AGENTHIPPO_LEASE_URL);
-    /** Resolved per turn, not at boot: revoking in the console must take effect on the next poll. */
-    const serviceUserIfPermitted = async () => {
-        if (!serviceIdentity.identity) {
-            return undefined;
-        }
-        const gate = (0, lease_2.resolveAllowServiceTurns)({
-            lease: (await leaseSource.get())?.allowServiceTurns,
-            managed: serviceTurnsManaged,
-        });
-        if (!gate.allowed) {
-            // Named gate, so the operator reads which knob to turn rather than "denied".
-            auditEvent('service-turn', 'service_turn_denied', {
-                identity: (0, identity_1.hashIdentity)(serviceIdentity.identity),
-                gate: gate.gate,
-                detail: (0, lease_2.describeServiceTurnGate)(gate.gate),
-            });
-            return undefined;
-        }
-        return serviceIdentity.identity;
-    };
-    if (serviceIdentity.identity) {
-        const boot = (0, lease_2.resolveAllowServiceTurns)({ lease: undefined, managed: serviceTurnsManaged });
-        logger.info(`[Serve] unattended runs: identity configured (${serve_hardening_1.SERVICE_USER_ENV}); `
-            + (serviceTurnsManaged
-                ? 'the control plane decides per turn via lease.allowServiceTurns — absent means deny'
-                : (0, lease_2.describeServiceTurnGate)(boot.gate)));
-    }
-    if (sandboxRunner) {
-        logger.info(`[Serve] sandbox mode: ${options.sandbox} (tier ${options.sandbox === 'container' ? 2 : 0}) — engines run in per-session sandboxes`);
-        // A sandbox's ONLY model credential is the per-sandbox warrant, which is meaningful only to an
-        // inference proxy. With no proxy configured there is nothing to send it to, so the engine
-        // dials the provider bare and the first turn dies with an opaque 401/reconnect loop. Say so
-        // at boot — same reason the engine credential check above is a boot check, not a turn check.
-        if (!apiConfig.baseUrl) {
-            console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} --sandbox without an inference proxy: a sandbox holds no provider key, so model calls will fail 401. Set AGENTHIPPO_LITELLM_BASE_URL.`);
-        }
-    }
-    /** Set when `--gateway-bridge` is enabled; cleared on shutdown. */
-    let gatewayBridge = null;
-    /** True once the pack is synced and (if bridged) the gateway is connected. Drives GET /ready. */
-    let ready = false;
-    // Create HTTP server
-    let evidenceShipHandle;
-    const server = http.createServer(async (req, res) => {
-        const cors = (0, serve_hardening_1.corsHeaders)();
-        for (const [k, v] of Object.entries(cors)) {
-            res.setHeader(k, v);
-        }
-        if (req.method === 'OPTIONS') {
-            res.writeHead(204);
-            res.end();
-            return;
-        }
-        try {
-            // Liveness — always open.
-            if (req.method === 'GET' && req.url === '/health') {
-                const health = { status: 'ok' };
-                // Reported unconditionally: with only `last_ok_at`, "shipping is off" and "shipping
-                // is on but has never once succeeded" look identical to an operator and to alerting.
-                health.evidence_ship_enabled = Boolean(evidenceShipHandle);
-                const lastOk = evidenceShipHandle?.lastOkAt();
-                if (lastOk !== undefined) {
-                    health.evidence_ship_last_ok_at = new Date(lastOk).toISOString();
-                }
-                // R-13 gap detection: evidence write failures and permanently-skipped files are
-                // COUNTED now rather than swallowed, but a counter nobody can read is the same as no
-                // counter. `disabledReason` matters most — "shipping is off because
-                // AGENTHIPPO_EVIDENCE_SHIP=0" and "shipping is on and failing" produce the same
-                // `enabled: false` shaped alert otherwise.
-                const ship = (0, sessionShip_1.getEvidenceShipStatus)();
-                health.evidence_ship_disabled_reason = ship.disabledReason ?? null;
-                health.evidence_ship_consecutive_failures = ship.consecutiveFailures;
-                health.evidence_records_staged = ship.recordsStaged;
-                health.evidence_records_shipped = ship.recordsShipped;
-                // Non-zero means the record is known to be INCOMPLETE, not merely late.
-                health.evidence_records_skipped_too_old = ship.recordsSkippedTooOld;
-                health.evidence_files_skipped_too_old = ship.filesSkippedTooOld;
-                health.evidence_content_capture = ship.contentCapture;
-                if (ship.lastHeartbeatAt !== undefined) {
-                    health.evidence_ship_last_heartbeat_at = new Date(ship.lastHeartbeatAt).toISOString();
-                }
-                const writes = (0, sessionEvents_1.getSessionEventWriterStats)();
-                health.evidence_writes_ok = writes.written;
-                health.evidence_writes_failed = writes.failed;
-                if (writes.lastError) {
-                    health.evidence_write_last_error = {
-                        at: new Date(writes.lastError.at).toISOString(),
-                        event_type: writes.lastError.eventType,
-                        message: writes.lastError.message,
-                    };
-                }
-                // Governance surface: an operator asking "is this instance actually governed?" gets
-                // the answer here rather than from boot logs that have long since scrolled away.
-                const leaseState = leaseSource.status();
-                health.lease_configured = Boolean(process.env.AGENTHIPPO_LEASE_URL);
-                health.lease_signed = leaseState.signed;
-                health.lease_signature_required = leaseState.requireSignedLease;
-                health.lease_staleness_seconds = leaseState.stalenessSeconds ?? null;
-                health.lease_fail_closed = leaseState.failClosed;
-                health.pack_signature_ok = packSignature.ok;
-                health.pack_signature_required = (0, signature_1.resolveRequireSignedPack)({
-                    localRequire: options.requireSignedPack, localAllowUnsigned: allowUnsignedPack,
-                });
-                health.pack_trust_root = packTrust.status;
-                // Reported separately from the pack root: "signed leases are required and the lease
-                // keyring is unavailable" is an outage in the making, and it is invisible in
-                // `pack_trust_root`. `lease_trust_root_source` distinguishes an operator-named root
-                // from the pack-keyring fallback, which is the state that stops working on rotation.
-                health.lease_trust_root = leaseTrust.status;
-                health.lease_trust_root_source = leaseTrust.explicitlyConfigured ? 'lease' : 'pack-fallback';
-                health.kill_in_flight_supported = Boolean(sandboxRunner);
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(health));
-                return;
-            }
-            // Readiness — pack synced (+ gateway connected when bridged).
-            // Inflight/queue depth for operators and load balancers (serve-v4 P0.1).
-            if (req.method === 'GET' && req.url === '/ready') {
-                res.writeHead(ready ? 200 : 503, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    ready,
-                    inflight: turnGate.inflight,
-                    queued: turnGate.queued,
-                    max: turnGate.max,
-                }));
-                return;
-            }
-            const urlPath = req.url?.split('?')[0] ?? '';
-            if (req.method === 'GET' && landingPageHtml && (urlPath === '/' || urlPath === '/index.html')) {
-                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-                res.end(landingPageHtml);
-                return;
-            }
-            // Chat endpoint
-            if (req.method === 'POST' && urlPath === '/v1/chat') {
-                const body = await parseBody(req);
-                const userId = (0, serve_hardening_1.resolveUserId)(req.headers, body);
-                const dataToken = (0, serve_hardening_1.resolveDataToken)(req.headers);
-                // Rate-limit on the trusted proxy identity (or client IP), never the client-supplied
-                // body user_id — otherwise a caller rotates user_id per request to reset the bucket.
-                const rlKey = (0, serve_hardening_1.resolveUserId)(req.headers, undefined) ?? (0, serve_hardening_1.clientIp)(req);
-                if (!rateLimiter.tryConsume(rlKey)) {
-                    res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': String(rateLimiter.retryAfterSeconds(rlKey)) });
-                    res.end(JSON.stringify({ error: 'Rate limit exceeded' }));
-                    return;
-                }
-                // User-namespaced session key (secure-obo-design §3.4): kills cross-user session
-                // attachment via a guessed session_id. Fails closed on pinned-identity deployments.
-                const { sessionKey, sandboxKey, rejected } = (0, serve_hardening_1.resolveServeSessionKey)(body.session_id, userId, sandboxScope);
-                if (rejected) {
-                    sessionEventWriter.append('unverified', (0, base_1.generateRequestId)(), 'warrant_denied', { reason: rejected });
-                    res.writeHead(403, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'verified user identity required' }));
-                    return;
-                }
-                // Acquire before turn-limiter so a capacity reject does not burn a turn slot.
-                const release = await turnGate.acquire();
-                if (!release) {
-                    warnGateReject(`TurnGate: rejecting /v1/chat (inflight=${turnGate.inflight} queued=${turnGate.queued} max=${turnGate.max})`);
-                    res.writeHead(429, {
-                        'Content-Type': 'application/json',
-                        'Retry-After': String(serve_hardening_1.TURN_GATE_RETRY_AFTER_SECONDS),
-                    });
-                    res.end(JSON.stringify({ error: 'At capacity' }));
-                    return;
-                }
-                // Turn-scoped data capability: mint a nonce bound to the verified user; the
-                // engine gets it via per-spawn env only. Deleted in the finally — a stale
-                // engine/tool fails closed at the gateway after that (secure-obo-design §3.1).
-                let turnReg = null;
-                try {
-                    if (!turnLimiter.tryConsume(sessionKey)) {
-                        res.writeHead(429, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
-                        return;
-                    }
-                    await prepareSession(sessionKey);
-                    if (userId?.trim()) {
-                        turnReg = await registerServeTurn({ userId: userId.trim(), sessionKey, inboundToken: dataToken, edgeNonce: edgeTurnNonce(req.headers) });
-                    }
-                    const result = await (0, credential_context_1.runWithCredential)({ userId, dataToken }, () => handleChat(runner, body, sessionKey, sandboxKey, defaultEngine, defaultModel, options.workspace, permissions, userId, turnReg?.env), { onDenied: logWarrantDenied(sessionKey) });
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify(result));
-                    statePusher?.schedule(sessionKey); // per-session delta push, off the response path
-                }
-                finally {
-                    await turnReg?.release();
-                    release();
-                }
-                return;
-            }
-            // Streaming chat endpoint
-            if (req.method === 'POST' && urlPath === '/v1/chat/stream') {
-                const body = await parseBody(req);
-                const userId = (0, serve_hardening_1.resolveUserId)(req.headers, body);
-                const dataToken = (0, serve_hardening_1.resolveDataToken)(req.headers);
-                // Rate-limit on the trusted proxy identity (or client IP), never the client-supplied
-                // body user_id — otherwise a caller rotates user_id per request to reset the bucket.
-                const rlKey = (0, serve_hardening_1.resolveUserId)(req.headers, undefined) ?? (0, serve_hardening_1.clientIp)(req);
-                if (!rateLimiter.tryConsume(rlKey)) {
-                    res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': String(rateLimiter.retryAfterSeconds(rlKey)) });
-                    res.end(JSON.stringify({ error: 'Rate limit exceeded' }));
-                    return;
-                }
-                // Same user-namespaced session key + fail-closed rule as /v1/chat above.
-                const { sessionKey, sandboxKey, rejected } = (0, serve_hardening_1.resolveServeSessionKey)(body.session_id, userId, sandboxScope);
-                if (rejected) {
-                    sessionEventWriter.append('unverified', (0, base_1.generateRequestId)(), 'warrant_denied', { reason: rejected });
-                    res.writeHead(403, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'verified user identity required' }));
-                    return;
-                }
-                // Acquire BEFORE writeHead(200, SSE) so a reject still gets a clean 429.
-                const release = await turnGate.acquire();
-                if (!release) {
-                    warnGateReject(`TurnGate: rejecting /v1/chat/stream (inflight=${turnGate.inflight} queued=${turnGate.queued} max=${turnGate.max})`);
-                    res.writeHead(429, {
-                        'Content-Type': 'application/json',
-                        'Retry-After': String(serve_hardening_1.TURN_GATE_RETRY_AFTER_SECONDS),
-                    });
-                    res.end(JSON.stringify({ error: 'At capacity' }));
-                    return;
-                }
-                // Turn-scoped data capability — same rules as /v1/chat above.
-                let turnReg = null;
-                try {
-                    if (!turnLimiter.tryConsume(sessionKey)) {
-                        res.writeHead(429, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
-                        return;
-                    }
-                    await prepareSession(sessionKey);
-                    if (userId?.trim()) {
-                        turnReg = await registerServeTurn({ userId: userId.trim(), sessionKey, inboundToken: dataToken, edgeNonce: edgeTurnNonce(req.headers) });
-                    }
-                    // Fail-closed credential check MUST run before SSE writeHead(200).
-                    // Otherwise a warrant denial lands after headers are committed, the outer
-                    // catch can only append raw JSON (not an SSE error event), and the IDE
-                    // client's SSE parser falls through to emitter.done() → silent success.
-                    await (0, credential_context_1.runWithCredential)({ userId, dataToken }, async () => {
-                        res.writeHead(200, {
-                            'Content-Type': 'text/event-stream',
-                            'Cache-Control': 'no-cache',
-                            'Connection': 'keep-alive',
-                        });
-                        await handleStreamingChat(runner, body, sessionKey, sandboxKey, defaultEngine, defaultModel, options.workspace, permissions, res, userId, turnReg?.env);
-                    }, { onDenied: logWarrantDenied(sessionKey) });
-                    statePusher?.schedule(sessionKey); // per-session delta push, off the response path
-                }
-                finally {
-                    await turnReg?.release();
-                    release();
-                }
-                return;
-            }
-            // 404
-            res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Not found' }));
-        }
-        catch (err) {
-            const tooLarge = err?.tooLarge === true;
-            if (tooLarge) {
-                if (!res.headersSent) {
-                    // Connection: close — we stopped reading mid-upload; don't reuse this socket.
-                    res.writeHead(413, { 'Content-Type': 'application/json', 'Connection': 'close' });
-                }
-                res.end(JSON.stringify({ error: 'Payload too large' }));
-                return;
-            }
-            console.error('Request error:', err);
-            if (!res.headersSent) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-            }
-            res.end(JSON.stringify({ error: err instanceof Error ? err.message : 'Internal error' }));
-        }
-    });
-    // Start server
-    server.listen(options.port, bindHost, () => {
-        void (async () => {
-            console.log('');
-            console.log(BANNER_LINE);
-            console.log('Agent Hippo Server');
-            console.log(BANNER_LINE);
-            console.log(`Host:      ${bindHost}`);
-            console.log(`Port:      ${options.port}`);
-            console.log(`Engine:    ${defaultEngine}`);
-            console.log(`Model:     ${defaultModel}`);
-            if (claudeCheapModel) {
-                console.log(`Cheap:     ${claudeCheapModel}`);
-            }
-            console.log(`Workspace: ${options.workspace}`);
-            if (pack) {
-                console.log(`Pack:      ${pack.manifest.metadata.name}@${pack.manifest.metadata.version}`);
-                console.log(`Gateway:   ${gatewayAgentId}`);
-            }
-            console.log(BANNER_LINE);
-            console.log('');
-            console.log('Endpoints:');
-            console.log(`  POST http://localhost:${options.port}/v1/chat`);
-            console.log(`  POST http://localhost:${options.port}/v1/chat/stream`);
-            console.log(`  GET  http://localhost:${options.port}/health`);
-            console.log('');
-            console.log('Press Ctrl+C to stop.');
-            console.log('');
-            const shipConfig = (0, sessionShip_1.resolveSessionShipConfig)(instanceId, analyticsSessionsDir, storagePath);
-            if (shipConfig) {
-                evidenceShipHandle = (0, sessionShip_1.startSessionShipper)({
-                    ...shipConfig,
-                    logger: { info: (m) => logger.info(m), warn: (m) => console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} ${m}`) },
-                });
-            }
-            // Bind channels before bridge connect so config.patch reload does not race registration.
-            const bindSpec = options.bind?.trim();
-            if (bindSpec) {
-                try {
-                    // The captured token — the env var was stripped at boot (§10 hole 2).
-                    await bindToGatewayChannels(gatewayAgentId, bindSpec, brokerGatewayToken);
-                }
-                catch (err) {
-                    console.error(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} Failed to bind channels: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            if (options.gatewayBridge) {
-                // Egress broker (secure-obo-design §7.6): start before the bridge so the URL is in
-                // process.env when the first channel turn spawns an engine. The broker holds the
-                // gateway token; the agent presents only the turn nonce.
-                if (turnRegistry) {
-                    try {
-                        egressBroker = await (0, data_plane_1.startEgressBroker)({
-                            registry: turnRegistry,
-                            workspaceRoot: options.workspace,
-                            agentId: pack.manifest.metadata.name,
-                            send: async (handle, message, media) => {
-                                const r = await (0, outboundSend_1.sendGatewayOutboundMessage)(handle, { message, media, token: brokerGatewayToken });
-                                return { ok: r.ok, via: r.via, stdout: r.stdout, stderr: r.stderr };
-                            },
-                            logger: options.verbose ? new headless_1.ConsoleLogger('[Egress]') : new headless_1.NoOpLogger(),
-                            audit: auditEvent,
-                        });
-                        process.env[data_plane_1.EGRESS_URL_ENV] = egressBroker.url;
-                        // The token itself was stripped from process.env at boot, broker or not.
-                        console.log('OK: Egress broker on loopback — gateway token stays broker-side; agent sends via turn nonce');
-                    }
-                    catch (err) {
-                        // Fail CLOSED: without the broker, AGENTHIPPO_EGRESS_URL stays unset and the
-                        // runtime would bake the gateway token back into engine children (§7.6 undone
-                        // by a port-bind hiccup). Refuse to serve rather than degrade silently.
-                        console.error(`${utils_1.COLORS.red}Error:${utils_1.COLORS.reset} Egress broker failed to start: ${err instanceof Error ? err.message : String(err)}`);
-                        process.exit(1);
-                    }
-                }
-                try {
-                    gatewayBridge = await startServeGatewayBridge({
-                        gatewayAgentId,
-                        packName: pack.manifest.metadata.name,
-                        workspace: options.workspace,
-                        registerTurn: registerServeTurn,
-                        brokerGatewayToken,
-                        engine: defaultEngine,
-                        defaultModel,
-                        runner,
-                        permissions,
-                        turnGate,
-                        rateLimiter,
-                        turnLimiter,
-                        warnGateReject,
-                        prepareSession,
-                        sandboxScope,
-                        onTurnComplete: (sessionId) => statePusher?.schedule(sessionId),
-                        logWarrantDenied,
-                        serviceUserIfPermitted,
-                    });
-                }
-                catch (err) {
-                    console.error(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} Gateway bridge failed: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            // Pack is synced (above) and any gateway bridge is connected → ready for traffic.
-            ready = true;
-        })();
-    });
-    // Graceful shutdown — drain in-flight work, stop accepting new connections.
-    let shuttingDown = false;
-    const shutdown = () => {
-        if (shuttingDown) {
-            return;
-        }
-        shuttingDown = true;
-        ready = false; // /ready flips to 503 so a load balancer stops routing here
-        console.log('\nShutting down...');
-        void (async () => {
-            if (statePusher) {
-                try {
-                    await statePusher.flush(); // final durable push before exit
-                }
-                catch {
-                    // best-effort
-                }
-            }
-            if (gatewayBridge) {
-                try {
-                    await gatewayBridge.unregisterAgent(gatewayAgentId);
-                }
-                catch {
-                    // ignore
-                }
-                gatewayBridge = null;
-            }
-            if (dataPlane) {
-                try {
-                    await dataPlane.close();
-                }
-                catch {
-                    // best-effort
-                }
-            }
-            if (egressBroker) {
-                try {
-                    await egressBroker.close();
-                }
-                catch {
-                    // best-effort
-                }
-            }
-            // After the planes are closed, so the tail includes whatever they just wrote. SIGTERM is
-            // how every redeploy ends, and without this each one drops up to one interval of
-            // session evidence — permanently, when the state dir (and its cursor) is ephemeral.
-            if (evidenceShipHandle) {
-                try {
-                    await evidenceShipHandle.flush();
-                }
-                catch {
-                    // best-effort — never block shutdown on the evidence server being reachable
-                }
-            }
-            server.close(() => {
-                runner.dispose();
-                process.exit(0);
-            });
-            // Safety net: force exit if connections don't drain promptly.
-            setTimeout(() => {
-                runner.dispose();
-                process.exit(0);
-            }, 10_000).unref();
-        })();
-    };
-    process.on('SIGINT', shutdown);
-    process.on('SIGTERM', shutdown);
-}
-async function parseBody(req) {
-    const raw = await (0, serve_hardening_1.readBodyWithCap)(req);
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        throw new Error('Invalid JSON');
-    }
-}
-async function handleChat(runner, body, sessionKey, sandboxKey, defaultEngine, defaultModel, workspace, permissions, userId, turnEnv) {
-    const result = await runner.run({
-        engineId: resolveRequestedEngineId(body.engine, defaultEngine),
-        modelId: body.model || defaultModel,
-        message: body.message,
-        workspaceRoot: workspace,
-        // The user-namespaced key (never raw body.session_id) so engine conversation
-        // state and per-session artifacts are per-user — see resolveServeSessionKey.
-        sessionId: sessionKey,
-        // Which sandbox runs it. Equal to sessionKey unless --sandbox-scope user; ignored
-        // entirely by the in-process runner.
-        sandboxKey,
-        analyticsUserId: userId,
-        permissions,
-        turnEnv,
-    });
-    return {
-        success: result.success,
-        text: result.text,
-        thinking: result.thinking || undefined,
-        tool_calls: result.toolCalls,
-        error: result.error,
-    };
-}
-/**
- * Session key for a gateway turn. Prefers the caller's own session identifiers; when the
- * sender has a resolved identity but no session id, keys off that identity (stable, no
- * collision risk — it's unique to that sender). Only when NEITHER a session id nor an
- * identity is available does this fall back to a per-message unique key, rather than a
- * shared 'gateway-anon' bucket — a shared bucket would let two unrelated, genuinely
- * unidentified senders share one TurnLimiter budget and, when AGENTHIPPO_STATE_S3_URI is
- * set, one S3 session-state prefix (ensureSessionLocal/pushSessionState), letting one
- * anonymous sender's state be restored into another's turn.
- *
- * `durable` is false only for that one-off fallback key. A key that is by construction
- * never reused can never hit its own TurnLimiter cap and can never have prior S3 state to
- * restore or a future turn to restore it for — callers should skip per-session tracking
- * (TurnLimiter, prepareSession/ensureSessionLocal, onTurnComplete/statePusher.schedule) for
- * it entirely, rather than accumulate a permanent, never-useful entry in those stores.
- *
- * `sessionKey` is namespaced by the resolved sender identity when an explicit session id is
- * supplied (secure-obo-design §3.4 — a caller-supplied id must not attach to another
- * sender's engine session). `outboundKey` preserves the raw gateway key: the bridge records
- * reply handles under it (bridge.ts upsertGatewayOutboundHandle), so the outbound-routing
- * file must keep resolving from the un-namespaced key or reply-to-sender breaks.
- */
-function resolveGatewaySessionKey(opts, userId, scope = 'session', 
-/**
- * This turn runs as the deployment's SERVICE identity — no human behind it
- * (PLAN/agent-identity.md §5.4). Passed explicitly rather than sniffed from a prefix on
- * `userId`: deriving behaviour from the shape of an identity string is how the `"false"` class
- * of bug happens, and §5.2 deliberately allows identities with no recognisable prefix at all.
- */
-isServiceIdentity = false) {
-    if (isServiceIdentity && userId) {
-        // Two independent reasons this branch cannot reuse the durable human shape.
-        //
-        // sessionKey FRESH: TurnLimiter is a monotonic per-session counter with no window, no
-        // reset and no decay (serve-hardening.ts). A recurring job on a stable key therefore burns
-        // a LIFETIME budget one run per night and, on night maxTurnsPerSession + 1, is rejected
-        // with `turn_limit` forever — recovering only on a serve restart. A nightly job that dies
-        // after N nights, where N is a cap nobody associates with cron.
-        //
-        // sandboxKey STABLE: under the default --sandbox-scope session it would otherwise track
-        // sessionKey, so "fresh key per run" would silently mean a NEW CONTAINER every night —
-        // cold start, a new governor entry per run, and maxSessionSeconds that never accumulates.
-        // Holding it stable gives the bot one warm sandbox and, more importantly, ONE handle for
-        // caps and the kill switch.
-        //
-        // Net shape: fresh conversation, warm sandbox.
-        const stable = `gateway-${userId}`;
-        return {
-            sessionKey: `${stable}--${(0, node_crypto_1.randomUUID)()}`,
-            sandboxKey: stable,
-            // Replies must still route: the egress broker resolves this run's destinations from the
-            // raw channel key, so a cron job that messages Slack keeps working.
-            outboundKey: opts.sessionId?.trim() || opts.gatewaySessionKey?.trim() || stable,
-            // No prior state to restore and no future turn to restore it for. A batch job that
-            // silently accumulates context also silently accumulates cost; continuity across runs
-            // stays available by passing a stable session_id, which takes the durable branch below.
-            durable: false,
-        };
-    }
-    // The SAME derivation resolveServeSessionKey uses. If the two disagreed, one person reaching
-    // the same serve over HTTP and over a channel would get two sandboxes under user scope —
-    // neither the old behaviour nor the new one.
-    const userSandboxKey = userId ? `u${(0, serve_hardening_1.userNamespaceHash)(userId)}` : undefined;
-    const explicit = opts.sessionId?.trim() || opts.gatewaySessionKey?.trim();
-    if (explicit) {
-        const sessionKey = userId ? `u${(0, serve_hardening_1.userNamespaceHash)(userId)}--${explicit}` : explicit;
-        const sandboxKey = scope === 'user' && userSandboxKey ? userSandboxKey : sessionKey;
-        return { sessionKey, sandboxKey, outboundKey: explicit, durable: true };
-    }
-    if (userId) {
-        // Already keyed on the sender's own identity — no cross-user attachment surface.
-        const sessionKey = `gateway-${userId}`;
-        return {
-            sessionKey,
-            sandboxKey: scope === 'user' && userSandboxKey ? userSandboxKey : sessionKey,
-            outboundKey: sessionKey,
-            durable: true,
-        };
-    }
-    // randomUUID (122 bits), not generateRequestId (~32 bits) — this is the sole thing
-    // standing between two unrelated anonymous senders and a real collision, so it needs to
-    // be architecturally collision-free, not just statistically unlikely.
-    const anon = `gateway-anon-${(0, node_crypto_1.randomUUID)()}`;
-    // Its own sandbox, under either scope: with no identity there is no user to group by, and
-    // grouping unidentified senders would be inventing one.
-    return { sessionKey: anon, sandboxKey: anon, outboundKey: anon, durable: false };
-}
-/**
- * Gateway-channel turn admission: rate limit → turn gate (capacity) → per-session turn cap,
- * then run. Extracted from the gateway bridge's messageHandler so this is directly testable
- * without a live gateway connection — this exact sequence (mirroring the HTTP endpoints'
- * admission order) previously didn't exist for gateway-originated turns at all: channel
- * messages skipped both the identity-keyed rate limiter and the per-session turn cap.
- * Gateway channels can't receive an HTTP 429, so each rejection emits a short channel
- * message instead (best-effort — a channel-notice failure must not mask the rejection).
- */
-async function runGatewayTurn(params) {
-    const notify = async (text) => {
-        try {
-            await params.emitter?.text(text);
-            await params.emitter?.done();
-        }
-        catch {
-            // best-effort channel notice
-        }
-    };
-    if (!params.rateLimiter.tryConsume(params.rlKey)) {
-        await notify(serve_hardening_1.RATE_LIMIT_BUSY_MESSAGE);
-        return { success: false, error: 'rate_limited' };
-    }
-    // Acquire before the turn-limiter so a capacity reject does not burn a turn slot.
-    const release = await params.turnGate.acquire();
-    if (!release) {
-        params.warnGateReject(`TurnGate: rejecting gateway turn (inflight=${params.turnGate.inflight} queued=${params.turnGate.queued} max=${params.turnGate.max})`);
-        await notify(serve_hardening_1.TURN_GATE_BUSY_MESSAGE);
-        return { success: false, error: 'busy' };
-    }
-    try {
-        if (params.trackSession !== false && !params.turnLimiter.tryConsume(params.sessionKey)) {
-            await notify(serve_hardening_1.TURN_LIMIT_BUSY_MESSAGE);
-            return { success: false, error: 'turn_limit' };
-        }
-        return await params.run();
-    }
-    finally {
-        release();
-    }
-}
-/**
- * Register this serve process as an OpenClaw external agent (WebSocket `agent.run` → headless runner).
- * Enables `openclaw agent --agent <packId> --message "…"` against the same gateway.
- */
-async function startServeGatewayBridge(params) {
-    const { GatewayBridge: Bridge } = await import('../../gateway/bridge.js');
-    const DEFAULT_GATEWAY_PORT = 18789;
-    const gatewayUrl = process.env.OPENCLAW_GATEWAY_URL ?? `ws://127.0.0.1:${DEFAULT_GATEWAY_PORT}`;
-    // The captured token — OPENCLAW_GATEWAY_TOKEN is stripped from process.env at boot (§7.6,
-    // §10 hole 2), so the bridge must never depend on the env var.
-    const token = params.brokerGatewayToken;
-    const bridge = new Bridge({ gatewayUrl, token });
-    await bridge.connect();
-    await bridge.registerAgent({
-        id: params.gatewayAgentId,
-        agentId: params.packName,
-        name: `${params.packName} (CLI)`,
-        workspace: params.workspace,
-        engineId: params.engine,
-        syncOpenClawConfigAgent: true,
-        messageHandler: (message, opts) => runBridgeTurn(params, message, opts),
-    });
-    console.log(`${utils_1.COLORS.green}✓${utils_1.COLORS.reset} Gateway bridge: registered "${params.gatewayAgentId}" at ${gatewayUrl}`);
-    console.log(`${utils_1.COLORS.dim}  Gateway outbound routes: ${params.workspace}/.agent-hippo/sessions/<sessionKey>/gateway-outbound.json${utils_1.COLORS.reset}`);
-    console.log(`${utils_1.COLORS.dim}  openclaw agent --agent ${params.gatewayAgentId} --message "…"${utils_1.COLORS.reset}`);
-    return bridge;
-}
-/**
- * One gateway-bridge turn, extracted from the message handler so the shipped path is directly
- * testable.
- *
- * It was previously an inline closure inside `bridge.registerAgent`, reachable only through a live
- * OpenClaw websocket — so the composition that actually delivers unattended runs (five identity
- * sites, four session-key values, the limiter, the registry) had no test that ran it. Transcribing
- * it into a test would have been a second implementation, free to drift from the one that ships.
- */
-async function runBridgeTurn(params, message, opts) {
-    const requestedEngine = opts.engineId?.trim().toLowerCase();
-    const effectiveEngine = requestedEngine === 'custom'
-        ? params.engine
-        : (requestedEngine || params.engine);
-    // #4: the channel sender becomes the per-user user_id (analytics + per-user data scoping).
-    const peerUser = (0, serve_hardening_1.peerToUserId)(opts.peerInfo);
-    // No chat peer ⇒ this is an unattended run (cron, or a channel event with no sender).
-    // It may act as the deployment's own service identity if BOTH operator-side gates
-    // allow it (PLAN/agent-identity.md §5.6). Never on the anonymous HTTP lane — that is
-    // externally reachable, and an unauthenticated caller must not be promotable to a
-    // standing identity; this handler is the gateway-bridge lane only.
-    const svcUser = peerUser ? undefined : await params.serviceUserIfPermitted?.();
-    const effectiveUser = peerUser ?? svcUser;
-    // effectiveUser flows to FIVE places, not two. Missing any of them degrades the design
-    // silently rather than loudly — see each site below.
-    const { sessionKey, sandboxKey, outboundKey, durable } = resolveGatewaySessionKey(opts, effectiveUser, params.sandboxScope, Boolean(svcUser));
-    return runGatewayTurn({
-        rateLimiter: params.rateLimiter,
-        turnLimiter: params.turnLimiter,
-        turnGate: params.turnGate,
-        warnGateReject: params.warnGateReject,
-        // (1) Same identity-keyed cap the HTTP endpoints enforce — a channel sender is already
-        // trusted enough here to gate the OBO credential scope below, so it's trusted enough
-        // to rate-limit on directly. Unidentified senders share one 'gateway' bucket rather
-        // than being exempt from throttling entirely. A service turn gets its OWN bucket:
-        // leaving it in the shared pool would let one bot's schedule throttle every
-        // anonymous sender, and vice versa.
-        rlKey: effectiveUser ?? 'gateway',
-        sessionKey,
-        trackSession: durable,
-        emitter: opts.emitter,
-        run: async () => {
-            // A one-off anonymous sessionKey can never have prior state to restore, and
-            // nothing will ever look it up again to push state for — skip both S3 round-trips.
-            if (durable) {
-                await params.prepareSession(sessionKey);
-            }
-            // Channel-originated turns carry no inbound platform token: with the
-            // passthrough provider they fail closed at the gateway (an unlinked chat
-            // peer gets NO data credential — secure-obo-design §7.5 bind-before-
-            // credential); the identity provider maps the peer id server-side instead.
-            // egressStoreKey is the RAW gateway key (outboundKey) the bridge records reply
-            // handles under — it lets the egress broker resolve this session's bound
-            // destinations server-side (§7.6). userId gates BOTH capabilities: an
-            // unidentified peer gets neither a nonce nor an egress route.
-            // (2) Data authority.
-            const turnReg = effectiveUser?.trim()
-                ? await params.registerTurn({ userId: effectiveUser.trim(), sessionKey, egressStoreKey: outboundKey })
-                : null;
-            try {
-                // (3) Warrant + spend. The easy site to miss and the expensive one: the
-                // warrant's `user` claim reads `currentCredential()?.userId ?? anon:<sandboxKey>`,
-                // so registering without ALSO scoping here gives the bot data access under its
-                // service identity while its SPEND attributes to `anon:` — outside the per-user
-                // meter and unattributable in evidence.
-                const result = await (0, credential_context_1.runWithCredential)({ userId: effectiveUser }, () => params.runner.run({
-                    engineId: effectiveEngine,
-                    modelId: params.defaultModel,
-                    message,
-                    workspaceRoot: params.workspace,
-                    // Use the resolved sessionKey (not the raw opts fields) so the engine's own
-                    // session state and the S3 restore/push above key off the same, user-namespaced
-                    // identity. The outbound-routing file (buildSessionEnvPatch) keeps the raw
-                    // gateway key — the bridge records reply handles under it, so namespacing it
-                    // here would break reply-to-sender. See resolveGatewaySessionKey.
-                    sessionId: sessionKey,
-                    // (4) Which sandbox runs it — stable across runs for a service
-                    // identity, so a nightly job reuses one warm container.
-                    sandboxKey,
-                    gatewaySessionKey: outboundKey,
-                    // (5) Attribution. Left unset, Spotlight rows would have no user
-                    // while the warrant claims the service identity — two attribution
-                    // channels disagreeing, which is worse than one being wrong.
-                    analyticsUserId: effectiveUser,
-                    emitter: opts.emitter,
-                    permissions: params.permissions,
-                    turnEnv: turnReg?.env,
-                }), { onDenied: params.logWarrantDenied(sessionKey) });
-                if (durable) {
-                    params.onTurnComplete?.(sessionKey);
-                }
-                return { success: result.success, error: result.error };
-            }
-            finally {
-                await turnReg?.release();
-            }
-        },
-    });
-}
-/**
- * Connect to the gateway and set channel bindings for this agent.
- * Called when --bind is specified (e.g., --bind "telegram,whatsapp" or --bind "*").
- */
-async function bindToGatewayChannels(agentId, bindSpec, token) {
-    const { createAgentIDEGatewayClient } = await import('../../gateway/client.js');
-    const DEFAULT_GATEWAY_PORT = 18789;
-    const gatewayUrl = process.env.OPENCLAW_GATEWAY_URL ?? `ws://127.0.0.1:${DEFAULT_GATEWAY_PORT}`;
-    const { client, clientInfo } = createAgentIDEGatewayClient(gatewayUrl, token);
-    try {
-        await client.connect(clientInfo);
-    }
-    catch (err) {
-        throw new Error(`Cannot connect to gateway at ${gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    try {
-        let channels;
-        let channelAccountOverrides;
-        let statusPayload;
-        if (bindSpec.trim() === '*') {
-            const ctx = await (0, openclaw_channel_routing_js_1.fetchMeetAgentChannelContext)(client.request.bind(client));
-            channels = ctx.rows.map((ch) => ch.id);
-            statusPayload = ctx.statusPayload;
-        }
-        else {
-            const parsed = (0, openclaw_channel_routing_js_1.parseChannelBindSpecs)(bindSpec);
-            channels = parsed.map((p) => p.channelId);
-            channelAccountOverrides = Object.fromEntries(parsed
-                .filter((p) => p.accountId)
-                .map((p) => [p.channelId, p.accountId]));
-            if (Object.keys(channelAccountOverrides).length === 0) {
-                channelAccountOverrides = undefined;
-            }
-        }
-        if (channels.length === 0) {
-            console.log(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} No channels to bind.`);
-            return;
-        }
-        const patched = await (0, openclaw_channel_routing_js_1.applyAgentChannelBindingsViaConfigPatch)(client.request.bind(client), {
-            agentId,
-            selectedChannelIds: channels,
-            channelAccountOverrides,
-            statusPayload,
-        });
-        if (patched) {
-            console.log(`${utils_1.COLORS.green}✓${utils_1.COLORS.reset} Bound ${agentId} to: ${channels.join(', ')}`);
-        }
-        else {
-            console.log(`${utils_1.COLORS.dim}Slack already bound to ${agentId}; skipped config.patch${utils_1.COLORS.reset}`);
-        }
-    }
-    finally {
-        client.close();
-    }
-}
-async function handleStreamingChat(runner, body, sessionKey, sandboxKey, defaultEngine, defaultModel, workspace, permissions, res, userId, turnEnv) {
-    let streamEnded = false;
-    const sendEvent = (type, data) => {
-        if (streamEnded || res.writableEnded) {
-            return;
-        }
-        res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
-    };
-    const endStream = () => {
-        if (streamEnded) {
-            return;
-        }
-        streamEnded = true;
-        res.end();
-    };
-    const emitter = {
-        async thinking(delta) {
-            sendEvent('thinking', { delta });
-        },
-        async text(delta) {
-            sendEvent('text', { delta });
-        },
-        async toolStart(name, input, toolCallId) {
-            sendEvent('tool_start', { name, input, tool_call_id: toolCallId });
-        },
-        async toolEnd(name, toolCallId, result, isError) {
-            sendEvent('tool_end', { name, tool_call_id: toolCallId, result, is_error: isError });
-        },
-        async progress(message) {
-            sendEvent('progress', { message });
-        },
-        async question(payload) {
-            sendEvent('question', { payload });
-            // No sessionResource in serve path → can't use workbench askQuestions. Emit for visibility; return declined so the run continues (see PLAN/ARCHITECTURE.md § Stream Question).
-            return {
-                selected: [],
-                freeText: null,
-                declined: true,
-            };
-        },
-        async error(message) {
-            sendEvent('error', { message });
-        },
-        async done() {
-            sendEvent('done', {});
-            endStream();
-        },
-    };
-    try {
-        const result = await runner.run({
-            engineId: resolveRequestedEngineId(body.engine, defaultEngine),
-            modelId: body.model || defaultModel,
-            message: body.message,
-            workspaceRoot: workspace,
-            // The user-namespaced key (never raw body.session_id) — see resolveServeSessionKey.
-            sessionId: sessionKey,
-            sandboxKey,
-            analyticsUserId: userId,
-            emitter,
-            permissions,
-            turnEnv,
-        });
-        // A policy refusal is a RESULT, not an exception: `withGovernor` returns
-        // `{success:false, error}` without ever touching the emitter. Ignoring it sent the client
-        // HTTP 200, zero events, then `done` — a kill switch, a cap breach or a deny rule looked
-        // exactly like the agent choosing to say nothing, and the operator's reason reached nobody.
-        // /v1/chat already returns the reason in its body; the two endpoints must not disagree.
-        if (!result.success && !streamEnded) {
-            sendEvent('error', { message: result.error ?? 'refused by policy' });
-        }
-        if (!streamEnded) {
-            sendEvent('done', {});
-            endStream();
-        }
-    }
-    catch (err) {
-        sendEvent('error', { message: err instanceof Error ? err.message : 'Unknown error' });
-        endStream();
-    }
-}
-function resolveRequestedEngineId(requestedEngine, fallbackEngine) {
-    const normalizedRequested = requestedEngine?.trim().toLowerCase();
-    if (!normalizedRequested) {
-        return fallbackEngine;
-    }
-    if (normalizedRequested === 'custom') {
-        return fallbackEngine;
-    }
-    return normalizedRequested;
-}