@intentic/sandbox-contract 1.312.0 → 1.314.0

package/src/front/generated/tunnel.json

@@ -0,0 +1,38 @@
+{
+  "close": {
+    "away": 1001,
+    "displaced": 4001,
+    "refused": 4003
+  },
+  "headers": {
+    "bulk": "x-intentic-bulk",
+    "grant": "x-intentic-grant",
+    "lane": "x-intentic-lane",
+    "transports": "x-intentic-transports"
+  },
+  "lanes": [
+    "interactive",
+    "bulk"
+  ],
+  "liveness": {
+    "deadAfterMs": 45000,
+    "pingEveryMs": 15000
+  },
+  "mux": "yamux",
+  "path": "/tunnel/v2",
+  "quic": {
+    "alpn": "intentic-tunnel/1",
+    "hello": {
+      "gone": 2,
+      "held": 0,
+      "refused": 1
+    },
+    "yieldAfterBytes": 1048576
+  },
+  "transports": [
+    "quic",
+    "h3",
+    "webtransport"
+  ],
+  "upgrade": "websocket"
+}

package/src/front/generated/wire.ts

@@ -16,7 +16,9 @@ export type Endpoint = { host: string, port: number, };
 /**
  * Everything Node sends the front.
  */
-export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kind": "listen", config: ListenConfig, } | { "kind": "certificate", certificate?: Certificate, } | { "kind": "tunnel", tunnel?: TunnelConfig, } | { "kind": "answer", id: number, answer: Answer, } | { "kind": "refused", id: number, message: string, } | { "kind": "revoke", member?: string, } | { "kind": "watch", checkout: WatchedCheckout, } | { "kind": "unwatch", dir: string, } | { "kind": "sync", id: number, dirs: Array<string>, };
+export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kind": "listen", config: ListenConfig, } | { "kind": "certificate", certificate?: Certificate, } | { "kind": "tunnel", tunnel?: TunnelConfig, } | { "kind": "ask", id: number, question: FrontQuestion, } | { "kind": "answer", id: number, answer: Answer, } | { "kind": "refused", id: number, message: string, } | { "kind": "revoke", member?: string, } | { "kind": "watch", checkout: WatchedCheckout, } | { "kind": "unwatch", dir: string, };
+
+export type FrontAnswer = { "answer": "sync", generations: Array<number | null>, };
 
 /**
  * Request headers only the front sets on what it forwards to Node; it strips them from everything arriving outside.
@@ -24,6 +26,11 @@ export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kin
  */
 export type FrontHeader = "x-intentic-preview" | "x-intentic-preview-unreachable";
 
+/**
+ * A question Node asks the front.
+ */
+export type FrontQuestion = { "question": "sync", dirs: Array<string>, };
+
 /**
  * Every port the front binds, as Node's config names them; an absent one is not bound.
  */
@@ -42,47 +49,37 @@ frameAncestors: Array<string>,
 previewProbePath: string, };
 
 /**
- * Where a preview host's requests go, as Node resolved it.
- */
-export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "node" };
-
-/**
- * A question the front asks Node; the answer carries the same id.
+ * An answer Node renders whole when asked, for the front to write as it stands: a refusal page, or the probe's report.
  */
-export type Question = { "question": "preview", host: string, } | { "question": "terminal", query: string, };
-
-export type Scheme = "http" | "https";
+export type Page = { status: number, headers: { [key in string]: string }, body: string, };
 
 /**
- * What the browser sends on a terminal socket, each a JSON text frame.
+ * What becomes of a preview host's request, decided by Node once, when asked.
  */
-export type TerminalClientMessage = { "type": "input", data: string, } | { "type": "resize", cols: number, rows: number, } | { "type": "ping" };
+export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "page", page: Page, } | { "to": "outbox" };
 
 /**
- * What a terminal socket opens onto, as Node decided from its ticket, session name and working directory.
+ * A question the front asks Node.
  */
-export type TerminalPlan = { "plan": "tmux", session: string, argv: Array<string>, } | { "plan": "tail", path: string, } | { "plan": "exit", code: number, reason: string, } | { "plan": "refused", code: number, reason: string, };
+export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, };
 
