@intentic/sandbox-contract 1.312.0 → 1.313.0

package/src/models/plan-pools.ts

@@ -1,10 +1,11 @@
-import type { AccountUsage, UsageWindow, WindowGates } from "../schemas/providers/plan-limits.js";
+import type { AccountState, AccountUsage, ProviderRefusal, UsageWindow, WindowGates } from "../schemas/providers/plan-limits.js";
 
 // Single reading of which account pool gates a given model (or, with none named, the account's tightest pool), shared
 // by the daemon's picker/refusal logic and the browser's rings and rail. A pool gated `none` is excluded from the
 // no-model case: visible to the account, never a gate on a turn.
 
-// 100 = exhaustion (the call will be refused), not the browser's 90% warning threshold (usageStatus SPENT_PERCENT).
+// 100 = exhaustion (the call will be refused). The one spent line: the daemon's pickers and every surface read it, and
+// anything short of it still has room.
 export const SPENT_UTILIZATION = 100;
 
 export interface ModelRef {
@@ -132,3 +133,152 @@ export const windowLive = (window: UsageWindow, measuredAt: number, now: number)
     const period = windowPeriod(window);
     return period === undefined || measuredAt + period.seconds * 1000 > now;
 };
+
+// Whether an account can serve a turn: the one rule every picker and surface reads (AccountState). The daemon runs it and
+// publishes the verdict on each account row; the editor runs it only on a row from a daemon older than that field.
+
+/** Everything the serviceability rule reads of one account, as the account rows already carry it. */
+export interface ServiceFacts {
+    // The daemon's key: a native account's id, a routed credential's auth-file name.
+    readonly account: string;
+    readonly needsReauth?: boolean | undefined;
+    // Why the sign-in needs renewing, where the provider said.
+    readonly detail?: string | undefined;
+    readonly seatRefusal?: string | undefined;
+    readonly cooling?: { readonly until?: number | undefined; readonly reason?: string | undefined } | undefined;
+    readonly usage?: AccountUsage | undefined;
+}
+
+// A spent allowance is over once a reading with room lands after it; a refused credential once any reading does (the
+// token worked). Nothing a reading says answers an entitlement refusal: a seatless account authenticates and reads fine.
+const answers = (refusal: ProviderRefusal, facts: ServiceFacts): boolean => {
+    const measuredAt = facts.usage?.measuredAt;
+    if (refusal.kind === "entitlement" || measuredAt === undefined || measuredAt <= refusal.at) {
+        return false;
+    }
+    if (refusal.kind === "auth") {
+        return facts.needsReauth !== true;
+    }
+    const binding = bindingWindow(facts.usage);
+    return binding !== undefined && binding.utilization < SPENT_UTILIZATION;
+};
+
+/**
+ * How a provider's last refusal stands against everything read since, over every account the provider holds: `gone` once
+ * the account it named is disconnected, `answered` once that account (or, for a refusal naming none, any account) has a
+ * later reading that contradicts it, else `standing`. An empty list is one not loaded yet, so the refusal stands.
+ */
+export const refusalVerdict = (refusal: ProviderRefusal, accounts: readonly ServiceFacts[]): "standing" | "answered" | "gone" => {
+    const named = accounts.filter((facts) => facts.account === refusal.account);
+    if (refusal.account !== undefined && named.length === 0) {
+        return accounts.length === 0 ? "standing" : "gone";
+    }
+    return (refusal.account === undefined ? accounts : named).some((facts) => answers(refusal, facts)) ? "answered" : "standing";
+};
+
+// The account reopens for this question when the pools holding it shut do: all of them for a model's own question (or
+// the pools gating every model), the first to reopen when only per-model slices are full. Unknown if any is unpublished.
+const reopening = (full: readonly UsageWindow[], first: boolean): number | undefined => {
+    const resets = full.flatMap((window) => (window.resetsAt === undefined ? [] : [window.resetsAt]));
+    return resets.length === full.length && resets.length > 0 ? (first ? Math.min(...resets) : Math.max(...resets)) : undefined;
+};
+
+const spent = (reopensAt: number | undefined): AccountState => (reopensAt === undefined ? { kind: "spent" } : { kind: "spent", reopensAt });
+
+/**
+ * The plan-limit half of the verdict, at the contract's one spent line. With a model, the pools that model spends: spent
+ * once any is full, else the room the fullest leaves. With none, whether the account can serve SOME turn: spent once a
+ * pool gating every model is full, or every per-model slice is; a full slice alone (Opus at 100%) leaves the other
+ * models their room, which is then read off the fullest pool still open.
+ */
+export const headroomState = (usage: AccountUsage | undefined, model?: ModelRef): AccountState => {
+    const windows = gatingWindows(usage, model);
+    if (windows.length === 0) {
+        return { kind: "unknown" };
+    }
+    const full = windows.filter((window) => window.utilization >= SPENT_UTILIZATION);
+    const open = windows.filter((window) => window.utilization < SPENT_UTILIZATION);
+    if (model !== undefined || full.some((window) => window.gates === "all") || open.length === 0) {
+        const holding = model !== undefined ? full : full.some((window) => window.gates === "all") ? full.filter((window) => window.gates === "all") : full;
+        if (holding.length > 0) {
+            return spent(reopening(holding, model === undefined && !holding.some((window) => window.gates === "all")));
+        }
+    }
+    return { kind: "ready", room: SPENT_UTILIZATION - Math.max(...open.map((window) => window.utilization)) };
+};
+
+// A standing limit refusal reads its pool as full, since a polled reading freezes the moment a pool actually empties: the
+// pool the refused turn's model spends, else the one asked about, else the tightest. Never another model's allowance.
+const refusedPool = (usage: AccountUsage | undefined, refusal: ProviderRefusal, model: ModelRef | undefined): AccountState => {
+    const refusedModel = refusal.model === undefined ? model : { id: refusal.model };
+    const binding = bindingWindow(usage, refusedModel);
+    if (usage === undefined || binding === undefined) {
+        // No pool to pin: the refusal itself is the evidence, unless it was about a different model than this question.
+        const sameModel = refusal.model === undefined || model === undefined || refusal.model === model.id;
+        return sameModel ? { kind: "spent" } : headroomState(usage, model);
+    }
+    const pinned = usage.windows.map((window) => (window === binding ? { ...window, utilization: Math.max(window.utilization, SPENT_UTILIZATION) } : window));
+    return headroomState({ ...usage, windows: pinned }, model);
+};
+
+/**
+ * One account's verdict. `refusal` is the provider's last refusal only when it still stands and covers this account
+ * (serviceStates decides that). Precedence: a revoked sign-in outranks a lost seat (reconnecting fixes one, nothing here
+ * fixes the other), both outrank a standing refusal, then a translator bench, then the plan limits.
+ */
+export const serviceState = (facts: ServiceFacts, refusal?: ProviderRefusal, model?: ModelRef, now: number = Date.now()): AccountState => {
+    if (facts.needsReauth === true) {
+        return { kind: "blocked", fix: "reconnect", reason: facts.detail ?? "sign-in expired" };
+    }
+    if (facts.seatRefusal !== undefined) {
+        return { kind: "blocked", fix: "admin", reason: facts.seatRefusal };
+    }
+    if (refusal?.kind === "auth") {
+        return { kind: "blocked", fix: "reconnect", reason: refusal.message };
+    }
+    if (refusal?.kind === "entitlement") {
+        return { kind: "blocked", fix: "admin", reason: refusal.message };
+    }
+    const cooling = facts.cooling;
+    // A bench with no instant is one no wait lifts (a Google account with no project): somebody has to connect again.
+    if (cooling !== undefined && cooling.until === undefined) {
+        return { kind: "blocked", fix: "reconnect", reason: cooling.reason ?? "benched by the translator" };
+    }
+    if (cooling?.until !== undefined && cooling.until * 1000 > now) {
+        return { kind: "blocked", fix: "wait", reason: cooling.reason ?? "cooling down", until: cooling.until };
+    }
+    return refusal?.kind === "limit" ? refusedPool(facts.usage, refusal, model) : headroomState(facts.usage, model);
+};
+
+/** Every account of one provider, judged together, since a refusal naming no account is answered by any of them. */
+export const serviceStates = (
+    accounts: readonly ServiceFacts[],
+    refusal: ProviderRefusal | undefined,
+    model?: ModelRef,
+    now: number = Date.now(),
+): ReadonlyMap<string, AccountState> => {
+    const standing = refusal !== undefined && refusalVerdict(refusal, accounts) === "standing" ? refusal : undefined;
+    return new Map(
+        accounts.map((facts) => [
+            facts.account,
+            serviceState(facts, standing !== undefined && (standing.account ?? facts.account) === facts.account ? standing : undefined, model, now),
+        ]),
+    );
+};
+
+// Worst last: proven room, no reading either way, known spent, and nothing a turn can run on.
+const PREFERENCE: Record<AccountState["kind"], number> = { ready: 0, unknown: 1, spent: 2, blocked: 3 };
+
+/** The account an unnamed turn runs on: ready by most room, then unmeasured, then spent, blocked only when that is all there is. Ties keep the caller's order. */
+export const preferredAccount = <T extends { readonly state: AccountState }>(entries: readonly T[]): T | undefined =>
+    entries.reduce<T | undefined>((best, next) => {
+        if (best === undefined) {
+            return next;
+        }
+        const tier = PREFERENCE[next.state.kind] - PREFERENCE[best.state.kind];
+        return tier < 0 || (tier === 0 && next.state.kind === "ready" && best.state.kind === "ready" && next.state.room > best.state.room) ? next : best;
+    }, undefined);
+
+/** The roomiest account with proven room, or none: what a move off a refused account may land on. Ties keep the caller's order. */
+export const roomiestAccount = <T extends { readonly state: AccountState }>(entries: readonly T[]): T | undefined =>
+    preferredAccount(entries.filter((entry) => entry.state.kind === "ready"));

