@intentic/sandbox-contract 1.311.0 → 1.312.0

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(

package/src/schemas/agents.ts

@@ -83,10 +83,30 @@ export const UnfinishedWorkSchema = z.object({
         })
         .optional()
         .describe("The agent's own checklist where that turn left it. Absent for a conversation that kept no list."),
-    // Name of the `turn.ending` check still red when the turn ended, after its two repair rounds ran out.
-    check: z.string().optional().describe("The end-of-turn check that was still failing when the turn ended, by name."),
+    // Name of the `turn.ending` check still red when the turn ended. Retired with that check: nothing writes it now, and
+    // it stays so entries written before still read.
+    check: z
+        .string()
+        .optional()
+        .describe("The end-of-turn check that was still failing when the turn ended, by name. No longer written: checks run after work lands."),
 });
 export type UnfinishedWork = z.infer<typeof UnfinishedWorkSchema>;
+// What the last turn showed of its own work, read off its tool calls and never asked of the model: the record a card
+// badges instead of sending the turn back to prove anything. Checks run after the work lands (mainline.ts).
+export const TurnProofSchema = z.object({
+    at: z.number().describe("When the turn that left this ended, in milliseconds."),
+    verification: z
+        .enum(["verified", "unproven", "failing", "no-code"])
+        .describe(
+            "Verified: a check it ran passed after its last edit to code. Failing: the last one it ran failed. Unproven: it changed code and ran nothing that checked it. No-code: it changed nothing a check could speak to.",
+        ),
+    check: z.string().optional().describe("The command that spoke, when one did, so a targeted test is never read as the whole suite."),
+    unviewed: z
+        .number()
+        .optional()
+        .describe("How many rendered files it changed (pages, components, styles) without looking at the result afterwards. Absent when none."),
+});
+export type TurnProof = z.infer<typeof TurnProofSchema>;
 // A landing's commit message: subject plus the two trailer sentences a changelog repo gets. One schema, not three
 // duplicated fields, since both the live roster and the review carrier must read the same shape and can't disagree.
 export const LandedMessageSchema = z.object({
@@ -396,7 +416,11 @@ export const AgentSummarySchema = z.object({
     // Beside `attention` since a reader asks both at a glance, but opposite in shape: a turn gone, not one still parked
     // and waiting.
     unfinished: UnfinishedWorkSchema.optional().describe(
-        "What its last turn left open: steps it never completed, a check still failing. Absent for a turn that finished what it started.",
+        "What its last turn left open: steps it never completed. Absent for a turn that finished what it started.",
+    ),
+    // Written by the turn's own settle from its tool calls; nothing is asked of the model to earn or clear it.
+    proof: TurnProofSchema.optional().describe(
+        "What its last turn showed of its work: whether a check it ran passed after its last edit, and whether it looked at interface files it changed. Absent until a turn that edited or checked anything has ended.",
     ),
     // Completed turns and lifetime tool calls, the card's msgs/tools counters.
     turns: z.number().optional().describe("Turns it has finished."),
@@ -484,6 +508,27 @@ export const AgentSummarySchema = z.object({
                 startedAt: z.number().describe("When it started, in milliseconds."),
                 endedAt: z.number().optional().describe("When the command exited, in milliseconds. Absent while it runs."),
                 exitCode: z.number().int().optional().describe("The code it exited with. Absent while it runs, or when its exit left none."),
+                // What the turn that left it running decided about it (agent/tools/job-fates.ts): one of these, or none
+                // while its turn is still going.
+                watch: z
+                    .string()
+                    .optional()
+                    .describe(
+                        "The watch its exit wakes this conversation through. Present once the turn that left it running has ended and the conversation is waiting on it.",
+                    ),
+                handed: z
+                    .boolean()
+                    .optional()
+                    .describe(
+                        "Left running for the person: the turn's reply gave its address, so it outlives the turn, wakes nothing and is theirs to stop.",
+                    ),
+                ports: z.array(z.number().int()).optional().describe("The ports it was listening on when its turn ended."),
+                stoppedBy: z
+                    .enum(["turn", "person", "agent"])
+                    .optional()
+                    .describe(
+                        "Who stopped it: the sandbox, when the turn that used it ended without handing it over; a person; or the agent itself. Present from the moment the stop is asked. Absent for a job that exited by itself.",
+                    ),
             }),
         )
         .optional()
@@ -514,6 +559,10 @@ export const AgentStopWatchingSchema = AgentIdSchema.extend({
     watchId: z.string().optional().describe("Which watch to disarm. Absent disarms every watch this conversation is parked on."),
 });
 
+export const AgentStopJobSchema = AgentIdSchema.extend({
+    jobId: z.string().min(1).describe("Which of its background jobs, by the id its card and transcript row carry."),
+});
+
 // Pages a transcript: a read returns its most recent turns and where they start (`from`); handing that back as `before`
 // asks for the page above. A stale cursor (a rewind, a fork) is clamped, never refused.
 export const AgentTranscriptQuerySchema = AgentIdSchema.extend({

package/src/schemas/git/git.ts

@@ -450,6 +450,11 @@ export const AgentChangesSchema = z.object({
 });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
 
+// The review's `conflicts` alone, re-derived the same way. The whole review also takes a code-only line count per
+// file, and on a branch of hundreds of files that count, not the conflict check, is what takes seconds.
+export const AgentConflictsSchema = AgentChangesSchema.pick({ conflicts: true });
+export type AgentConflicts = z.infer<typeof AgentConflictsSchema>;
+
 // Names scratch exactly as `AgentChanges.scratch` lists it; anything else is refused, so a stale list cannot reach a
 // file that was never scratch.
 export const AgentScratchSchema = z.object({

package/src/schemas/hosts.ts

@@ -35,9 +35,17 @@ export const DeviceFactsSchema = z.object({
     // the rest are other sandboxes' addresses, and a sandbox has no business learning its siblings'. Absent from an
     // agent older than this field, which is why "none unreachable" is not the same value as "did not say".
     links: z.object({ total: z.number(), unreachable: z.number(), unreachableSince: z.number().optional() }).optional(),
+    // What this agent understands beyond the ops every agent has, so a caller can refuse up front rather than send a
+    // field an older agent drops without a word. Absent from an agent older than this field: it supports none of them.
+    features: z.array(z.string()).optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 
+// `reshape` with `later`: save the change for the next restart. An agent without it strips `later` from the request and
+// reshapes NOW, restarting the sandbox and interrupting everyone in it, which is why a later-reshape is never sent to one.
+export const DEVICE_FEATURE_RESHAPE_LATER = "reshape-later";
+export const deviceSupports = (facts: Pick<DeviceFacts, "features"> | undefined, feature: string): boolean => facts?.features?.includes(feature) === true;
+
 // Docker Desktop's own distros: `wsl -l -q` lists them like any other, and none ever runs an agent or holds a checkout.
 export const WSL_SYSTEM_DISTROS: ReadonlySet<string> = new Set(["docker-desktop", "docker-desktop-data"]);
 

package/src/schemas/metrics.ts

@@ -140,6 +140,8 @@ export const STORAGE_CLEANABILITY = {
     other: "none",
     // Git data and checkouts of repositories deleted from the workspace; nothing reads it again, but it may hold commits never pushed.
     trash: "confirm",
+    // Transcripts as they were before the sandbox converted them to its current format; nothing reads them again.
+    backups: "confirm",
     // Copies of the sandbox packed for download.
     exports: "confirm",
     // Files agents produced: generated images, reports, harness output.

package/src/schemas/offload.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/runner-protocol.js";
+
+// OFFLOADED WORK, as the in-sandbox `offload-run` command and the editor see it (settings `offload`): a heavy line this
+// sandbox hands a runner on one of the owner's machines instead of running it itself.
+
+// Whether a runner can take a line right now, asked before the tree is snapshotted, so a machine that is asleep costs
+// nothing. `name` is the machine the runner sits on, the word the owner picked it by.
+export const OffloadTargetSchema = z.object({
+    runner: z.string().min(1),
+    name: z.string().min(1),
+    ready: z.boolean(),
+    // Why not, in the words the command prints before it runs the line here instead.
+    why: z.string().optional(),
+});
+export type OffloadTarget = z.infer<typeof OffloadTargetSchema>;
+
+export const OffloadRunSchema = RunnerCommandSchema.extend({ runner: z.string().min(1) });
+export type OffloadRun = z.infer<typeof OffloadRunSchema>;
+
+// What a run streams back: the runner's own frames, or one refusal when the runner could not take it after all (it went
+// offline between the question and the run, or it predates offloading), which sends the line back here.
+export const OffloadFrameSchema = z.union([...RunnerCommandFrameSchema.options, z.object({ kind: z.literal("refused"), why: z.string() })]);
+export type OffloadFrame = z.infer<typeof OffloadFrameSchema>;
+
+// One offloaded run as the runner card lists it: the recent ones, kept in memory, newest first.
+export const OffloadRecordSchema = z.object({
+    runId: z.string(),
+    runner: z.string(),
+    name: z.string(),
+    label: z.string(),
+    // The line, cut to a readable length.
+    command: z.string(),
+    startedAt: z.number(),
+    endedAt: z.number().optional(),
+    code: z.number().int().optional(),
+    failure: z.string().optional(),
+});
+export type OffloadRecord = z.infer<typeof OffloadRecordSchema>;
+
+// One kind of heavy work the owner can send elsewhere: a heavy-command rule this sandbox queues (its id, as settings
+// `offload.commands` keys it) and the pattern that sorts a line into it.
+export const OffloadKindSchema = z.object({ id: z.string().min(1), pattern: z.string() });
+export type OffloadKind = z.infer<typeof OffloadKindSchema>;

package/src/schemas/personas.ts

@@ -125,9 +125,9 @@ export const TURN_BRIEFING_NOTES: readonly TurnBriefingNote[] = [
     },
     {
         id: "checks",
-        label: "Automatic end-of-turn checks",
-        when: "First message, and again after a compaction, when you have rules that run at the end of a turn.",
-        cost: "Your checks still run; the agent just does not know they are coming, so a failure arrives as a surprise it has to re-read the turn to understand.",
+        label: "Checks after landing",
+        when: "First message and after a compaction, and again whenever the main tree's own check turns red or back to green: what runs after its work lands, and which failures the main tree already has.",
+        cost: "The agent does not know which failures are the main tree's own and not its doing, so it may spend a turn chasing one somebody else is already fixing.",
     },
     {
         id: "dependencies",

package/src/schemas/ports.ts

@@ -45,6 +45,16 @@ export const PortSummarySchema = z.object({
         .describe(
             'The terminal it came from, to watch it in or stop it from. Absent when nothing in its ancestry is one, which is the honest "you cannot reach this from here".',
         ),
+    // A job an agent's turn left running for the person (AgentSummary.jobs[].handed); ports listed anywhere else stay
+    // unclaimed by any conversation.
+    job: z
+        .object({
+            conversationId: z.string().describe("The conversation whose turn left it running."),
+            jobId: z.string().describe("The job, as that conversation's card names it; stopping it stops this port."),
+            label: z.string().describe("What the job is, in the agent's own words when it gave any."),
+        })
+        .optional()
+        .describe("The background job an agent left running for you on this port, when that is what answers here."),
     forwarded: z.boolean().describe("Whether it is currently reachable from outside."),
     // `https://port-<slot>-<sandboxId>.<zone>`.
     previewUrl: z.string().optional().describe("Where to open it. Present only while forwarded, and only on a sandbox that has an outside address."),

package/src/schemas/providers/plan-limits.ts

@@ -24,11 +24,24 @@ export const UsageWindowSchema = z.object({
     gates: WindowGatesSchema,
 });
 export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+// A failed re-read, whatever the cause: a 429 park, a 403 asking for verification, a 5xx, a timeout. Recorded as the fact
+// "the last attempt failed", never inferred from a list of known failure kinds, so a surface that dates readings by
+// age can leave out every reading that cannot move, including one whose failure nobody has seen before.
+export const UsageUnreadSchema = z.object({
+    since: z.number().describe("When re-reading this account first failed, in milliseconds. It has failed on every attempt since."),
+    reason: z
+        .string()
+        .describe("Why, in the provider's own words where it gave some (\"Verify your account to continue.\"). Short enough to print; never a pasted response body."),
+});
+export type UsageUnread = z.infer<typeof UsageUnreadSchema>;
 // Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
 // within a window, so a stale reading is still a valid floor. `measuredAt` is epoch ms — windows are seconds.
 export const AccountUsageSchema = z.object({
     windows: z.array(UsageWindowSchema),
     measuredAt: z.number(),
+    unread: UsageUnreadSchema.optional().describe(
+        "Present while re-reading this account keeps failing: these windows are the last reading that succeeded, and `measuredAt` will not move until a read succeeds again.",
+    ),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
 // Anthropic's once-a-week reset of the session window only; the weekly allowance is untouched. The answer is entirely