-/**
- * What a terminal socket sends as JSON text; the pane's own bytes travel as binary frames.
- */
-export type TerminalServerMessage = { "type": "exit", code: number, reason?: string, } | { "type": "pong" };
+export type Scheme = "http" | "https";
 
 /**
- * The Upgrade a terminal opens with where no WebSocket rides the stream, a WebTransport one: its messages then travel
- * as frames (`FrameKind`). Exported as a literal type, as `FrontHeader` is.
+ * What a terminal socket opens onto, as Node decided from its ticket, session name and working directory.
  */
-export type TerminalUpgrade = "intentic-terminal";
+export type TerminalPlan = { "plan": "session", name: string, createIn?: string, } | { "plan": "tail", path: string, } | { "plan": "exit", code: number, reason: string, } | { "plan": "refused", code: number, reason: string, };
 
 /**
  * Everything the front sends Node.
  */
-export type ToNode = { "kind": "ask", id: number, question: Question, } | { "kind": "tunnel", connected: boolean, } | { "kind": "synced", id: number, generations: Array<number | null>, };
+export type ToNode = { "kind": "ask", id: number, question: Question, } | { "kind": "answer", id: number, answer: FrontAnswer, } | { "kind": "refused", id: number, message: string, } | { "kind": "tunnel", connected: boolean, };
 
 /**
- * The ingress tunnel's door and the reachability grant it presents there.
+ * The ingress tunnel's door, the reachability grant it presents there, and the daemon's transfer routes it announces
+ * (`METHOD /path` each, as the daemon names them), which the edge sends down the bulk socket.
  */