package/src/policy/request-status.ts

@@ -1,5 +1,6 @@
-import type { RequestField, TranscriptRequests, TranscriptRow } from "../events/transcript.js";
+import { REQUEST_FIELDS, type RequestField, type TranscriptRequests, type TranscriptRow } from "../events/transcript.js";
 import type { AgentReply } from "../schemas/providers/plan-limits.js";
+import { startedChildCard } from "../events/child-run.js";
 
 // How a reply settles the card it answers: one rule used both by the fold and by a chat freezing its own card
 // optimistically before the frame returns. No reply (turn stopped or died) reads as cancelled for every card; a reply
@@ -22,7 +23,7 @@ export const settledRequests = (cards: TranscriptRequests, reply: AgentReply | u
     }
     if (permission !== undefined) {
         out.permission = {
-            ...permission,
+            ...startedChildCard(permission, reply),
             status:
                 reply?.kind !== "permission"
                     ? "cancelled"
@@ -65,16 +66,7 @@ export const settledRequests = (cards: TranscriptRequests, reply: AgentReply | u
 export const cancelledRequests = (cards: TranscriptRequests): TranscriptRequests => {
     const out: Cards = {};
     let changed = false;
-    for (const field of [
-        "plan",
-        "question",
-        "permission",
-        "browserHelp",
-        "terminalHelp",
-        "capabilityOffer",
-        "paymentOffer",
-        "credentialOffer",
-    ] as const) {
+    for (const field of REQUEST_FIELDS) {
         const card = cards[field];
         if (card === undefined) {
             continue;

package/src/policy/reserved-servers.test.ts

@@ -24,6 +24,12 @@ describe("reserved MCP server names", () => {
 });
 
 describe("collidesWithReservedServer", () => {
+    // Derived from the manifest schema's meanings: a cli card mints a server when it serves tools, a device and a
+    // connected browser always do, and `mcp` is the core kind that is its own endpoint.
+    test("the minting kinds are exactly the ones whose id becomes a server name", () => {
+        expect([...MCP_SERVER_MINTING_KINDS].toSorted()).toEqual(["cli", "device", "mcp", "webext"]);
+    });
+
     test("a kind whose id becomes a server name may not reuse a reserved one", () => {
         for (const kind of MCP_SERVER_MINTING_KINDS) {
             for (const name of RESERVED_MCP_SERVER_NAMES) {

package/src/policy/reserved-servers.ts

@@ -1,4 +1,5 @@
-// The MCP servers the daemon mounts in its OWN process, and whether each carries content from outside this container.
+import { contributedServerMintingKinds } from "@intentic/extension-manifest";
+// The MCP servers the daemon mounts under its own names, and whether each carries content from outside this container.
 // One source of truth: the outside-content guard's exemption list is the `control` subset of this, and a capability
 // whose id would become `mcp__<id>__…` is refused when the id is one of these, so nothing the owner configures can
 // shadow a daemon server. A daemon server's name is what reaches the model as the `mcp__<name>__` prefix.
@@ -8,9 +9,9 @@
 // - outside: the server carries content from beyond the container (a web page, a provider's verbatim sentence)
 export type ServerProvenance = "control" | "outside";
 
-// Every server agent/run/agent.ts and agent/run/harness/harness-servers.ts mount themselves; the browser router's two
-// names (web, browser) come in through `...turn.browser.servers`, so they are named here rather than discovered by the
-// text scan. A server added anywhere else without a row here fails the conformance test in the sandbox guard package.
+// Every server agent/run/agent.ts and agent/run/harness/harness-servers.ts mount themselves, plus the browser router's two
+// names (web, browser), which every turn mounts on its lease at the daemon's MCP door (browser-tools.ts) and which the
+// text scan reads from their constants. A server added anywhere else without a row here fails the conformance test in the sandbox guard package.
 export const DAEMON_MCP_SERVERS: Readonly<Record<string, ServerProvenance>> = {
     ui: "control", // agent.ts: AskUserQuestion
     accounts: "control", // agent.ts: the account roster and the credential typists
@@ -22,8 +23,8 @@ export const DAEMON_MCP_SERVERS: Readonly<Record<string, ServerProvenance>> = {
     watch: "control", // harness: condition watches
     deps: "control", // harness: dependency readiness
     diagnostics: "outside", // harness: two tools relay a provider's own sentence verbatim
-    web: "outside", // harness browser: the anonymous router; the page is the internet
-    browser: "outside", // harness browser: the signed-in router; the page is the internet
+    web: "outside", // the turn's mounts: the anonymous browser router; the page is the internet
+    browser: "outside", // the turn's mounts: the signed-in browser router; the page is the internet
 };
 
 // Every daemon-mounted server name, the set a capability id may not collide with.
@@ -37,10 +38,12 @@ export const CONTROL_MCP_SERVERS: ReadonlySet<string> = new Set(
         .map(([name]) => name),
 );
 
-// Capability kinds whose id becomes an MCP server name for the turn (`mcp` → its own endpoint; `device`/`webext` → the
-// loopback peer bridge), and so whose id must not collide with a daemon server. Other kinds mint accounts, providers or
-// infrastructure, never a `mcp__<id>__` server keyed by the id.
-export const MCP_SERVER_MINTING_KINDS: ReadonlySet<string> = new Set(["mcp", "device", "webext"]);
+// Capability kinds whose id becomes an MCP server name for the turn, and so whose id must not collide with a daemon
+// server: `mcp`, a core kind that is its own endpoint, and every contributable kind the manifest schema says mints one
+// (a device's and a connected browser's peer bridge, a cli card that serves tools), read off the schema's own meaning
+// (`contributedServerMintingKinds`), so a kind that starts minting is refused here without a second list. Other kinds
+// mint accounts, providers or infrastructure, never a `mcp__<id>__` server keyed by the id.
+export const MCP_SERVER_MINTING_KINDS: ReadonlySet<string> = new Set(["mcp", ...contributedServerMintingKinds()]);
 
 // Whether adding or renaming a capability of this kind to this id would shadow a daemon server. The one predicate the
 // capability routes consult, so the refusal and this list can't drift.

package/src/policy/turned-away.ts

@@ -5,6 +5,9 @@
 // A set rather than a run of case labels: what they share is a fact about the turn, not a shape.
 const TURNED_AWAY: ReadonlySet<string> = new Set([
     "claude-reauth",
+    // An organisation turned the account's Claude Code access off, or no account of the provider can serve: the next
+    // turn is routed off it (the daemon's blocked-account route), so the words wait for it rather than being spent.
+    "claude-not-entitled",
     "unknown-command",
     "context-window-too-small",
     "sandbox-memory-low",

package/src/protocol/edge-verdict.ts

@@ -3,19 +3,21 @@
 // JavaScript unless the responder allows it — so the verdict rides an exposed header and the edge CORS-allows its own
 // errors. Ingress writes it, the editor's connection machine reads it; both sides import this file so they cannot drift.
 
+import type { EdgeVerdict } from "../front/generated/browser-wire.js";
+
 export const EDGE_VERDICT_HEADER = "x-intentic-edge";
 
-export type EdgeVerdict =
-    // No tunnel is registered for this sandbox: its container is not running, or the machine it runs on is off.
-    // Retrying is right — a container that comes back redials within seconds.
-    | "no-tunnel"
-    // The platform has no such sandbox. The row is deleted, no tunnel for this id will ever be accepted again, and
-    // nothing the reader waits for can change that.
-    | "unknown-sandbox"
-    // A tunnel was held and the forward failed mid-flight: the box went away between being routed to and answering.
-    | "dropped";
-
-const VERDICTS: ReadonlySet<string> = new Set(["no-tunnel", "unknown-sandbox", "dropped"]);
+// The verdicts themselves are the edge's (browser-wire's `EdgeVerdict`), each documented there:
+// - no-tunnel: no tunnel is registered for this sandbox, and retrying is right, since a container that comes back redials
+//   within seconds;
+// - unknown-sandbox: the platform has no such sandbox, and nothing the reader waits for can change that;
+// - dropped: a tunnel was held and the forward failed mid-flight.
+export type { EdgeVerdict };
+
+// Every verdict, so a new one in the Rust enum fails this file's typecheck until it is read here too.
+const VERDICTS: ReadonlySet<string> = new Set(
+    Object.keys({ "no-tunnel": true, "unknown-sandbox": true, dropped: true } satisfies Record<EdgeVerdict, true>),
+);
 
 // A header value only counts when it is one of ours: a 502 from anything else on the path (a corporate proxy, a CDN)
 // carries no verdict and must not be read as one.

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

@@ -44,6 +44,19 @@
         { "host": "127.0.0.1:8788", "owner": null },
         { "host": "", "owner": null }
     ],
+    "bulk": [
+        "GET /diff/raw",
+        "GET /workspace/raw",
+        "GET /workspace/media",
+        "POST /workspace/upload",
+        "POST /workspace/upload-archive",
+        "GET /system/sync/ssh",
+        "GET /bundles/download",
+        "GET /extensions/{id}/bundle",
+        "GET /system/runners/git/{repo}/info/refs",
+        "POST /system/runners/git/{repo}/git-upload-pack",
+        "POST /system/runners/git/{repo}/git-receive-pack"
+    ],
     "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" },

package/src/protocol/ingress-contract.ts

@@ -63,8 +63,9 @@ export const hostOwnerId = (host: string): string | undefined => {
 
 // Wire constants
 
-// Tunnel door on the ingress; versioned so a v2 session shape adds a new path instead of replacing this one.
-export const INGRESS_TUNNEL_PATH = "/tunnel/v1";
+// Tunnel door on the ingress (the tunnel crate's TUNNEL_PATH); versioned, so a new session shape adds a path. `/tunnel/v1`
+// is the edge's alone to answer now, for fronts that predate this one.
+export const INGRESS_TUNNEL_PATH = "/tunnel/v2";
 
 // Grant travels as a header on the tunnel upgrade; this connection is never a browser's.
 export const INGRESS_GRANT_HEADER = "x-intentic-grant";
@@ -77,9 +78,12 @@ export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
 // - 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.
+// - Streams: every exchange is a stream of its own carrying HTTP/1.1 (yamux over a WebSocket, or QUIC). Over TCP a
+//   transfer rides the bulk socket: a preview's request, or a route the front announced (tunnel-bulk.ts); over QUIC a
+//   stream that sends a megabyte without pausing yields to the others.
+// - Liveness: the front pings 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.
 // - The tunnel door and any host without a sandbox id are served directly by the ingress, never routed.
+// - `/health` lists the tunnel doors the build serves (`"doors":["/tunnel/v1","/tunnel/v2"]`); a sandbox image moves
+//   onto a tag sandboxes pull only once the live edge lists INGRESS_TUNNEL_PATH (_tools/scripts/image/require-edge-door.sh).

package/src/protocol/raw-routes.ts

@@ -81,11 +81,6 @@ export const RAW_ROUTES = {
     "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" },
@@ -107,11 +102,12 @@ export const RAW_ROUTES = {
     "GET /fleet": { agent: true },
     "POST /fleet/message": { agent: true },
     "GET /fleet/{handle}": { agent: true },
-    // An extension gateway's realtime-listener control, reached with the panel token.
-    "GET /listeners/{provider}/state": {},
-    "POST /listeners/{provider}/dispatch": {},
-    "POST /listeners/{provider}/failure": {},
-    "POST /listeners/{provider}/status": {},
+    // An extension gateway's realtime-listener control: /state hands back its connectors' stored credentials, so only the
+    // extension token of the extension declaring that `listener.provider` reaches them, checked in the handler too.
+    "GET /listeners/{provider}/state": { floor: "maintainer", panel: false, control: "never" },
+    "POST /listeners/{provider}/dispatch": { panel: false, control: "never" },
+    "POST /listeners/{provider}/failure": { panel: false, control: "never" },
+    "POST /listeners/{provider}/status": { panel: false, control: "never" },
     // The CI webhook receiver, gated by the per-sandbox webhook secret.
     "POST /ci/webhook/{host}": { auth: "door" },
     // Below maintainer a pairing is capped to port-mirror, so a collaborator may mint a preview tunnel.
@@ -123,27 +119,20 @@ export const RAW_ROUTES = {
     "DELETE /system/hosts/{id}": { control: "never" },
     // A peer's socket reconnects on its own backoff, so it answers before boot.
     "GET /system/hosts/connect": { auth: "door", beforeBoot: true, control: "never" },
-    // The MCP bridge onto a peer, carrying the per-boot bridge token its handler checks.
-    "POST /mcp/hosts/{id}": { auth: "door" },
-    "GET /mcp/hosts/{id}": { auth: "door" },
-    "DELETE /mcp/hosts/{id}": { auth: "door" },
     "POST /system/webext/pair": { control: "never" },
     "POST /system/webext/enroll": { auth: "door", control: "never" },
     "GET /system/webext": { control: "never" },
     "DELETE /system/webext/{id}": { control: "never" },
     "GET /system/webext/connect": { auth: "door", beforeBoot: true, control: "never" },
-    "POST /mcp/webext/{id}": { auth: "door" },
-    "GET /mcp/webext/{id}": { auth: "door" },
-    "DELETE /mcp/webext/{id}": { auth: "door" },
     "POST /system/runners/pair": { control: "never" },
     "POST /system/runners/enroll": { auth: "door", control: "never" },
     "GET /system/runners": { control: "never" },
     "DELETE /system/runners/{id}": { control: "never" },
     "GET /system/runners/connect": { auth: "door", beforeBoot: true, 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" },
+    // Every MCP server the daemon hosts for a turn (its browser routers, the machines and browsers it was granted, its
+    // extension cards' endpoints), by server name: the handler checks the conversation's mount bearer the turn's tool
+    // config carries, and that the running turn mounted that name.
+    "ALL /mcp/{mount}": { 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" },

package/src/protocol/route-meta.ts

@@ -33,11 +33,46 @@ 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.
+    // A transfer: announced to the edge through the front (tunnel-bulk.ts), which sends it down the tunnel's bulk socket,
+    // 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 floor a route gets when it declares none: a read (GET, HEAD) floors at viewer, anything else (`ALL` included) at
+// maintainer, so a route nobody classified can under-serve, never over-grant.
+export const defaultFloor = (method: string): MemberRole => (method === "GET" || method === "HEAD" ? "viewer" : "maintainer");
+
+// The fields that say how a request travels, not who may send it; every other RouteMeta field decides reach.
+type TransportField = "lane" | "front";
+
+// Every field that decides who reaches a route, with its default resolved, so an absent field and a declared one read
+// alike and loosening either is a changed value: what contract.lock.json records per route (`access:METHOD /path`),
+// where the lock check and the push gate see it. Keyed by the interface: a RouteMeta field added above fails this
+// package's typecheck until it is read here or named a TransportField.
+const ACCESS = {
+    auth: (meta) => meta.auth ?? "session",
+    embedded: (meta) => meta.embedded === true,
+    beforeBoot: (meta) => meta.beforeBoot === true,
+    stream: (meta) => meta.stream === true,
+    floor: (meta, method) => meta.floor ?? defaultFloor(method),
+    guest: (meta) => meta.guest === true,
+    attachmentFloor: (meta) => meta.attachmentFloor ?? "none",
+    enrolment: (meta) => meta.enrolment === true,
+    agent: (meta) => meta.agent === true,
+    sync: (meta) => meta.sync ?? "none",
+    panel: (meta) => meta.panel !== false,
+    // `floor`: no reach of its own, the control rungs read the route's floor alone.
+    control: (meta) => meta.control ?? "floor",
+} as const satisfies { readonly [K in Exclude<keyof RouteMeta, TransportField>]-?: (meta: RouteMeta, method: string) => string | boolean };
+
+export type RouteAccess = { readonly [K in keyof typeof ACCESS]: ReturnType<(typeof ACCESS)[K]> };
+
+// One route's reach as its declaration states it, every default filled in.
+export const routeAccess = (method: string, meta: RouteMeta): RouteAccess =>
+    // SAFETY: every entry is one of ACCESS's own keys paired with what its reader returned, which RouteAccess spells.
+    Object.fromEntries(Object.entries(ACCESS).map(([field, read]) => [field, read(meta, method)])) as RouteAccess;
+
 // The builder every sandbox procedure starts from, so each carries a RouteMeta and whatever it leaves out defaults.
 export const procedure = oc.$meta<RouteMeta>({});

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

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { servedRoute } from "./routes.js";
+import { RAW_ROUTE_LIST } from "./raw-routes.js";
+import { hostOwnerId } from "./ingress-contract.js";
+import { tunnelBulkRoutes } from "./tunnel-bulk.js";
+
+// The shared fixture the edge reads too (the tunnel crate's bulk.rs): `bulk` is what the daemon announces, and every
+// case is the lane the daemon's own router gives the request, which the edge's reading of `bulk` must match.
+// SAFETY: the fixture is this repository's own file, and both tests below fail on a key it lacks.
+const FIXTURE = JSON.parse(readFileSync(new URL("./ingress-contract.fixture.json", import.meta.url), "utf8")) as {
+    readonly bulk: readonly string[];
+    readonly lanes: readonly { readonly host: string; readonly method: string; readonly path: string; readonly lane: "interactive" | "bulk" }[];
+};
+
+// A preview's dev server rides bulk; a daemon request rides its route's lane, the route found as the router finds it.
+const laneOf = (host: string, method: string, path: string): "interactive" | "bulk" => {
+    const id = hostOwnerId(host);
+    const label = host.split(":")[0]?.split(".")[0] ?? "";
+    if (id === undefined || label !== `sandbox-${id}`) {
+        return "bulk";
+    }
+    return servedRoute(RAW_ROUTE_LIST, [], method, path)?.meta.lane ?? "interactive";
+};
+
+test("the fixture's announcement is what the daemon announces today", () => {
+    expect(tunnelBulkRoutes()).toEqual([...FIXTURE.bulk]);
+    for (const route of tunnelBulkRoutes()) {
+        expect(route).toMatch(/^[A-Z]+ \/\S*$/);
+    }
+});
+
+test("every request the shared fixture names rides the lane the daemon's router gives it", () => {
+    expect(FIXTURE.lanes.length).toBeGreaterThan(20);
+    for (const { host, method, path, lane } of FIXTURE.lanes) {
+        expect({ host, method, path, lane: laneOf(host, method, path) }).toEqual({ host, method, path, lane });
+    }
+});

package/src/protocol/tunnel-bulk.ts

@@ -0,0 +1,7 @@
+import { RAW_ROUTE_LIST } from "./raw-routes.js";
+
+// What the daemon announces to the edge as its transfers (RouteMeta `lane`), handed to the front with the tunnel's door
+// and carried on each of its sockets' upgrades (the tunnel crate's `x-intentic-bulk`), so the edge sends a transfer
+// down the bulk socket and a keystroke never queues behind it on one TCP connection. The edge compiles in nothing of it.
+export const tunnelBulkRoutes = (): string[] =>
+    RAW_ROUTE_LIST.filter(({ meta }) => meta.lane === "bulk").map(({ method, path }) => `${method} ${path}`);

package/src/protocol/x402.test.ts

@@ -0,0 +1,29 @@
+import { atomicToUsd, USDC_NETWORKS, usdcNetworkOf, usdToAtomic } from "./x402.js";
+
+it("converts USD and atomic units without floats, in both directions", () => {
+    expect(usdToAtomic("1.00")).toBe(1_000_000n);
+    expect(usdToAtomic("0.1")).toBe(100_000n);
+    expect(usdToAtomic("0.000001")).toBe(1n);
+    // The classic float trap: 0.1 + 0.2 in binary floating point is not 0.3, and money must not care.
+    expect(usdToAtomic("0.1") + usdToAtomic("0.2")).toBe(usdToAtomic("0.3"));
+    expect(atomicToUsd(1_000_000n)).toBe("1.00");
+    expect(atomicToUsd(100_000n)).toBe("0.10");
+    expect(atomicToUsd(1n)).toBe("0.000001");
+});
+
+it("reads a bare whole or fraction, cuts past the sixth decimal, and writes zero as cents", () => {
+    expect(usdToAtomic("5")).toBe(5_000_000n);
+    expect(usdToAtomic(".5")).toBe(500_000n);
+    expect(usdToAtomic("0.0000019")).toBe(1n);
+    expect(atomicToUsd(0n)).toBe("0.00");
+    expect(atomicToUsd(12_345_670n)).toBe("12.34567");
+});
+
+it("knows USDC on Base and Base Sepolia by CAIP-2 id, and nothing else", () => {
+    expect(USDC_NETWORKS.map(({ network, chainId, asset }) => [network, chainId, asset])).toEqual([
+        ["eip155:8453", 8453, "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
+        ["eip155:84532", 84532, "0x036CbD53842c5426634e7929541eC2318f3dCF7e"],
+    ]);
+    expect(usdcNetworkOf("eip155:84532")?.v1Network).toBe("base-sepolia");
+    expect(usdcNetworkOf("base")).toBeUndefined();
+});

package/src/protocol/x402.ts

@@ -0,0 +1,61 @@
+// The money side of x402 every tier states alike: which USDC contracts a payment may move, and dollars as atomic units.
+
+// One chain's USDC: token contract, EIP-712 domain defaults, explorer; an asset not on the list below is refused.
+export interface UsdcNetwork {
+    // CAIP-2 ("eip155:8453"), the v2 vocabulary and the wallet config's.
+    readonly network: string;
+    // How v1 challenges spell the same chain ("base"), matched on parse, echoed on the v1 retry header.
+    readonly v1Network: string;
+    readonly chainId: number;
+    readonly asset: string;
+    // EIP-712 domain fallbacks; `extra.{name,version}` on the challenge wins when present.
+    readonly domainName: string;
+    readonly domainVersion: string;
+    readonly label: string;
+    readonly explorer: string;
+    readonly rpc: string;
+}
+
+export const USDC_NETWORKS: readonly UsdcNetwork[] = [
+    {
+        network: "eip155:8453",
+        v1Network: "base",
+        chainId: 8453,
+        asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+        domainName: "USD Coin",
+        domainVersion: "2",
+        label: "Base",
+        explorer: "https://basescan.org/tx/",
+        rpc: "https://mainnet.base.org",
+    },
+    {
+        network: "eip155:84532",
+        v1Network: "base-sepolia",
+        chainId: 84532,
+        asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+        domainName: "USDC",
+        domainVersion: "2",
+        label: "Base Sepolia (test)",
+        explorer: "https://sepolia.basescan.org/tx/",
+        rpc: "https://sepolia.base.org",
+    },
+];
+
+export const usdcNetworkOf = (network: string): UsdcNetwork | undefined => USDC_NETWORKS.find((entry) => entry.network === network);
+
+// Every amount is a bigint of atomic units, never a float; USD strings ("1.50") are the display and policy vocabulary.
+export const USDC_DECIMALS = 6n;
+const ATOMIC_PER_USD = 10n ** USDC_DECIMALS;
+
+// Digits past the sixth decimal are cut, not rounded: a price is never read as more than was written.
+export const usdToAtomic = (usd: string): bigint => {
+    const [whole, fraction = ""] = usd.split(".");
+    return BigInt(whole || "0") * ATOMIC_PER_USD + BigInt(fraction.padEnd(6, "0").slice(0, 6) || "0");
+};
+
+// At least cents ("1.50"), and every non-zero atomic digit after them ("0.000001").
+export const atomicToUsd = (atomic: bigint): string => {
+    const whole = atomic / ATOMIC_PER_USD;
+    const fraction = (atomic % ATOMIC_PER_USD).toString().padStart(6, "0").replace(/0+$/, "");
+    return fraction === "" ? `${whole}.00` : `${whole}.${fraction.padEnd(2, "0")}`;
+};