@intentic/sandbox-contract 1.310.0 → 1.312.0

package/src/protocol/ingress-contract.fixture.json

@@ -0,0 +1,77 @@
+{
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAfiMlxPB/8tnjh6TYS3rVde63OXB/wY77KWWtJ39XjBg=\n-----END PUBLIC KEY-----\n",
+    "grants": [
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": {"sandboxId": "abcdef012345", "issuedAt": 1700000000} },
+        { "token": "ig1.eyJzdWIiOiIwMTIzNDU2Nzg5YWIiLCJpYXQiOjE3NTcwMDAwMDAsImV4dHJhIjoiaWdub3JlZCJ9.NK2BR2L_ycCACdmnbZgkg7sovw-Nhlt5vIL6ldArAx_jN9XOh-k1wisviROAgU40YGBgUASIgA6Wdn5SyYHHCA", "claim": {"sandboxId": "0123456789ab", "issuedAt": 1757000000} },
+        { "token": "ig1.eyJpYXQiOjE3MDAwMDAwMDAsInN1YiI6ImFiY2RlZjAxMjM0NSJ9.AenzYQn3Opfc-Sg_vkBrMEIOnCFZ3a46oSzjABAWyoVe3GP0vXlIM8MFgddHDQc7yow4kdfn1kHcUcsOoKkLCg", "claim": {"sandboxId": "abcdef012345", "issuedAt": 1700000000} },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wNpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eiJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.Ac2ofn7IxD3M51pchXEycOPg4TP_kiTzu-aTVowDLTirjVzYrvfJ-ntrzPbQg-3RpBhmc53yP7s7iWyOgGWuAw", "claim": null },
+        { "token": "ig2.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.", "claim": null },
+        { "token": "", "claim": null },
+        { "token": "ig1", "claim": null },
+        { "token": "ig1..", "claim": null },
+        { "token": "ig1.%%%.%%%", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJBQkNERUYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.CbPEciFki-GXJnUcS5F9_9uXUOw5tWhv3iS69BjuQpSmsA72_xnvYUIjhAMiBPI98XBQ9-zKc9GSPJIFGQqaDA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNCIsImlhdCI6MTcwMDAwMDAwMH0.qfJbxpVtbcymaweaCu9fUounkldkMy4HSdllEDlHs5Yq8b11XxiHLguDyvqubXcMGCuVVygCeg2MjU3i0vEuDA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOiIxNzAwMDAwMDAwIn0.BI6UT1aTaN01bGZyI9SHc_qIf9S-JlpmNtiBd8by_giZCq8pQIJCBKIutYZW0mmqCF0YHf0NHc9icq1h9Wr7BA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUifQ.Aa5FeLKazhsr2IvYZ2p5BJmLL1qvQWReXeCKt5gxCq9PqSaAnn8Pa6PJp0jiaXY5FIbc_S9MFrUCeEfQ6vnkBQ", "claim": null },
+        { "token": "ig1.eyJzdWIiOjEyMzQ1Njc4OTAxMiwiaWF0IjoxNzAwMDAwMDAwfQ.kb_lMTBvFS4nzTmqLf-T7l9IF8PHaPPkP5HB1T0yd0IRWqYJnIZH2eoKexv7e6aA2PkqCpe-B1FL8Nbu4qPvDg", "claim": null },
+        { "token": "ig1.bm90IGpzb24.Ffec27cYSbvKvjlxtSUIFFX7sGo3Zp4BxotW02rFwcJHfJikM51Zfzn3_0Rg8coR4y43iOUA2u-ZOcBJg4mmDA", "claim": null },
+        { "token": "ig1.bnVsbA.lFa3FNSkMcf3WCyjdb87YRVdt8h3aSzt4cignx9Rkwq6drwl12m0rlrmzdPkLjsdrQdL1oWZ2E2MGuo2CMeSBw", "claim": null },
+        { "token": "ig1.WyJhYmNkZWYwMTIzNDUiLDE3MDAwMDAwMDBd.BWFTD0bHKDBAEWwhYq6F-cWo_HXEC8UvDWkrTmafOycvTZUHvVOjWy_97OYl_pF-svCO1vbeumhF89ybhqv4Dw", "claim": null }
+    ],
+    "owners": [
+        { "host": "sandbox-abcdef012345.sbx.example.test", "owner": "abcdef012345" },
+        { "host": "sandbox-abcdef012345.sbx.example.test:443", "owner": "abcdef012345" },
+        { "host": "preview-web-app-abcdef012345.sbx.example.test:443", "owner": "abcdef012345" },
+        { "host": "port-0f0f0f0f0f0f-abcdef012345.sbx.example.dev", "owner": "abcdef012345" },
+        { "host": "public-1a2b3c4d5e6f-abcdef012345.sbx.example.dev", "owner": "abcdef012345" },
+        { "host": "SANDBOX-abcdef012345.sbx.example.test", "owner": "abcdef012345" },
+        { "host": "-abcdef012345.example.com", "owner": "abcdef012345" },
+        { "host": "sandbox-abcdef012345", "owner": "abcdef012345" },
+        { "host": "ingress.sbx.example.test", "owner": null },
+        { "host": "sbx.example.test", "owner": null },
+        { "host": "abcdef012345.local.sbx.example.dev", "owner": null },
+        { "host": "sandbox-ABCDEF012345.sbx.example.test", "owner": null },
+        { "host": "sandbox-abcdef01234.sbx.example.test", "owner": null },
+        { "host": "sandbox-abcdef012345x.sbx.example.test", "owner": null },
+        { "host": "sandbox-abcdef012345-.sbx.example.test", "owner": null },
+        { "host": "[::1]:8788", "owner": null },
+        { "host": "127.0.0.1:8788", "owner": null },
+        { "host": "", "owner": null }
+    ],
+    "lanes": [
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/media?path=a.mp4", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload?path=a", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test:443", "method": "GET", "path": "/system/runners/git/app/info/refs?service=git-upload-pack", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/system/runners/git/app/git-receive-pack", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/system/sync/ssh", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/extensions/abc/bundle", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/diff/raw?a=1?b=2", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/bundles/download?ticket=x", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload-archive", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "HEAD", "path": "/workspace/raw?path=a", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "OPTIONS", "path": "/workspace/raw", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "OPTIONS", "path": "/system/runners/git/app/git-upload-pack", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "get", "path": "/workspace/raw?path=a", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/thumb?path=a.png", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload-diff", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/system/terminal?ticket=t", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/raw", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/raw/", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/system/runners/git//info/refs", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/x/anything/at/all", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "", "lane": "interactive" },
+        { "host": "preview-web-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents", "lane": "bulk" },
+        { "host": "port-1a2b3c4d5e6f-abcdef012345.sbx.example.test", "method": "GET", "path": "/", "lane": "bulk" },
+        { "host": "Sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents", "lane": "bulk" },
+        { "host": "sbx.example.test", "method": "GET", "path": "/agents", "lane": "bulk" },
+        { "host": "", "method": "GET", "path": "/agents", "lane": "bulk" }
+    ]
+}

package/src/protocol/ingress-contract.test.ts

@@ -1,5 +1,14 @@
 import { generateKeyPairSync } from "node:crypto";
-import { hostOwnerId, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+import { readFileSync } from "node:fs";
+import { hostOwnerId, type ReachabilityGrant, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+
+// The edge's rules as both implementations must answer them; the Rust edge reads the same file. Its grants were minted
+// by a throwaway pair whose private half was never kept, so a new grant case takes a new pair and every token again.
+const FIXTURE = JSON.parse(readFileSync(new URL("./ingress-contract.fixture.json", import.meta.url), "utf8")) as {
+    readonly publicKey: string;
+    readonly grants: readonly { readonly token: string; readonly claim: ReachabilityGrant | null }[];
+    readonly owners: readonly { readonly host: string; readonly owner: string | null }[];
+};
 
 const pemPair = (): { privateKey: string; publicKey: string } => {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
@@ -31,10 +40,11 @@ describe("reachability grant", () => {
         expect(verifyReachabilityGrant(keys.publicKey, `${prefix}.${forged}.${signature}`)).toBeUndefined();
     });
 
-    it("answers undefined for garbage rather than throwing", () => {
-        const keys = pemPair();
-        for (const junk of ["", "ig1", "ig1..", "nonsense.a.b", "ig2.a.b", "ig1.%%%.%%%"]) {
-            expect(verifyReachabilityGrant(keys.publicKey, junk)).toBeUndefined();
+    it("answers every grant in the shared fixture as it states, and garbage with undefined rather than a throw", () => {
+        // Both verdicts, so the loop below can never pass by holding only one kind of case.
+        expect(new Set(FIXTURE.grants.map(({ claim }) => (claim === null ? "refused" : "accepted")))).toEqual(new Set(["accepted", "refused"]));
+        for (const { token, claim } of FIXTURE.grants) {
+            expect({ token, claim: verifyReachabilityGrant(FIXTURE.publicKey, token) ?? null }).toEqual({ token, claim });
         }
     });
 
@@ -44,27 +54,9 @@ describe("reachability grant", () => {
 });
 
 describe("hostOwnerId", () => {
-    it("owns the daemon's own name and every labelled name", () => {
-        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`preview-operator-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`port-0f0f0f0f0f0f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`public-1a2b3c4d5e6f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-    });
-
-    it("ignores a port suffix", () => {
-        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev:443`)).toBe(SANDBOX_ID);
-    });
-
-    it("owns nothing that does not end in a 12-hex tail", () => {
-        // The ingress's own door, the zone apex, the loopback name's bare-id label, and a near-miss tail.
-        for (const host of [
-            "ingress.sbx.example.dev",
-            "sbx.example.dev",
-            `${SANDBOX_ID}.local.sbx.example.dev`,
-            "sandbox-abc123def45.sbx.example.dev",
-            "",
-        ]) {
-            expect(hostOwnerId(host)).toBeUndefined();
+    it("owns every host in the shared fixture as it states, port or not", () => {
+        for (const { host, owner } of FIXTURE.owners) {
+            expect({ host, owner: hostOwnerId(host) ?? null }).toEqual({ host, owner });
         }
     });
 });

package/src/protocol/ingress-contract.ts

@@ -73,31 +73,12 @@ export const INGRESS_GRANT_HEADER = "x-intentic-grant";
 export const ENV_INGRESS_URL = "INGRESS_URL";
 export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
 
-// The daemon-side surface
-
-// Daemon-side tunnel behavior this contract requires: dial, register, forward to the loopback listener, and reconnect
-// forever with backoff, never giving up. `close()` is for shutdown and tests.
-export interface IngressTunnelOptions {
-    // e.g. https://ingress.<zone>; the daemon derives the wss:// door itself via INGRESS_TUNNEL_PATH.
-    readonly url: string;
-    readonly grant: string;
-    // The daemon's own loopback listener; every h2 stream lands there as a plain HTTP/1.1 request or upgrade.
-    readonly targetPort: number;
-    readonly log: (message: string, error?: unknown) => void;
-}
-
-export interface IngressTunnelHandle {
-    readonly close: () => Promise<void>;
-    // For /health and the boot log: whether the tunnel currently holds a registered session.
-    readonly connected: () => boolean;
-}
-
-export type StartIngressTunnel = (options: IngressTunnelOptions) => IngressTunnelHandle;
-
-// What the ingress side must also honor, enforced by ingress-protocol tests:
+// What the edge (_platform/ingress, Rust) must also honor, held by its suites and by ingress-contract.fixture.json:
 // - Register: verify the grant offline; if PLATFORM_URL is set, check the sandbox exists (GET /api/reachability/<id>)
 //   and cache the answer, failing open if the platform doesn't respond. A 404 refuses the tunnel.
 // - Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
+// - Lanes: a tunnel naming the bulk lane (tunnel-lanes.ts) is held beside the interactive one and displaces only its
+//   own kind; only the interactive lane is the sandbox's home in the cluster.
 // - Liveness: WebSocket ping every 15s; a peer silent for 45s is unregistered.
 // - Routing: host maps via hostOwnerId to a registered tunnel; no tunnel answers 502 naming the sandbox label, with
 //   the verdict header and CORS of edge-verdict.ts, and admits the preflight of the request it is about to refuse.

package/src/protocol/raw-routes.ts

@@ -8,26 +8,26 @@ import { runnerTranslatorPath } from "./runner-protocol.js";
 export const RAW_ROUTES = {
     // The "is a daemon there" probe every flow uses; it names the sandbox and says whether it is still converging.
     "GET /health": { auth: "door", beforeBoot: true },
-    "GET /diff/raw": {},
+    "GET /diff/raw": { lane: "bulk" },
     // Arming the dictation model is a read any tier makes; dictating is writing a message, the collaborator's grant.
     "GET /speech/status": { guest: true },
     "POST /speech/transcribe": { floor: "collaborator", guest: true },
     // The bytes behind the workspace reads; each applies the caller's fence itself.
-    "GET /workspace/raw": { guest: true },
+    "GET /workspace/raw": { guest: true, lane: "bulk" },
     // No door, unlike media: the page fetches a thumbnail itself, so the request carries the header.
     "GET /workspace/thumb": { guest: true },
     // Fetched by a <video>/<audio> tag, which sends no header: its scoped ticket is checked in the handler.
-    "GET /workspace/media": { auth: "door", guest: true },
+    "GET /workspace/media": { auth: "door", guest: true, lane: "bulk" },
     // An attachment is part of the message it rides with; any other target edits the shared tree.
-    "POST /workspace/upload": { floor: "writer", attachmentFloor: "collaborator" },
+    "POST /workspace/upload": { floor: "writer", attachmentFloor: "collaborator", lane: "bulk" },
     "POST /workspace/upload-diff": {},
-    "POST /workspace/upload-archive": {},
+    "POST /workspace/upload-archive": { lane: "bulk" },
     // Minting is cheap: each WebSocket upgrade floors its own redemption.
     "POST /system/ws-ticket": { beforeBoot: true, floor: "collaborator", control: "never" },
     // A WebSocket upgrade carries no Authorization header; the terminal and both browser wires check a query ticket.
-    "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never" },
+    "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never", front: true },
     // Desktop sync's byte pipe, guarded again by sshd's own key check against the same enrollment.
-    "GET /system/sync/ssh": { sync: "pipe", control: "never" },
+    "GET /system/sync/ssh": { sync: "pipe", control: "never", lane: "bulk" },
     "GET /system/browser-profile": { auth: "door", beforeBoot: true, control: "never" },
     "GET /system/browser-view": { auth: "door", beforeBoot: true, control: "never" },
     // Deploy-target enrollment, gated by the connect token.
@@ -68,7 +68,7 @@ export const RAW_ROUTES = {
     "DELETE /bundles": { control: "never" },
     "POST /bundles/ticket": { control: "never" },
     // Navigated to by the browser, so no header: its ticket is checked in the handler.
-    "GET /bundles/download": { auth: "door", control: "never" },
+    "GET /bundles/download": { auth: "door", control: "never", lane: "bulk" },
     "GET /definition": {},
     "POST /definition/diff": {},
     "GET /definition/workspace": {},
@@ -78,9 +78,14 @@ export const RAW_ROUTES = {
     "POST /arrivals/scan": {},
     "POST /arrivals/apply": {},
     "DELETE /arrivals": {},
-    "GET /extensions/{id}/bundle": {},
+    "GET /extensions/{id}/bundle": { lane: "bulk" },
     // An extension backend's own namespace, proxied verbatim.
     "ALL /x/*": {},
+    // An extension card's MCP endpoint (its manifest's `mcp`), forwarded to the backend host; the per-boot token its
+    // handler checks is the one the turn's tool config carries.
+    "POST /mcp/extensions/{id}": { auth: "door" },
+    "GET /mcp/extensions/{id}": { auth: "door" },
+    "DELETE /mcp/extensions/{id}": { auth: "door" },
     // The `capabilities` CLI: discovery by name, and the ask that parks on an owner-decided card.
     "GET /capabilities/connectable": { floor: "maintainer", agent: true, control: "never" },
     "POST /capabilities/ask": { floor: "maintainer", agent: true, control: "never" },
@@ -135,16 +140,18 @@ export const RAW_ROUTES = {
     "GET /system/runners": { control: "never" },
     "DELETE /system/runners/{id}": { control: "never" },
     "GET /system/runners/connect": { auth: "door", beforeBoot: true, control: "never" },
-    // A turn's own browser router, carrying the per-boot browser bridge token.
-    "POST /system/browser/prepare": { auth: "door", control: "never" },
+    // A turn's browser routers, hosted in the daemon; each carries its own per-turn bearer, checked by the handler.
+    "POST /mcp/browser/{id}": { auth: "door", control: "never" },
+    "GET /mcp/browser/{id}": { auth: "door", control: "never" },
+    "DELETE /mcp/browser/{id}": { auth: "door", control: "never" },
     // A connected browser's credential doors, on its durable token: a sign-in moves in (`session`) or out (`lend`).
     "POST /system/webext/session": { auth: "door", control: "never" },
     "POST /system/webext/lend": { auth: "door", control: "never" },
     "POST /system/runners/{id}/definition/sync": { control: "never" },
     // A runner's git door and credential doors, each on the runner's own bearer.
-    "GET /system/runners/git/{repo}/info/refs": { auth: "door", control: "never" },
-    "POST /system/runners/git/{repo}/git-upload-pack": { auth: "door", control: "never" },
-    "POST /system/runners/git/{repo}/git-receive-pack": { auth: "door", control: "never" },
+    "GET /system/runners/git/{repo}/info/refs": { auth: "door", control: "never", lane: "bulk" },
+    "POST /system/runners/git/{repo}/git-upload-pack": { auth: "door", control: "never", lane: "bulk" },
+    "POST /system/runners/git/{repo}/git-receive-pack": { auth: "door", control: "never", lane: "bulk" },
     "POST /system/runners/credentials": { auth: "door", control: "never" },
     "POST /system/runners/credentials/refresh": { auth: "door", control: "never" },
     [`ALL ${runnerTranslatorPath}/*` as const]: { auth: "door", control: "never" },

package/src/protocol/route-meta.ts

@@ -33,6 +33,10 @@ export interface RouteMeta {
     // Withheld from the panel token, which reaches every other route: it puts a stored credential in motion.
     readonly panel?: false;
     readonly control?: ControlReach;
+    // Rides the tunnel's bulk lane: a transfer, kept off the connection every keystroke and call waits on.
+    readonly lane?: "bulk";
+    // Served by intentic-front itself (_sandbox/front, term/): the daemon only answers the front's question about it.
+    readonly front?: true;
 }
 
 // The builder every sandbox procedure starts from, so each carries a RouteMeta and whatever it leaves out defaults.

package/src/protocol/runner-protocol.ts

@@ -188,6 +188,59 @@ export const RunnerTurnSchema = z.object({
 });
 export type RunnerTurn = z.infer<typeof RunnerTurnSchema>;
 
+// OFFLOADED COMMANDS: one shell line the parent hands a runner instead of running it itself (settings `offload`). The
+// code travels as a snapshot commit of the parent's working tree, uncommitted and untracked work included, parked under
+// this ref in the repo's git dir for the runner to fetch through the git door, and deleted once the run ends.
+export const OFFLOAD_REF_PREFIX = "refs/intentic-offload/";
+export const offloadRef = (runId: string): string => `${OFFLOAD_REF_PREFIX}${runId}`;
+const OffloadRunIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{7,63}$/u);
+const EnvNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
+
+export const RunnerCommandSchema = z.object({
+    runId: OffloadRunIdSchema,
+    // The repo id the git door serves (a /history/gits entry: `root` for the workspace itself).
+    repo: z.string().min(1),
+    // The snapshot commit's ref in that repo, always under OFFLOAD_REF_PREFIX.
+    ref: z.string().startsWith(OFFLOAD_REF_PREFIX),
+    // Where in the repo the line runs, repo-relative; "" is the repo root.
+    cwd: z.string().refine((path) => !path.startsWith("/") && !path.split("/").includes(".."), "must stay inside the repo"),
+    command: z.string().min(1).max(64_000),
+    // Values set for the line, beside the runner's own environment. Never a secret: a line that needs one runs here.
+    env: z.record(EnvNameSchema, z.string()).default({}),
+    // Variables the line writes a file to (a report path): the runner points each at a scratch file and hands the file
+    // back with the exit.
+    exports: z.array(EnvNameSchema).max(8).default([]),
+    // The heavy-command rule it matched here, named in the runner's own output and queue.
+    label: z.string().min(1).max(80),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(6 * 60 * 60_000)
+        .optional(),
+});
+export type RunnerCommand = z.infer<typeof RunnerCommandSchema>;
+
+// What a running command streams back: narration of the runner's own steps (fetch, install, queue), the line's output
+// as it comes, and last its end: the exit, every file it changed as a binary git patch against the snapshot, and the
+// exported files, base64.
+export const RunnerCommandFrameSchema = z.union([
+    z.object({ kind: z.literal("status"), text: z.string() }),
+    z.object({ kind: z.literal("output"), stream: z.enum(["stdout", "stderr"]), text: z.string() }),
+    z.object({
+        kind: z.literal("exit"),
+        code: z.number().int(),
+        signal: z.string().optional(),
+        // Why the run did not end on its own: stopped, timed out, or never started (a fetch or install that failed).
+        failure: z.string().optional(),
+        // False when the line never started there, which sends it back to run on the parent.
+        ran: z.boolean().default(true),
+        patchBase64: z.string().optional(),
+        files: z.record(EnvNameSchema, z.string()).default({}),
+    }),
+]);
+export type RunnerCommandFrame = z.infer<typeof RunnerCommandFrameSchema>;
+
 // Where a conversation runs, fixed on its first turn like `isolated` placement: later turns follow the registry, not
 // the sender. `runner` implies isolation since a remote conversation is branch-anchored; absent means local.
 export const AgentPlacementSchema = z.union([z.object({ kind: z.literal("local") }), z.object({ kind: z.literal("runner"), id: z.string().min(1) })]);

package/src/protocol/tunnel-lanes.json

@@ -0,0 +1,136 @@
+[
+    {"method":"GET","path":"/health","lane":"interactive"},
+    {"method":"GET","path":"/diff/raw","lane":"bulk"},
+    {"method":"GET","path":"/speech/status","lane":"interactive"},
+    {"method":"POST","path":"/speech/transcribe","lane":"interactive"},
+    {"method":"GET","path":"/workspace/raw","lane":"bulk"},
+    {"method":"GET","path":"/workspace/thumb","lane":"interactive"},
+    {"method":"GET","path":"/workspace/media","lane":"bulk"},
+    {"method":"POST","path":"/workspace/upload","lane":"bulk"},
+    {"method":"POST","path":"/workspace/upload-diff","lane":"interactive"},
+    {"method":"POST","path":"/workspace/upload-archive","lane":"bulk"},
+    {"method":"POST","path":"/system/ws-ticket","lane":"interactive"},
+    {"method":"GET","path":"/system/terminal","lane":"interactive"},
+    {"method":"GET","path":"/system/sync/ssh","lane":"bulk"},
+    {"method":"GET","path":"/system/browser-profile","lane":"interactive"},
+    {"method":"GET","path":"/system/browser-view","lane":"interactive"},
+    {"method":"POST","path":"/enroll","lane":"interactive"},
+    {"method":"POST","path":"/automations/{id}/fire","lane":"interactive"},
+    {"method":"POST","path":"/workflows/{id}/gate","lane":"interactive"},
+    {"method":"GET","path":"/webchat/widget.js","lane":"interactive"},
+    {"method":"GET","path":"/webchat/{id}/config","lane":"interactive"},
+    {"method":"GET","path":"/webchat/{id}/challenge","lane":"interactive"},
+    {"method":"POST","path":"/webchat/{id}/message","lane":"interactive"},
+    {"method":"GET","path":"/webchat/{id}/messages","lane":"interactive"},
+    {"method":"GET","path":"/webchat/{id}/installs","lane":"interactive"},
+    {"method":"GET","path":"/intake/sdk.js","lane":"interactive"},
+    {"method":"GET","path":"/intake/{id}/config","lane":"interactive"},
+    {"method":"GET","path":"/intake/{id}/challenge","lane":"interactive"},
+    {"method":"POST","path":"/intake/{id}/report","lane":"interactive"},
+    {"method":"GET","path":"/members","lane":"interactive"},
+    {"method":"POST","path":"/members","lane":"interactive"},
+    {"method":"DELETE","path":"/members","lane":"interactive"},
+    {"method":"DELETE","path":"/members/self","lane":"interactive"},
+    {"method":"GET","path":"/environment","lane":"interactive"},
+    {"method":"GET","path":"/environment/contents","lane":"interactive"},
+    {"method":"POST","path":"/environment/approve","lane":"interactive"},
+    {"method":"POST","path":"/environment/reject","lane":"interactive"},
+    {"method":"POST","path":"/environment/runtime-install","lane":"interactive"},
+    {"method":"GET","path":"/engines","lane":"interactive"},
+    {"method":"POST","path":"/engines/channel","lane":"interactive"},
+    {"method":"POST","path":"/engines/update","lane":"interactive"},
+    {"method":"POST","path":"/engines/revert","lane":"interactive"},
+    {"method":"GET","path":"/bundles","lane":"interactive"},
+    {"method":"POST","path":"/bundles","lane":"interactive"},
+    {"method":"DELETE","path":"/bundles","lane":"interactive"},
+    {"method":"POST","path":"/bundles/ticket","lane":"interactive"},
+    {"method":"GET","path":"/bundles/download","lane":"bulk"},
+    {"method":"GET","path":"/definition","lane":"interactive"},
+    {"method":"POST","path":"/definition/diff","lane":"interactive"},
+    {"method":"GET","path":"/definition/workspace","lane":"interactive"},
+    {"method":"POST","path":"/definition/workspace/publish","lane":"interactive"},
+    {"method":"POST","path":"/arrivals/plan","lane":"interactive"},
+    {"method":"GET","path":"/arrivals/hosts","lane":"interactive"},
+    {"method":"POST","path":"/arrivals/scan","lane":"interactive"},
+    {"method":"POST","path":"/arrivals/apply","lane":"interactive"},
+    {"method":"DELETE","path":"/arrivals","lane":"interactive"},
+    {"method":"GET","path":"/extensions/{id}/bundle","lane":"bulk"},
+    {"method":"ALL","path":"/x/*","lane":"interactive"},
+    {"method":"POST","path":"/mcp/extensions/{id}","lane":"interactive"},
+    {"method":"GET","path":"/mcp/extensions/{id}","lane":"interactive"},
+    {"method":"DELETE","path":"/mcp/extensions/{id}","lane":"interactive"},
+    {"method":"GET","path":"/capabilities/connectable","lane":"interactive"},
+    {"method":"POST","path":"/capabilities/ask","lane":"interactive"},
+    {"method":"GET","path":"/sandboxes","lane":"interactive"},
+    {"method":"POST","path":"/sandboxes","lane":"interactive"},
+    {"method":"GET","path":"/wallet/status","lane":"interactive"},
+    {"method":"POST","path":"/wallet/fetch","lane":"interactive"},
+    {"method":"GET","path":"/wallet/history","lane":"interactive"},
+    {"method":"POST","path":"/children/spawn","lane":"interactive"},
+    {"method":"GET","path":"/children/providers","lane":"interactive"},
+    {"method":"POST","path":"/children/wait","lane":"interactive"},
+    {"method":"POST","path":"/children/send","lane":"interactive"},
+    {"method":"POST","path":"/children/answer","lane":"interactive"},
+    {"method":"GET","path":"/children","lane":"interactive"},
+    {"method":"GET","path":"/fleet","lane":"interactive"},
+    {"method":"POST","path":"/fleet/message","lane":"interactive"},
+    {"method":"GET","path":"/fleet/{handle}","lane":"interactive"},
+    {"method":"GET","path":"/listeners/{provider}/state","lane":"interactive"},
+    {"method":"POST","path":"/listeners/{provider}/dispatch","lane":"interactive"},
+    {"method":"POST","path":"/listeners/{provider}/failure","lane":"interactive"},
+    {"method":"POST","path":"/listeners/{provider}/status","lane":"interactive"},
+    {"method":"POST","path":"/ci/webhook/{host}","lane":"interactive"},
+    {"method":"POST","path":"/system/sync/pair","lane":"interactive"},
+    {"method":"POST","path":"/system/hosts/pair","lane":"interactive"},
+    {"method":"POST","path":"/system/hosts/enroll","lane":"interactive"},
+    {"method":"GET","path":"/system/hosts","lane":"interactive"},
+    {"method":"DELETE","path":"/system/hosts/{id}","lane":"interactive"},
+    {"method":"GET","path":"/system/hosts/connect","lane":"interactive"},
+    {"method":"POST","path":"/mcp/hosts/{id}","lane":"interactive"},
+    {"method":"GET","path":"/mcp/hosts/{id}","lane":"interactive"},
+    {"method":"DELETE","path":"/mcp/hosts/{id}","lane":"interactive"},
+    {"method":"POST","path":"/system/webext/pair","lane":"interactive"},
+    {"method":"POST","path":"/system/webext/enroll","lane":"interactive"},
+    {"method":"GET","path":"/system/webext","lane":"interactive"},
+    {"method":"DELETE","path":"/system/webext/{id}","lane":"interactive"},
+    {"method":"GET","path":"/system/webext/connect","lane":"interactive"},
+    {"method":"POST","path":"/mcp/webext/{id}","lane":"interactive"},
+    {"method":"GET","path":"/mcp/webext/{id}","lane":"interactive"},
+    {"method":"DELETE","path":"/mcp/webext/{id}","lane":"interactive"},
+    {"method":"POST","path":"/system/runners/pair","lane":"interactive"},
+    {"method":"POST","path":"/system/runners/enroll","lane":"interactive"},
+    {"method":"GET","path":"/system/runners","lane":"interactive"},
+    {"method":"DELETE","path":"/system/runners/{id}","lane":"interactive"},
+    {"method":"GET","path":"/system/runners/connect","lane":"interactive"},
+    {"method":"POST","path":"/mcp/browser/{id}","lane":"interactive"},
+    {"method":"GET","path":"/mcp/browser/{id}","lane":"interactive"},
+    {"method":"DELETE","path":"/mcp/browser/{id}","lane":"interactive"},
+    {"method":"POST","path":"/system/webext/session","lane":"interactive"},
+    {"method":"POST","path":"/system/webext/lend","lane":"interactive"},
+    {"method":"POST","path":"/system/runners/{id}/definition/sync","lane":"interactive"},
+    {"method":"GET","path":"/system/runners/git/{repo}/info/refs","lane":"bulk"},
+    {"method":"POST","path":"/system/runners/git/{repo}/git-upload-pack","lane":"bulk"},
+    {"method":"POST","path":"/system/runners/git/{repo}/git-receive-pack","lane":"bulk"},
+    {"method":"POST","path":"/system/runners/credentials","lane":"interactive"},
+    {"method":"POST","path":"/system/runners/credentials/refresh","lane":"interactive"},
+    {"method":"ALL","path":"/system/runners/translator/*","lane":"interactive"},
+    {"method":"POST","path":"/system/control/tokens","lane":"interactive"},
+    {"method":"GET","path":"/system/control/tokens","lane":"interactive"},
+    {"method":"DELETE","path":"/system/control/tokens/{id}","lane":"interactive"},
+    {"method":"GET","path":"/system/passkeys","lane":"interactive"},
+    {"method":"POST","path":"/system/passkeys/register/options","lane":"interactive"},
+    {"method":"POST","path":"/system/passkeys/register","lane":"interactive"},
+    {"method":"POST","path":"/system/passkeys/assert/options","lane":"interactive"},
+    {"method":"POST","path":"/system/passkeys/assert","lane":"interactive"},
+    {"method":"POST","path":"/system/passkeys/policy","lane":"interactive"},
+    {"method":"POST","path":"/system/passkeys/recovery","lane":"interactive"},
+    {"method":"DELETE","path":"/system/passkeys/{id}","lane":"interactive"},
+    {"method":"POST","path":"/system/session/recover","lane":"interactive"},
+    {"method":"POST","path":"/system/sessions/revoke","lane":"interactive"},
+    {"method":"POST","path":"/system/access/disable","lane":"interactive"},
+    {"method":"POST","path":"/system/authorized-key","lane":"interactive"},
+    {"method":"GET","path":"/system/sync","lane":"interactive"},
+    {"method":"POST","path":"/system/sync/report","lane":"interactive"},
+    {"method":"DELETE","path":"/system/authorized-key","lane":"interactive"},
+    {"method":"DELETE","path":"/system/authorized-key/{machine}","lane":"interactive"}
+]

package/src/protocol/tunnel-lanes.test.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+import { type TunnelLane, tunnelLaneNamed, tunnelLaneOf, tunnelLaneTable } from "./tunnel-lanes.js";
+
+interface LaneCase {
+    readonly host: string;
+    readonly method: string;
+    readonly path: string;
+    readonly lane: TunnelLane;
+}
+
+const read = (name: string): unknown => JSON.parse(readFileSync(new URL(name, import.meta.url), "utf8"));
+const CASES = (read("./ingress-contract.fixture.json") as { lanes: LaneCase[] }).lanes;
+
+test("the table the Rust edge embeds is the raw routes' lanes as they stand (pnpm --filter @intentic/sandbox-contract lanes)", () => {
+    expect(read("./tunnel-lanes.json")).toEqual(tunnelLaneTable());
+});
+
+test("every request the shared fixture names rides the lane it states", () => {
+    expect(CASES.length).toBeGreaterThan(20);
+    for (const { host, method, path, lane } of CASES) {
+        expect({ host, method, path, lane: tunnelLaneOf(host, method, path) }).toEqual({ host, method, path, lane });
+    }
+});
+
+test("a tunnel is interactive unless its upgrade names the bulk lane", () => {
+    expect(tunnelLaneNamed("bulk")).toBe("bulk");
+    expect(tunnelLaneNamed(undefined)).toBe("interactive");
+    expect(tunnelLaneNamed("interactive")).toBe("interactive");
+    expect(tunnelLaneNamed(["bulk", "bulk"])).toBe("interactive");
+});

package/src/protocol/tunnel-lanes.ts

@@ -0,0 +1,32 @@
+import { sandboxSubdomain } from "../ids/hostnames.js";
+import { hostOwnerId } from "./ingress-contract.js";
+import { RAW_ROUTE_LIST } from "./raw-routes.js";
+import { servedRoute } from "./routes.js";
+
+// Each sandbox dials two tunnels, and each browser request rides one, so a transfer never queues a keystroke, a call or
+// an event frame behind it on one TCP connection. The front dials both (_sandbox/front tunnel.rs); the edge
+// (_platform/ingress lanes.rs) picks by the table this file emits, and falls back to the other lane while the one picked
+// is not held.
+
+export type TunnelLane = "interactive" | "bulk";
+
+// Names a tunnel's lane on its upgrade; a tunnel that names none is the interactive one.
+export const INGRESS_LANE_HEADER = "x-intentic-lane";
+
+export const tunnelLaneNamed = (header: string | string[] | undefined): TunnelLane => (header === "bulk" ? "bulk" : "interactive");
+
+// A preview's dev server (every label but the daemon's own) is bulk: a page load is hundreds of requests and its assets
+// can be large. The daemon's routes are interactive unless their policy says otherwise (RouteMeta `lane`).
+export const tunnelLaneOf = (host: string, method: string, path: string): TunnelLane => {
+    const id = hostOwnerId(host);
+    const label = host.split(":")[0]?.split(".")[0] ?? "";
+    if (id === undefined || label !== sandboxSubdomain(id)) {
+        return "bulk";
+    }
+    return servedRoute(RAW_ROUTE_LIST, [], method, path)?.meta.lane ?? "interactive";
+};
+
+// The raw routes in registration order with the lane each rides: what the Rust edge matches a daemon request against,
+// written to tunnel-lanes.json by scripts/write-lanes.mjs since the edge cannot run this file.
+export const tunnelLaneTable = (): { readonly method: string; readonly path: string; readonly lane: TunnelLane }[] =>
+    RAW_ROUTE_LIST.map(({ method, path, meta }) => ({ method, path, lane: meta.lane ?? "interactive" }));

package/src/schemas/activity.ts

@@ -20,7 +20,9 @@ export const ActivityEventSchema = z.object({
     // in: message.received, voice_utterance.received, voice_transcript.received
     // out: message.send, reaction.add, messages.read, api.call (unclassified endpoint)
     // system: gateway.login_failed, dispatch.failed, voice.session_started, voice.session_ended, automation.run,
-    // turn.started, turn.plan, turn.error, turn.completed, rule.blocked_push, rule.held_work, rule.continued_turn
+    // turn.started, turn.plan, turn.error, turn.completed, rule.held_work, deps.verify_green, deps.verify_red,
+    // deps.breakage_routed, deps.breakage_fixup, deps.breakage_waiting, deps.breakage_held, deps.breakage_resolved,
+    // deps.breakage_spent; rule.blocked_push and rule.continued_turn are retired and only appear in older logs
     type: z
         .string()
         .describe(