@agenthippo-ai/agenthippo 1.110.9 → 1.110.11

package/out/cli/commands/serve.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.serveCommand = serveCommand;
 exports.resolveGatewaySessionKey = resolveGatewaySessionKey;
 exports.runGatewayTurn = runGatewayTurn;
+exports.runBridgeTurn = runBridgeTurn;
 /**
  * Serve Command - HTTP Server
  */
@@ -66,6 +67,8 @@ 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");
@@ -221,6 +224,25 @@ async function serveCommand(options) {
     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
@@ -248,7 +270,26 @@ async function serveCommand(options) {
     // 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;
-    const auditEvent = (sessionKey, event, fields) => sessionEventWriter.append(sessionKey, (0, base_1.generateRequestId)(), event, fields);
+    /**
+     * 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;
@@ -317,7 +358,13 @@ async function serveCommand(options) {
         }
         // Sidecar: register with the connector container; serve never sees a base credential.
         if (remoteDataPlane) {
-            const r = await remoteDataPlane.registerTurn(reg);
+            // 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;
@@ -708,6 +755,9 @@ async function serveCommand(options) {
     // 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
@@ -734,25 +784,31 @@ async function serveCommand(options) {
         });
         sandboxImageUser = await (0, support_1.resolveSandboxImageUser)(support_1.dockerExec, options.sandboxImage);
     }
-    // A session's engine state must outlive its sandboxes or the conversation restarts every time a
-    // sandbox is reaped (serve-v4-sandbox §8.4). Per session, under serve's own state dir, so the
-    // existing per-session sync/prune machinery already covers it.
-    const sandboxStateDirFor = (sessionKey) => (0, support_1.ensureSandboxStateDir)(path.join(storagePath, 'sandbox-state', (0, state_sync_1.safeSessionId)(sessionKey)), sandboxImageUser);
+    // 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 session's sandbox: the pack read-only, and a workspace only this session sees.
+     * Mounts for ONE sandbox: the pack read-only, and a workspace only that sandbox sees.
      *
-     * The per-session workspace lives beside that session's engine state, 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 also being visible to every other session.
+     * 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 (sessionKey) => {
+    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)(sessionKey)), sandboxImageUser);
+        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}`] };
     };
     /**
@@ -814,6 +870,7 @@ async function serveCommand(options) {
                 // 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}`),
@@ -872,7 +929,9 @@ async function serveCommand(options) {
             }),
             // Kill switch + rollback, checked before a sandbox can exist. Revoking the lease stops
             // new work fleet-wide immediately; TTL bounds the sandboxes already running.
-            admit: async (sessionKey) => {
+            // 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);
             },
@@ -887,11 +946,11 @@ async function serveCommand(options) {
             // 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 session-scoped marker rather than
-            // silently borrowing the pack's name — sessionKey is already user-namespaced, so the
-            // marker cannot collide across identified users.
-            mintModelToken: (sandboxId, sessionKey) => (0, support_1.mintSandboxInferenceWarrant)(warrantKey, {
-                user: (0, credential_context_1.currentCredential)()?.userId?.trim() || `anon:${sessionKey}`,
+            // 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,
@@ -990,6 +1049,51 @@ async function serveCommand(options) {
             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
@@ -1111,11 +1215,11 @@ async function serveCommand(options) {
                 }
                 // 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, rejected } = (0, serve_hardening_1.resolveServeSessionKey)(body.session_id, userId);
+                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: 'session_id requires an authenticated user' }));
+                    res.end(JSON.stringify({ error: 'verified user identity required' }));
                     return;
                 }
                 // Acquire before turn-limiter so a capacity reject does not burn a turn slot.
@@ -1143,7 +1247,7 @@ async function serveCommand(options) {
                     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, defaultEngine, defaultModel, options.workspace, permissions, userId, turnReg?.env), { onDenied: logWarrantDenied(sessionKey) });
+                    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
@@ -1168,11 +1272,11 @@ async function serveCommand(options) {
                     return;
                 }
                 // Same user-namespaced session key + fail-closed rule as /v1/chat above.
-                const { sessionKey, rejected } = (0, serve_hardening_1.resolveServeSessionKey)(body.session_id, userId);
+                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: 'session_id requires an authenticated user' }));
+                    res.end(JSON.stringify({ error: 'verified user identity required' }));
                     return;
                 }
                 // Acquire BEFORE writeHead(200, SSE) so a reject still gets a clean 429.
@@ -1208,7 +1312,7 @@ async function serveCommand(options) {
                             'Cache-Control': 'no-cache',
                             'Connection': 'keep-alive',
                         });
-                        await handleStreamingChat(runner, body, sessionKey, defaultEngine, defaultModel, options.workspace, permissions, res, userId, turnReg?.env);
+                        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
                 }
@@ -1330,8 +1434,10 @@ async function serveCommand(options) {
                         turnLimiter,
                         warnGateReject,
                         prepareSession,
+                        sandboxScope,
                         onTurnComplete: (sessionId) => statePusher?.schedule(sessionId),
                         logWarrantDenied,
+                        serviceUserIfPermitted,
                     });
                 }
                 catch (err) {
@@ -1419,7 +1525,7 @@ async function parseBody(req) {
         throw new Error('Invalid JSON');
     }
 }
-async function handleChat(runner, body, sessionKey, defaultEngine, defaultModel, workspace, permissions, userId, turnEnv) {
+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,
@@ -1428,6 +1534,9 @@ async function handleChat(runner, body, sessionKey, defaultEngine, defaultModel,
         // 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,
@@ -1462,21 +1571,70 @@ async function handleChat(runner, body, sessionKey, defaultEngine, defaultModel,
  * 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) {
+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;
-        return { sessionKey, outboundKey: explicit, durable: true };
+        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.
-        return { sessionKey: `gateway-${userId}`, outboundKey: `gateway-${userId}`, durable: true };
+        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)()}`;
-    return { sessionKey: anon, outboundKey: anon, durable: false };
+    // 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,
@@ -1539,79 +1697,112 @@ async function startServeGatewayBridge(params) {
         workspace: params.workspace,
         engineId: params.engine,
         syncOpenClawConfigAgent: true,
-        messageHandler: async (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 userId = (0, serve_hardening_1.peerToUserId)(opts.peerInfo);
-            const { sessionKey, outboundKey, durable } = resolveGatewaySessionKey(opts, userId);
-            return runGatewayTurn({
-                rateLimiter: params.rateLimiter,
-                turnLimiter: params.turnLimiter,
-                turnGate: params.turnGate,
-                warnGateReject: params.warnGateReject,
-                // 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.
-                rlKey: userId ?? '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.
-                    const turnReg = userId?.trim()
-                        ? await params.registerTurn({ userId: userId.trim(), sessionKey, egressStoreKey: outboundKey })
-                        : null;
-                    try {
-                        const result = await (0, credential_context_1.runWithCredential)({ userId }, () => 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,
-                            gatewaySessionKey: outboundKey,
-                            analyticsUserId: userId,
-                            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();
-                    }
-                },
-            });
-        },
+        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 "*").
@@ -1667,7 +1858,7 @@ async function bindToGatewayChannels(agentId, bindSpec, token) {
         client.close();
     }
 }
-async function handleStreamingChat(runner, body, sessionKey, defaultEngine, defaultModel, workspace, permissions, res, userId, turnEnv) {
+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) {
@@ -1723,6 +1914,7 @@ async function handleStreamingChat(runner, body, sessionKey, defaultEngine, defa
             workspaceRoot: workspace,
             // The user-namespaced key (never raw body.session_id) — see resolveServeSessionKey.
             sessionId: sessionKey,
+            sandboxKey,
             analyticsUserId: userId,
             emitter,
             permissions,

package/out/cli/credential-context.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ON_DENIED_TIMEOUT_MS = exports.WARRANT_DENIED_REASON = void 0;
 exports.runWithCredential = runWithCredential;
 exports.currentCredential = currentCredential;
+exports.resolveEngineHomeUserKey = resolveEngineHomeUserKey;
 exports.requireUserId = requireUserId;
 /**
  * Request-scoped credential context — the "Design B" seam from serve-v3 §11.1.
@@ -23,6 +24,7 @@ exports.requireUserId = requireUserId;
  * (secure-obo-design §2/§3 — the agent gets a capability, not the credential).
  */
 const async_hooks_1 = require("async_hooks");
+const paths_1 = require("../agentpack/paths");
 /** Stable, queryable reason code for the one case runWithCredential rejects. */
 exports.WARRANT_DENIED_REASON = 'token_without_verified_user';
 /** Default bound on `onDenied` so a hung audit write cannot stall admission forever. */
@@ -78,6 +80,21 @@ async function runWithCredential(cred, fn, options) {
 function currentCredential() {
     return storage.getStore();
 }
+/**
+ * The per-user engine-home segment for this turn, from whichever source actually has it.
+ *
+ * Two processes need the same answer and only one of them can read the credential. In serve the
+ * frame is authoritative. In a sandbox child there is no frame — that is the design, the
+ * credential never crosses — so the key arrives pre-computed on the run frame and is used as-is.
+ * The frame wins where both exist, so a child cannot widen its own scope by sending a key.
+ *
+ * Every engine must go through this rather than reading the credential directly: doing the latter
+ * is what silently unscoped every sandboxed turn, and the failure was invisible because the
+ * unscoped path is a perfectly good directory that simply holds everyone's data.
+ */
+function resolveEngineHomeUserKey(fromRunFrame) {
+    return (0, paths_1.engineHomeUserKey)(storage.getStore()?.userId) ?? fromRunFrame?.trim() ?? undefined;
+}
 /**
  * Fail-closed accessor for the acting user id. Throws when there is no
  * authenticated user in scope, so a tool can never silently run unscoped.

package/out/cli/data-plane/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataPlane = exports.resolveEdgeDataPlane = exports.EdgeDataPlane = exports.resolveRemoteDataPlane = exports.RemoteDataPlane = exports.startDataPlaneSidecar = exports.EGRESS_URL_ENV = exports.startEgressBroker = exports.TURN_NONCE_HEADER = exports.TURN_NONCE_ENV = exports.DATA_MCP_URL_ENV = exports.startDataGateway = exports.TURN_META_KEY = exports.ConnectorHost = exports.identityProvider = exports.passthroughProvider = exports.resolveProvider = exports.CredentialBroker = exports.DEFAULT_TURN_DEADLINE_MS = exports.hashNonce = exports.TurnRegistry = void 0;
+exports.DataPlane = exports.resolveEdgeDataPlane = exports.EdgeDataPlane = exports.resolveRemoteDataPlane = exports.RemoteDataPlane = exports.ASSERTION_HEADER = exports.startDataPlaneSidecar = exports.EGRESS_URL_ENV = exports.startEgressBroker = exports.TURN_NONCE_HEADER = exports.TURN_NONCE_ENV = exports.DATA_MCP_URL_ENV = exports.startDataGateway = exports.TURN_META_KEY = exports.ConnectorHost = exports.identityProvider = exports.passthroughProvider = exports.resolveProvider = exports.CredentialBroker = exports.DEFAULT_TURN_DEADLINE_MS = exports.hashNonce = exports.TurnRegistry = void 0;
 exports.resolveDataPlaneConfig = resolveDataPlaneConfig;
 /**
  * DataPlane — orchestration of the credential broker + data-plane gateway
@@ -75,6 +75,7 @@ Object.defineProperty(exports, "startEgressBroker", { enumerable: true, get: fun
 Object.defineProperty(exports, "EGRESS_URL_ENV", { enumerable: true, get: function () { return egress_1.EGRESS_URL_ENV; } });
 var sidecar_1 = require("./sidecar");
 Object.defineProperty(exports, "startDataPlaneSidecar", { enumerable: true, get: function () { return sidecar_1.startDataPlaneSidecar; } });
+Object.defineProperty(exports, "ASSERTION_HEADER", { enumerable: true, get: function () { return sidecar_1.ASSERTION_HEADER; } });
 var remote_1 = require("./remote");
 Object.defineProperty(exports, "RemoteDataPlane", { enumerable: true, get: function () { return remote_1.RemoteDataPlane; } });
 Object.defineProperty(exports, "resolveRemoteDataPlane", { enumerable: true, get: function () { return remote_1.resolveRemoteDataPlane; } });