-export type TunnelConfig = { url: string, grant: string, };
+export type TunnelConfig = { url: string, grant: string, bulk: Array<string>, };
 
 /**
  * A local upstream a preview host relays to.

package/src/front/wire-manifests.test.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import { EDGE_VERDICT_HEADER, edgeVerdictOf } from "../protocol/edge-verdict.js";
+import { INGRESS_GRANT_HEADER, INGRESS_TUNNEL_PATH } from "../protocol/ingress-contract.js";
+import { EDGE_TRANSPORTS, TERMINAL_PATH, WEBTRANSPORT_PATH } from "./browser-wire.js";
+import { ASK_PATIENCE_MS, FRAME_LENGTH_BYTES, FRONT_SOCKET_ENV, NODE_SOCKET_ENV } from "./front-wire.js";
+
+// The manifests `cargo test` writes from the Rust crates that define this wire: every value TypeScript restates is read
+// back against them, so the two languages cannot drift and contract.lock.json pins what both agree on.
+const manifest = (name: string): Record<string, unknown> =>
+    JSON.parse(readFileSync(new URL(`./generated/${name}.json`, import.meta.url), "utf8")) as Record<string, unknown>;
+
+const tunnel = manifest("tunnel") as {
+    path: string;
+    headers: { grant: string; transports: string };
+    transports: string[];
+};
+// SAFETY: front-wire's own test writes this manifest with exactly these keys, and the lock pins them.
+const socket = manifest("front-wire") as {
+    env: { frontSocket: string; nodeSocket: string };
+    askPatienceMs: number;
+    frame: { lengthBytes: number };
+};
+const browser = manifest("browser-wire") as {
+    edge: { verdictHeader: string; verdicts: { oneOf: { const: string }[] } };
+    terminal: { path: string; upgrade: string };
+    webTransport: { path: string };
+};
+
+describe("the wire outside oRPC, as the Rust crates define it", () => {
+    it("names the tunnel door and its headers as the tunnel crate does", () => {
+        expect({ path: INGRESS_TUNNEL_PATH, grant: INGRESS_GRANT_HEADER }).toEqual({
+            path: tunnel.path,
+            grant: tunnel.headers.grant,
+        });
+    });
+
+    it("names the control socket's env vars, its patience and its framing as front-wire does", () => {
+        expect({ front: FRONT_SOCKET_ENV, node: NODE_SOCKET_ENV, patience: ASK_PATIENCE_MS, length: FRAME_LENGTH_BYTES }).toEqual({
+            front: socket.env.frontSocket,
+            node: socket.env.nodeSocket,
+            patience: socket.askPatienceMs,
+            length: socket.frame.lengthBytes,
+        });
+    });
+
+    it("declares exactly the transports an edge may", () => {
+        expect<readonly string[]>(EDGE_TRANSPORTS).toEqual(tunnel.transports);
+    });
+
+    it("reads the edge's verdicts and the browser's paths as browser-wire writes them", () => {
+        const verdicts = browser.edge.verdicts.oneOf.map((verdict) => verdict.const);
+        expect(verdicts).toEqual(["no-tunnel", "unknown-sandbox", "dropped"]);
+        expect<readonly (string | undefined)[]>(verdicts.map((verdict) => edgeVerdictOf(verdict))).toEqual(verdicts);
+        expect({ header: EDGE_VERDICT_HEADER, terminal: TERMINAL_PATH, session: WEBTRANSPORT_PATH, upgrade: "websocket" }).toEqual({
+            header: browser.edge.verdictHeader,
+            terminal: browser.terminal.path,
+            session: browser.webTransport.path,
+            upgrade: browser.terminal.upgrade,
+        });
+    });
+});

package/src/ids/conversation-ids.ts

@@ -160,15 +160,16 @@ const repoSlug = (repo: string): string =>
         .replace(/^-+|-+$/g, "") || "repo";
 export const ciFixConversationId = (repo: string, runId: number): string => `${CI_FIX_PREFIX}${repoSlug(repo)}-${runId}`;
 
-// Keyed by which gates failed (fixSignature), not a run id (a push has none); the same gates red again is the same
-// failure. Hashed rather than spelled into the branch name; the fix agent's first message names the gates.
+// Keyed by when the project's push red began (pushFixBase, `red:<since>`), not a run id (a push has none): a refused push
+// is owed by that red too (push-checks-store.ts). Hashed rather than spelled into the branch name; the fix agent's first
+// message names what it is for.
 export const PUSH_FIX_PREFIX = "push-fix-";
 
 // FNV-1a, not a cryptographic hash: nothing here is secret, the only requirement is the same failure yields the same
-// seven characters in every browser and in node.
+// seven characters in every browser and in node. The one spelling: a push finding's id (push-checks-store.ts) is this too.
 const FNV_OFFSET = 0x811c_9dc5;
 const FNV_PRIME = 0x0100_0193;
-const digest = (text: string): string => {
+export const fnvDigest = (text: string): string => {
     let hash = FNV_OFFSET;
     for (let index = 0; index < text.length; index += 1) {
         hash = Math.imul(hash ^ text.charCodeAt(index), FNV_PRIME);
@@ -176,7 +177,7 @@ const digest = (text: string): string => {
     return (hash >>> 0).toString(36).padStart(7, "0");
 };
 
-export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${digest(signature)}`;
+export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${fnvDigest(signature)}`;
 
 // A red main-line check that no conversation still holding the work could take: keyed by the project and the moment its
 // red streak began, so every attempt at one streak shares a base and a later streak in the same project starts over.

package/src/ids/session-names.ts

@@ -6,6 +6,8 @@ export const WEB_SESSION_PREFIX = "web-";
 export const AGENT_SESSION_PREFIX = "agent-";
 export const JOB_SESSION_PREFIX = "job-";
 export const BROWSER_SESSION_PREFIX = "browser-";
+// A panel's session, one per managed process; the browser string-builds these names too, so never rename it.
+export const PANEL_SESSION_PREFIX = "panel-";
 
 // Eight characters of the SDK session UUID, sanitized to the name-guard charset; groups a turn's work, including its
 // subagents', under one name. Undefined when it sanitizes to empty.
@@ -21,6 +23,11 @@ export const agentSessionName = (sessionId: string): string | undefined => {
     return suffix === undefined ? undefined : `${AGENT_SESSION_PREFIX}${suffix}`;
 };
 
+// The session a panel keyed `key` runs in, and back; undefined for a name that isn't a panel session at all.
+export const panelSession = (key: string): string => `${PANEL_SESSION_PREFIX}${key}`;
+export const panelKeyOf = (session: string | undefined): string | undefined =>
+    session?.startsWith(PANEL_SESSION_PREFIX) === true ? session.slice(PANEL_SESSION_PREFIX.length) : undefined;
+
 // The browser session one SDK session drives. Shares the suffix with agentSessionName on purpose: a conversation's
 // shell and its browser read as the pair they are.
 export const browserSessionName = (sessionId: string): string | undefined => {

package/src/index.ts

@@ -114,14 +114,17 @@ export * from "./events/transcript.js";
 export * from "./events/land-breakage.js";
 export * from "./events/land-conflict.js";
 export * from "./events/verify-nudge.js";
+export * from "./events/errands.js";
 export * from "./events/watch-wake.js";
 export * from "./policy/request-status.js";
+export * from "./events/child-run.js";
 export * from "./policy/turned-away.js";
 export * from "./text/mentions.js";
 export * from "./protocol/sse.js";
 export * from "./protocol/routes.js";
-export type { ControlReach, RouteMeta } from "./protocol/route-meta.js";
+export { type ControlReach, defaultFloor, type RouteAccess, type RouteMeta, routeAccess } from "./protocol/route-meta.js";
 export { RAW_ROUTE_LIST, RAW_ROUTES, type RawRouteKey, rawRoutePath } from "./protocol/raw-routes.js";
+export { tunnelBulkRoutes } from "./protocol/tunnel-bulk.js";
 export type { SandboxCallInput, SandboxGroup, SandboxHandlerInput, SandboxHandlerOutput, SandboxProcedure } from "./protocol/procedure-types.js";
 export * from "./policy/control-scopes.js";
 // The container's directory layout, re-exported since extensions can't import @intentic/constants directly.
@@ -133,6 +136,7 @@ export * from "./state/history-state.js";
 export * from "./state/fix-stance.js";
 export * from "./state/landed-commit.js";
 export * from "./state/fix-attempt-plan.js";
+export * from "./state/red-streak.js";
 // Provider vocabulary bottom-up: agent-runtimes, provider-specs, agent-catalog; three modules since the dependency
 // points one way.
 export * from "./models/agent-runtimes.js";
@@ -173,6 +177,7 @@ export * from "./schemas/areas.js";
 export * from "./policy/fence-paths.js";
 export * from "./policy/persona-home.js";
 export * from "./schemas/agents.js";
+export * from "./schemas/speaker.js";
 export * from "./schemas/approvals.js";
 export * from "./schemas/automations.js";
 export * from "./schemas/capabilities.js";
@@ -218,6 +223,7 @@ export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
+export * from "./schemas/state-plan.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
 export * from "./schemas/keep-warm.js";
@@ -238,6 +244,7 @@ export * from "./state/starter.js";
 export * from "./text/title.js";
 export * from "./state/versions.js";
 export * from "./text/model-answer.js";
+export * from "./text/shell-regions.js";
 export * from "./text/whisper.js";
 export * from "./text/workflow-faults.js";
 export * from "./text/emoji.js";

package/src/models/agent-catalog.test.ts

@@ -31,7 +31,7 @@ describe("every provider/harness pair declares what it can do", () => {
 
         expect(["claude-code", "codex", "cursor", "opencode", "opencode-gemini", "acp", "pi"]).toContain(capabilities.runtime);
         expect(["modes", "plan"]).toContain(capabilities.permissions);
-        expect(["full", "tools", "browser", "http", "none"]).toContain(capabilities.mcp);
+        expect(["full", "tools", "http", "none"]).toContain(capabilities.mcp);
         expect(capabilities.execution).toContain("shell");
         for (const backend of capabilities.execution) {
             expect(["shell", "js"]).toContain(backend);
@@ -135,8 +135,8 @@ test("the ceiling has nothing to disclose; a floor names what it lacks", () => {
     expect(acpCaps.terminals).toBe(true);
 
     const codexCaps = capabilitiesOf("codex", "native");
-    expect(codexCaps.mcp).toBe("browser");
-    expect(limitationsOf(codexCaps).some((line) => line.includes("browser"))).toBe(true);
+    expect(codexCaps.mcp).toBe("http");
+    expect(limitationsOf(codexCaps)).toContain("MCP servers only, none of the daemon's own tools, no plugins");
     expect(limitationsOf(codexCaps).length).toBeLessThan(limitationsOf({ ...grokCaps, mcp: "none" }).length + 5);
 });
 
@@ -154,13 +154,15 @@ test("every axis a record can lack has words for it", () => {
         commands: false,
         terminals: false,
         recovery: false,
+        warm: false,
         instructions: "none",
         skillDiscovery: "prompt",
         rulebook: "none",
         secrets: "none",
     };
 
-    // Thirteen disclosable axes, thirteen sentences; `fastMode` is the exception, disclosed via fastAllowed.
+    // Thirteen disclosable axes, thirteen sentences; `fastMode` is disclosed via fastAllowed, and `warm` (keep-warm, off by
+    // default) is no limit on the turn itself.
     expect(limitationsOf(nothing)).toHaveLength(13);
     expect(limitationsOf(nothing).join(" ")).not.toContain("fast");
 });

package/src/models/agent-catalog.ts

@@ -116,12 +116,10 @@ export const limitationsOf = (capabilities: AgentCapabilities): string[] => [
     ...(capabilities.mcp === "none"
         ? ["no MCP tools or plugins"]
         : capabilities.mcp === "http"
-          ? ["MCP tools only, no plugins or browser"]
-          : capabilities.mcp === "browser"
-            ? ["browser tools only, no other MCP"]
-            : capabilities.mcp === "tools"
-              ? ["no plugins"]
-              : []),
+          ? ["MCP servers only, none of the daemon's own tools, no plugins"]
+          : capabilities.mcp === "tools"
+            ? ["no plugins"]
+            : []),
     ...(capabilities.execution.includes("js") ? [] : ["no code runs, shell only"]),
     ...(capabilities.effort ? [] : ["no effort control"]),
     ...(capabilities.commands ? [] : ["no slash commands"]),

package/src/models/agent-runtimes.ts

@@ -15,8 +15,13 @@ export interface AgentCapabilities {
     readonly permissions: "modes" | "plan";
     // Can stop mid-turn and ask the user a multiple-choice question (`question` frames).
     readonly questions: boolean;
-    // Which tools reach the agent, full down to none; never rounded up or down from what a runtime has.
-    readonly mcp: "full" | "tools" | "browser" | "http" | "none";
+    // Which tools reach the agent, full down to none; never rounded up or down from what a runtime has. Every runtime
+    // but `none` takes the turn's whole remote list (TurnTools.remote: the daemon's MCP door's mounts, browsers
+    // included, and the mcp-kind cards), so no granted server reaches one runtime and misses another:
+    // full - that list, the daemon's own in-process servers (ui, secrets, watch, …), and plugin checkouts.
+    // tools - that list, and the daemon's own tools through the runtime's host callbacks; no plugins.
+    // http - that list alone, as http MCP servers.
+    readonly mcp: "full" | "tools" | "http" | "none";
     // Which ways of executing the daemon stands behind here; distinct from `mcp`, which names tools, not execution.
     readonly execution: readonly ExecutionBackend[];
     // Reasoning-effort selection is forwarded to the model.
@@ -31,6 +36,9 @@ export interface AgentCapabilities {
     readonly terminals: boolean;
     // Fails with the coded frames auto-resume keys off, so a turn the provider killed is re-run once it's back.
     readonly recovery: boolean;
+    // Can hold an idle conversation's prompt cache warm: its provider replays the last turn's prefix as one forked,
+    // unsaved request with every tool refused (keep-warm). Only where the provider module also implements `warm`.
+    readonly warm: boolean;
     // How much of the owner's instructions this runtime takes: replace the base, append to it, or no seam at all.
     readonly instructions: "replace" | "append" | "none";
     // How the runtime discovers loaded skills: scans its own filesystem, or the daemon names them in the opener.
@@ -61,6 +69,7 @@ export const CLAUDE_CODE: AgentCapabilities = {
     commands: true,
     terminals: true,
     recovery: true,
+    warm: true,
     instructions: "replace",
     skillDiscovery: "native",
     // The only runtime with its own pre-execution hook, so the only one where a hold can park instead of refusing.
@@ -68,14 +77,15 @@ export const CLAUDE_CODE: AgentCapabilities = {
     secrets: "masked",
 };
 
-// Codex app-server: item-level events, process-backed MCP, and four seams (steer, a question request, the skills list,
-// the shared mount namespace). Daemon-side servers, plugins, server approvals stay unwired.
+// Codex app-server: item-level events, the turn's remote MCP servers over http, and four seams (steer, a question
+// request, the skills list, the shared mount namespace). The daemon's in-process servers, plugins and server approvals
+// stay unwired.
 export const CODEX: AgentCapabilities = {
     runtime: "codex",
     steering: true,
     permissions: "plan",
     questions: true,
-    mcp: "browser",
+    mcp: "http",
     execution: ["shell"],
     effort: true,
     fastMode: false,
@@ -83,6 +93,7 @@ export const CODEX: AgentCapabilities = {
     commands: true,
     terminals: false,
     recovery: false,
+    warm: false,
     // Both ride the per-thread config: one replaces Codex's base prompt, the other adds a developer message.
     instructions: "replace",
     skillDiscovery: "native",
@@ -106,6 +117,7 @@ export const OPENCODE: AgentCapabilities = {
     commands: false,
     terminals: false,
     recovery: false,
+    warm: false,
     // `system` on the prompt body, per message; adds to OpenCode's own prompt, with no seam to replace it.
     instructions: "append",
     skillDiscovery: "prompt",
@@ -122,7 +134,7 @@ export const OPENCODE_GEMINI: AgentCapabilities = {
 };
 
 // Any agent speaking the Agent Client Protocol: a documented floor, not the native ceiling. Publishes commands and
-// terminals, takes http MCP tools when offered, but owns its own model, effort and permission posture.
+// terminals, takes the turn's remote MCP servers when it advertises http MCP, but owns its own model, effort and permission posture.
 export const ACP: AgentCapabilities = {
     runtime: "acp",
     steering: false,
@@ -136,6 +148,7 @@ export const ACP: AgentCapabilities = {
     commands: true,
     terminals: true,
     recovery: false,
+    warm: false,
     // ACP's calls carry no system field: the agent owns its instructions, the persona note rides the message.
     instructions: "none",
     skillDiscovery: "prompt",
@@ -159,6 +172,7 @@ export const PI: AgentCapabilities = {
     commands: true,
     terminals: false,
     recovery: false,
+    warm: false,
     // Pi's RPC sets no standing instructions; like ACP, it hears the persona note through the user message.
     instructions: "none",
     skillDiscovery: "prompt",
@@ -177,7 +191,7 @@ export const CURSOR: AgentCapabilities = {
     permissions: "plan",
     // True since the daemon supplies its own ask tool; Cursor's own can fabricate an answer, so it's disallowed.
     questions: true,
-    // stdio + http/sse MCP servers plus host callbacks; everything but a Claude Code plugin checkout.
+    // The turn's remote MCP servers plus host callbacks; everything but a Claude Code plugin checkout.
     mcp: "tools",
     // The JS backend rides Cursor's custom-tool seam rather than an MCP server, and consults the rulebook in its
     // handler, since the hook file only covers the shell.
@@ -193,6 +207,7 @@ export const CURSOR: AgentCapabilities = {
     terminals: false,
     // The SDK throws typed errors instead of dissolving a refusal into prose, so the adapter files coded frames.
     recovery: true,
+    warm: false,
     // append, reached differently: `beforeSubmitPrompt`'s reply folds the daemon's text onto Cursor's base. The SDK can
     // replace that base outright, but only for an entitled account, so the seam every turn can reach is this one.
     instructions: "append",

package/src/models/capability-ledger.test.ts

@@ -32,6 +32,8 @@ const LEDGER: Record<keyof AgentCapabilities, Backing> = {
     // - refuse-only: a hold refuses instead of parking
     // - other values: park on a card
     rulebook: "enforced",
+    // agent/run/turn/cache-keepwarm.ts files nothing to keep warm for a turn whose runtime lacks it.
+    warm: "enforced",
 
     // Descriptive: true of the runtime but nothing consults these; wiring one up moves it to enforced.
     questions: "descriptive",

package/src/models/plan-pools.test.ts

@@ -1,5 +1,18 @@
-import { bindingWindow, gatesModel, gatingWindows, scopedWindow, windowLive, windowPeriod } from "./plan-pools.js";
-import type { AccountUsage, UsageWindow } from "../schemas/providers/plan-limits.js";
+import {
+    bindingWindow,
+    gatesModel,
+    gatingWindows,
+    headroomState,
+    preferredAccount,
+    refusalVerdict,
+    roomiestAccount,
+    scopedWindow,
+    serviceState,
+    serviceStates,
+    windowLive,
+    windowPeriod,
+} from "./plan-pools.js";
+import type { AccountState, AccountUsage, ProviderRefusal, UsageWindow } from "../schemas/providers/plan-limits.js";
 
 // One rule for which pool blocks a given model, shared by the daemon and the browser: a plan can meter models
 // separately, so the account's fullest pool need not be the model's own.
@@ -102,3 +115,109 @@ test("a reading is live until its reset, or, with none published, for one window
     // And a pool whose length nothing names has only its reset instant; without one it stands.
     expect(windowLive(window({ kind: "claude:tangelo" }), NOW - 400 * HOUR, NOW)).toBe(true);
 });
+
+// Serviceability: the one verdict on whether an account can serve a turn.
+
+const at = (measuredAt: number, ...windows: UsageWindow[]): AccountUsage => ({ windows, measuredAt });
+const refusal = (over: Partial<ProviderRefusal> & Pick<ProviderRefusal, "kind">): ProviderRefusal => ({ at: 1_000, message: "no.", ...over });
+
+test("spent is the contract's one line: 99.5% still has room, 100% is spent until its last full pool reopens", () => {
+    expect(headroomState(usage(window({ kind: "five_hour", utilization: 99.5 })))).toEqual({ kind: "ready", room: 0.5 });
+    expect(
+        headroomState(usage(window({ kind: "five_hour", utilization: 100, resetsAt: 50 }), window({ kind: "seven_day", utilization: 100, resetsAt: 900 }))),
+    ).toEqual({ kind: "spent", reopensAt: 900 });
+    expect(headroomState(usage(window({ kind: "five_hour", utilization: 100 })))).toEqual({ kind: "spent" });
+    expect(headroomState(undefined)).toEqual({ kind: "unknown" });
+    expect(headroomState(CLAUDE, { id: "claude-haiku-4-5" })).toEqual({ kind: "ready", room: 70 });
+    expect(headroomState(CLAUDE, { id: "claude-opus-4-6" })).toEqual({ kind: "spent" });
+});
+
+test("with no model named, an account is spent only when no model can run on it", () => {
+    // A full Opus slice leaves every other model the room of the fullest pool still open.
+    expect(headroomState(CLAUDE)).toEqual({ kind: "ready", room: 70 });
+    expect(headroomState(GOOGLE)).toEqual({ kind: "ready", room: 73 });
+    // A pool gating every model, full: nothing runs, and it reopens with that pool.
+    expect(headroomState(usage(window({ kind: "seven_day", utilization: 100, resetsAt: 900 }), window({ kind: "model:Opus", utilization: 10, gates: { models: ["Opus"] } })))).toEqual({
+        kind: "spent",
+        reopensAt: 900,
+    });
+    // Every slice full: the first to reopen lets some model run again.
+    expect(
+        headroomState(
+            usage(
+                window({ kind: "g", utilization: 100, resetsAt: 500, gates: { models: ["gemini"] } }),
+                window({ kind: "c", utilization: 100, resetsAt: 800, gates: { models: ["claude"] } }),
+            ),
+        ),
+    ).toEqual({ kind: "spent", reopensAt: 500 });
+});
+
+test("a revoked sign-in outranks a lost seat, which outranks a bench, whatever the meters say", () => {
+    const facts = { account: "a", usage: usage(window({ kind: "five_hour", utilization: 0 })) };
+    expect(serviceState({ ...facts, needsReauth: true, seatRefusal: "no seat" })).toEqual({ kind: "blocked", fix: "reconnect", reason: "sign-in expired" });
+    expect(serviceState({ ...facts, seatRefusal: "Your org disabled Claude Code." })).toEqual({
+        kind: "blocked",
+        fix: "admin",
+        reason: "Your org disabled Claude Code.",
+    });
+    expect(serviceState({ ...facts, cooling: { reason: "no project" } })).toEqual({ kind: "blocked", fix: "reconnect", reason: "no project" });
+    expect(serviceState({ ...facts, cooling: { until: 2_000 } }, undefined, undefined, 1_000_000)).toEqual({
+        kind: "blocked",
+        fix: "wait",
+        reason: "cooling down",
+        until: 2_000,
+    });
+    // A bench whose instant has passed is over.
+    expect(serviceState({ ...facts, cooling: { until: 999 } }, undefined, undefined, 1_000_000)).toEqual({ kind: "ready", room: 100 });
+});
+
+test("a standing refusal blocks by its kind, and a limit refusal pins only the pool its model spends", () => {
+    const facts = { account: "a", usage: CLAUDE };
+    expect(serviceState(facts, refusal({ kind: "auth" }))).toEqual({ kind: "blocked", fix: "reconnect", reason: "no." });
+    expect(serviceState(facts, refusal({ kind: "entitlement" }))).toEqual({ kind: "blocked", fix: "admin", reason: "no." });
+    // Refused on Haiku: the 5-hour/weekly binding pool (seven_day, 30%) reads full, so Haiku is spent too.
+    expect(serviceState(facts, refusal({ kind: "limit", model: "claude-haiku-4-5" }), { id: "claude-haiku-4-5" })).toEqual({ kind: "spent" });
+    // Refused on Opus: its own slice was already full; Haiku keeps the room its pools show.
+    expect(serviceState(facts, refusal({ kind: "limit", model: "claude-opus-4-6" }), { id: "claude-haiku-4-5" })).toEqual({ kind: "ready", room: 70 });
+    // No reading at all: the refusal is the evidence, unless it was about another model.
+    expect(serviceState({ account: "a" }, refusal({ kind: "limit" }))).toEqual({ kind: "spent" });
+    expect(serviceState({ account: "a" }, refusal({ kind: "limit", model: "opus" }), { id: "haiku" })).toEqual({ kind: "unknown" });
+});
+
+test("a refusal stands until a later reading contradicts it, and never past its account's disconnection", () => {
+    const room = at(2_000, window({ kind: "five_hour", utilization: 40 }));
+    const full = at(2_000, window({ kind: "five_hour", utilization: 100 }));
+    const before = at(500, window({ kind: "five_hour", utilization: 40 }));
+    expect(refusalVerdict(refusal({ kind: "limit", account: "a" }), [{ account: "a", usage: room }])).toBe("answered");
+    expect(refusalVerdict(refusal({ kind: "limit", account: "a" }), [{ account: "a", usage: full }])).toBe("standing");
+    expect(refusalVerdict(refusal({ kind: "limit", account: "a" }), [{ account: "a", usage: before }])).toBe("standing");
+    // Another account's room proves nothing about the one refused.
+    expect(refusalVerdict(refusal({ kind: "limit", account: "a" }), [{ account: "a", usage: before }, { account: "b", usage: room }])).toBe("standing");
+    // A refusal naming no account is answered by any of them.
+    expect(refusalVerdict(refusal({ kind: "limit" }), [{ account: "a", usage: before }, { account: "b", usage: room }])).toBe("answered");
+    expect(refusalVerdict(refusal({ kind: "auth", account: "a" }), [{ account: "a", usage: full }])).toBe("answered");
+    expect(refusalVerdict(refusal({ kind: "auth", account: "a" }), [{ account: "a", usage: full, needsReauth: true }])).toBe("standing");
+    expect(refusalVerdict(refusal({ kind: "entitlement", account: "a" }), [{ account: "a", usage: room }])).toBe("standing");
+    expect(refusalVerdict(refusal({ kind: "limit", account: "gone" }), [{ account: "a", usage: room }])).toBe("gone");
+    expect(refusalVerdict(refusal({ kind: "limit", account: "a" }), [])).toBe("standing");
+});
+
+test("a provider's accounts are judged together: a standing refusal lands only on the account it names", () => {
+    const room = at(500, window({ kind: "five_hour", utilization: 40 }));
+    const states = serviceStates([{ account: "a", usage: room }, { account: "b", usage: room }], refusal({ kind: "entitlement", account: "a" }));
+    expect(Object.fromEntries(states)).toEqual({ a: { kind: "blocked", fix: "admin", reason: "no." }, b: { kind: "ready", room: 60 } });
+    const answered = serviceStates([{ account: "a", usage: at(2_000, window({ kind: "five_hour", utilization: 40 })) }], refusal({ kind: "limit", account: "a" }));
+    expect(answered.get("a")).toEqual({ kind: "ready", room: 60 });
+});
+
+test("an unnamed turn takes the most room, then an unmeasured account, then a spent one, and a blocked one only when that is all", () => {
+    const entry = (id: string, state: AccountState) => ({ id, state });
+    const blocked: AccountState = { kind: "blocked", fix: "admin", reason: "no seat" };
+    expect(preferredAccount([entry("seatless", blocked), entry("spent", { kind: "spent" }), entry("low", { kind: "ready", room: 5 }), entry("high", { kind: "ready", room: 60 })])?.id).toBe("high");
+    expect(preferredAccount([entry("seatless", blocked), entry("spent", { kind: "spent" }), entry("unread", { kind: "unknown" })])?.id).toBe("unread");
+    expect(preferredAccount([entry("seatless", blocked), entry("spent", { kind: "spent" })])?.id).toBe("spent");
+    expect(preferredAccount([entry("seatless", blocked), entry("other", blocked)])?.id).toBe("seatless");
+    expect(preferredAccount([entry("first", { kind: "ready", room: 60 }), entry("second", { kind: "ready", room: 60 })])?.id).toBe("first");
+    expect(roomiestAccount([entry("seatless", blocked), entry("unread", { kind: "unknown" })])).toBeUndefined();
+    expect(roomiestAccount([entry("low", { kind: "ready", room: 5 }), entry("high", { kind: "ready", room: 60 })])?.id).toBe("high");
+});