@intentic/sandbox-contract 1.310.0 → 1.312.0

package/src/events/transcript.ts

@@ -311,8 +311,9 @@ export const holdsRequest = (row: TranscriptRequests): boolean => REQUEST_FIELDS
 // Whether a row is holding the turn open on a card nobody has answered.
 export const isAwaitingDecision = (row: TranscriptRequests): boolean => REQUEST_FIELDS.some((field) => row[field]?.status === "pending");
 
-// One change to a run's rows, so a client keeps rows rather than frames. Prose/thinking append to a row; a `tool` card
-// replaces whole by id; everything else replaces its row; `drop` removes a row that opened and never wrote.
+// One change to a run's rows, so a client keeps rows rather than frames. Prose/thinking append to a row or a card; a
+// `tool` card replaces its own fields by id, never its nested calls or thinking, which arrive by their own patches;
+// everything else replaces its row; `drop` removes a row that opened and never wrote.
 export const TranscriptPatchSchema = z.discriminatedUnion("op", [
     z.object({ op: z.literal("append").describe("A new row at the end."), row: TranscriptRowSchema }),
     z.object({ op: z.literal("replace").describe("This row, whole, in place of the one at that index."), index: z.number().int().nonnegative(), row: TranscriptRowSchema }),
@@ -320,7 +321,17 @@ export const TranscriptPatchSchema = z.discriminatedUnion("op", [
     z.object({ op: z.literal("text").describe("More of the agent's prose, onto that row's text."), index: z.number().int().nonnegative(), text: z.string() }),
     z.object({ op: z.literal("thinking").describe("More of the agent's reasoning, onto that row's thinking."), index: z.number().int().nonnegative(), text: z.string() }),
     z.object({
-        op: z.literal("tool").describe("A tool card, whole: new, or the latest state of one already there, matched by id wherever it nests."),
+        op: z.literal("toolThinking").describe("More of a delegated subagent's reasoning, onto the thinking of the card that started it."),
+        index: z.number().int().nonnegative(),
+        id: z.string().describe("The card's id, matched wherever it nests."),
+        text: z.string(),
+    }),
+    z.object({
+        op: z
+            .literal("tool")
+            .describe(
+                "A tool card's own fields: new, or the latest state of one already there, matched by id wherever it nests. Carries no `children` or `thinking`; a card already there keeps its own.",
+            ),
         index: z.number().int().nonnegative(),
         tool: TranscriptToolSchema,
         parent: z.string().optional().describe("The card this one nests under, when it is a delegated subagent's own call."),

package/src/events/verify-nudge.ts

@@ -1,6 +1,7 @@
-// The follow-up the daemon sends when a turn ended with work it could not confirm: the runtimes with no Stop hook get
-// their turn.ending asks this way (verify-nudge.ts), as an ordinary prompt. Its opening lives on the wire because the
-// chat has to recognise it coming back: a prompt nobody typed must not reach a reader as their own words.
+// The follow-up the daemon USED to send when a turn ended with work it could not confirm. Nothing sends it any more:
+// checks run after work lands, never inside a conversation (schemas/workspace/mainline.ts). It stays on the wire because
+// records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not reach a reader as
+// their own words.
 
 // Anchored on by the reader, so it must stay unique and stable across releases — a reworded opening un-recognises every
 // nudge already in a record, and they read as the user's own typing again.

package/src/front/generated/wire.ts

@@ -0,0 +1,104 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Answer = { "answer": "preview", route: PreviewRoute, } | { "answer": "terminal", plan: TerminalPlan, 
+/**
+ * The member whose ticket opened it, lowercased; absent when the daemon runs without auth.
+ */
+member?: string, };
+
+/**
+ * A PEM certificate chain and its PEM private key.
+ */
+export type Certificate = { certificate: string, privateKey: string, };
+
+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>, };
+
+/**
+ * Request headers only the front sets on what it forwards to Node; it strips them from everything arriving outside.
+ * Exported as a literal type, so a Node constant naming one that drifts from this spelling fails to compile.
+ */
+export type FrontHeader = "x-intentic-preview" | "x-intentic-preview-unreachable";
+
+/**
+ * Every port the front binds, as Node's config names them; an absent one is not bound.
+ */
+export type ListenConfig = { daemon: Endpoint, preview?: Endpoint, loopback?: Endpoint, 
+/**
+ * The 12-hex id every public hostname ends in; without one, a label's prefix alone classifies it.
+ */
+sandboxId?: string, 
+/**
+ * Origins that may frame a preview besides the preview itself.
+ */
+frameAncestors: Array<string>, 
+/**
+ * A preview path Node answers whatever its host resolves to.
+ */
+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.
+ */
+export type Question = { "question": "preview", host: string, } | { "question": "terminal", query: string, };
+
+export type Scheme = "http" | "https";
+
+/**
+ * What the browser sends on a terminal socket, each a JSON text frame.
+ */
+export type TerminalClientMessage = { "type": "input", data: string, } | { "type": "resize", cols: number, rows: number, } | { "type": "ping" };
+
+/**
+ * What a terminal socket opens onto, as Node decided from its ticket, session name and working directory.
+ */
+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, };
+
+/**
+ * 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" };
+
+/**
+ * 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.
+ */
+export type TerminalUpgrade = "intentic-terminal";
+
+/**
+ * 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>, };
+
+/**
+ * The ingress tunnel's door and the reachability grant it presents there.
+ */
+export type TunnelConfig = { url: string, grant: string, };
+
+/**
+ * A local upstream a preview host relays to.
+ */
+export type Upstream = { host: string, port: number, scheme: Scheme, 
+/**
+ * Rewrites Host and Origin to `localhost:<port>`, for an app that never agreed to its preview name.
+ */
+localhost: boolean, 
+/**
+ * Framed by the editor: `frame-ancestors` is set and `x-frame-options` dropped.
+ */
+frameable: boolean, };
+
+/**
+ * A checkout whose changes the front counts: its working tree, the git dir holding its index and HEAD, and the common
+ * dir holding refs and excludes (the git dir itself for a repository's main checkout).
+ */
+export type WatchedCheckout = { dir: string, gitDir: string, commonDir: string, };

package/src/front/terminal-frames.fixture.json

@@ -0,0 +1,55 @@
+{
+    "session": "/system/transport",
+    "upgrade": "intentic-terminal",
+    "frames": [
+        {
+            "encoded": "00000000081b5b33316d68c3a9",
+            "frame": {
+                "kind": "pane",
+                "bytes": "1b5b33316d68c3a9"
+            }
+        },
+        {
+            "encoded": "010000001c7b2274797065223a22696e707574222c2264617461223a22c582227d",
+            "frame": {
+                "kind": "message",
+                "text": "{\"type\":\"input\",\"data\":\"ł\"}"
+            }
+        },
+        {
+            "encoded": "020000001703f0617574686f72697a6174696f6e207265766f6b6564",
+            "frame": {
+                "kind": "close",
+                "code": 1008,
+                "reason": "authorization revoked"
+            }
+        },
+        {
+            "encoded": "0200000000",
+            "frame": {
+                "kind": "close",
+                "reason": ""
+            }
+        },
+        {
+            "encoded": "0300000000",
+            "frame": {
+                "kind": "ping",
+                "bytes": ""
+            }
+        },
+        {
+            "encoded": "040000000101",
+            "frame": {
+                "kind": "pong",
+                "bytes": "01"
+            }
+        }
+    ],
+    "unreadable": [
+        "0500000000",
+        "01ffffffff",
+        "020000000103",
+        "0100000002c328"
+    ]
+}

package/src/front/terminal-frames.test.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { TERMINAL_UPGRADE, type TerminalFrame, WEBTRANSPORT_PATH, encodeTerminalFrame, terminalFrameReader } from "./terminal-frames.js";
+
+interface FixtureFrame {
+    readonly kind: TerminalFrame["kind"];
+    readonly bytes?: string;
+    readonly text?: string;
+    readonly code?: number;
+    readonly reason?: string;
+}
+
+const FIXTURE = JSON.parse(readFileSync(new URL("./terminal-frames.fixture.json", import.meta.url), "utf8")) as {
+    session: string;
+    upgrade: string;
+    frames: { encoded: string; frame: FixtureFrame }[];
+    unreadable: string[];
+};
+
+const hex = (value: string): Uint8Array => Uint8Array.from(value.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16));
+
+const frameOf = ({ kind, bytes, text, code, reason }: FixtureFrame): TerminalFrame => {
+    if (kind === "message") {
+        return { kind, text: text ?? "" };
+    }
+    if (kind === "close") {
+        return code === undefined ? { kind, reason: reason ?? "" } : { kind, code, reason: reason ?? "" };
+    }
+    return { kind, bytes: hex(bytes ?? "") };
+};
+
+const MAX = 16 * 1024 * 1024;
+
+test("the session's path and the upgrade are the ones the edge and the front answer", () => {
+    expect(FIXTURE.session).toBe(WEBTRANSPORT_PATH);
+    expect(FIXTURE.upgrade).toBe(TERMINAL_UPGRADE);
+});
+
+test("every frame the shared fixture names encodes to its bytes and reads back", () => {
+    expect(FIXTURE.frames.length).toBeGreaterThan(5);
+    for (const { encoded, frame } of FIXTURE.frames) {
+        expect(encodeTerminalFrame(frameOf(frame))).toEqual(hex(encoded));
+        expect(terminalFrameReader(MAX)(hex(encoded))).toEqual([frameOf(frame)]);
+    }
+});
+
+test("frames read the same however the stream's chunks cut them", () => {
+    const whole = hex(FIXTURE.frames.map(({ encoded }) => encoded).join(""));
+    const expected = FIXTURE.frames.map(({ frame }) => frameOf(frame));
+    for (const size of [1, 2, 3, 7, whole.length]) {
+        const read = terminalFrameReader(MAX);
+        const frames: TerminalFrame[] = [];
+        for (let at = 0; at < whole.length; at += size) {
+            frames.push(...read(whole.slice(at, at + size)));
+        }
+        expect(frames).toEqual(expected);
+    }
+});
+
+test("a frame no front sends ends the stream", () => {
+    for (const encoded of FIXTURE.unreadable) {
+        expect(() => terminalFrameReader(MAX)(hex(encoded))).toThrow();
+    }
+});

package/src/front/terminal-frames.ts

@@ -0,0 +1,102 @@
+// A terminal's messages on a stream no WebSocket rides (a WebTransport one): a kind byte, a big-endian u32 length, then
+// that many bytes, one WebSocket message's worth each. The front's Rust codec reads the fixture this file's test reads.
+
+import type { TerminalUpgrade } from "./generated/wire.js";
+
+export const TERMINAL_UPGRADE: TerminalUpgrade = "intentic-terminal";
+
+// Where a browser opens its WebTransport session, on the address of the sandbox the session's streams reach; the edge
+// answers it, never the sandbox.
+export const WEBTRANSPORT_PATH = "/system/transport";
+
+const HEADER_BYTES = 5;
+
+// Indexed by the kind byte.
+const KINDS = ["pane", "message", "close", "ping", "pong"] as const;
+
+export type TerminalFrame =
+    | { readonly kind: "pane" | "ping" | "pong"; readonly bytes: Uint8Array }
+    | { readonly kind: "message"; readonly text: string }
+    // No code is a close that names none, as a WebSocket's may.
+    | { readonly kind: "close"; readonly code?: number; readonly reason: string };
+
+const utf8 = new TextEncoder();
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+
+const payloadOf = (frame: TerminalFrame): Uint8Array => {
+    switch (frame.kind) {
+        case "message":
+            return utf8.encode(frame.text);
+        case "close": {
+            if (frame.code === undefined) {
+                return new Uint8Array(0);
+            }
+            const reason = utf8.encode(frame.reason);
+            const payload = new Uint8Array(2 + reason.length);
+            new DataView(payload.buffer).setUint16(0, frame.code);
+            payload.set(reason, 2);
+            return payload;
+        }
+        default:
+            return frame.bytes;
+    }
+};
+
+export const encodeTerminalFrame = (frame: TerminalFrame): Uint8Array => {
+    const payload = payloadOf(frame);
+    const encoded = new Uint8Array(HEADER_BYTES + payload.length);
+    encoded[0] = KINDS.indexOf(frame.kind);
+    new DataView(encoded.buffer).setUint32(1, payload.length);
+    encoded.set(payload, HEADER_BYTES);
+    return encoded;
+};
+
+const frameOf = (kind: (typeof KINDS)[number], payload: Uint8Array): TerminalFrame => {
+    switch (kind) {
+        case "message":
+            return { kind, text: strictUtf8.decode(payload) };
+        case "close": {
+            if (payload.length === 0) {
+                return { kind, reason: "" };
+            }
+            if (payload.length < 2) {
+                throw new Error("a close frame's code is two bytes");
+            }
+            const code = new DataView(payload.buffer, payload.byteOffset, 2).getUint16(0);
+            return { kind, code, reason: strictUtf8.decode(payload.subarray(2)) };
+        }
+        default:
+            return { kind, bytes: payload };
+    }
+};
+
+// Whole frames out of a stream's chunks however the chunks cut them. Throws on a kind, a length past `maxBytes` or a
+// payload no front sends, since nothing after it on the stream can be framed.
+export const terminalFrameReader = (maxBytes: number): ((chunk: Uint8Array) => TerminalFrame[]) => {
+    let pending = new Uint8Array(0);
+    return (chunk) => {
+        const joined = new Uint8Array(pending.length + chunk.length);
+        joined.set(pending);
+        joined.set(chunk, pending.length);
+        const view = new DataView(joined.buffer);
+        const frames: TerminalFrame[] = [];
+        let at = 0;
+        while (joined.length - at >= HEADER_BYTES) {
+            const kind = KINDS[joined[at] ?? KINDS.length];
+            if (kind === undefined) {
+                throw new Error(`no terminal frame is of kind ${joined[at]}`);
+            }
+            const length = view.getUint32(at + 1);
+            if (length > maxBytes) {
+                throw new Error(`a terminal frame of ${length} bytes is past ${maxBytes}`);
+            }
+            if (joined.length - at - HEADER_BYTES < length) {
+                break;
+            }
+            frames.push(frameOf(kind, joined.subarray(at + HEADER_BYTES, at + HEADER_BYTES + length)));
+            at += HEADER_BYTES + length;
+        }
+        pending = joined.slice(at);
+        return frames;
+    };
+};

package/src/ids/conversation-ids.ts

@@ -178,6 +178,13 @@ const digest = (text: string): string => {
 
 export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${digest(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.
+// Seconds in base36 keep it short; the workspace root is spelled `workspace`, since its project folder is empty.
+export const LAND_FIX_PREFIX = "land-fix-";
+export const landFixConversationId = (project: string, redSince: number): string =>
+    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(redSince / 1000).toString(36)}`;
+
 // ONE FAILURE, MANY ATTEMPTS, ONE LIVE ANSWER. The derived id above names the FAILURE; an attempt at it is a
 // conversation of its own, so starting over (another model, a clean worktree) never rewrites a record some other window
 // is showing, and every attempt keeps its own transcript, cost and URL. Attempt 1 wears the bare id, so every id minted

package/src/ids/hostnames.fixture.json

@@ -0,0 +1,20 @@
+[
+    { "host": "preview-web-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "panel": "web" },
+    { "host": "preview-my-app-abcdef012345.sbx.example.test:443", "sandboxId": "abcdef012345", "panel": "my-app" },
+    { "host": "preview-shop--web-abcdef012345.example.com", "sandboxId": "abcdef012345", "panel": "shop--web" },
+    { "host": "preview-web-0123456789ab.sbx.example.test", "sandboxId": "abcdef012345" },
+    { "host": "preview--abcdef012345.sbx.example.test", "sandboxId": "abcdef012345" },
+    { "host": "preview-x-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "panel": "x" },
+    { "host": "port-1a2b3c4d5e6f-abcdef012345.sbx.example.test:8443", "sandboxId": "abcdef012345", "port": "1a2b3c4d5e6f" },
+    { "host": "public-9f8e7d6c5b4a-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345", "public": "9f8e7d6c5b4a" },
+    { "host": "sandbox-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345" },
+    { "host": "app.example.com", "sandboxId": "abcdef012345" },
+    { "host": "preview-web.localhost:8788", "panel": "web" },
+    { "host": "port-a.localhost", "port": "a" },
+    { "host": "public-z.example.com", "public": "z" },
+    { "host": "preview-.localhost" },
+    { "host": "127.0.0.1:8788" },
+    { "host": "[::1]:8788" },
+    { "host": "" },
+    { "host": "Preview-web-abcdef012345.sbx.example.test", "sandboxId": "abcdef012345" }
+]

package/src/ids/hostnames.test.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import {
     labelHostname,
     panelFromHost,
@@ -8,6 +9,7 @@ import {
     previewHostname,
     previewLabel,
     previewUrl,
+    publicSlotFromHost,
     sandboxHostname,
     sandboxIdFromUrl,
     syncFolder,
@@ -15,6 +17,24 @@ import {
 
 const ID = "abc123def456";
 
+// The cases the front's Rust router is held to as well (_sandbox/front, route.rs), read from the one file both run.
+interface HostCase {
+    readonly host: string;
+    readonly sandboxId?: string;
+    readonly panel?: string;
+    readonly port?: string;
+    readonly public?: string;
+}
+const HOST_CASES = JSON.parse(readFileSync(new URL("./hostnames.fixture.json", import.meta.url), "utf8")) as HostCase[];
+
+test.each(HOST_CASES)("the shared host cases parse as the front parses them: $host", (hostCase) => {
+    expect({
+        panel: panelFromHost(hostCase.host, hostCase.sandboxId),
+        port: portSlotFromHost(hostCase.host, hostCase.sandboxId),
+        public: publicSlotFromHost(hostCase.host, hostCase.sandboxId),
+    }).toEqual({ panel: hostCase.panel, port: hostCase.port, public: hostCase.public });
+});
+
 test("preview and port hostnames round-trip through their Host-header parsers", () => {
     expect(panelFromHost(`${previewHostname("shop--web", ID, "example.com")}:443`, ID)).toBe("shop--web");
     expect(portSlotFromHost(`${portHostname("a", ID, "example.com")}:443`, ID)).toBe("a");

package/src/index.ts

@@ -40,6 +40,7 @@ import { skillsContract } from "./contracts/skills.contract.js";
 import { systemContract } from "./contracts/system.contract.js";
 import { translatorContract } from "./contracts/translator.contract.js";
 import { usageContract } from "./contracts/usage.contract.js";
+import { offloadContract } from "./contracts/offload.contract.js";
 import { vpnContract } from "./contracts/vpn.contract.js";
 import { workflowsContract } from "./contracts/workflows.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
@@ -100,6 +101,7 @@ export { systemContract } from "./contracts/system.contract.js";
 export { translatorContract } from "./contracts/translator.contract.js";
 export { type PlanLimitsHeld, type PlanLimitsRefreshed, PlanLimitsRefreshedSchema, usageContract } from "./contracts/usage.contract.js";
 export { netdiskContract } from "./contracts/netdisk.contract.js";
+export { offloadContract } from "./contracts/offload.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
@@ -110,6 +112,7 @@ export * from "./events/resume.js";
 export * from "./events/system-events.js";
 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/watch-wake.js";
 export * from "./policy/request-status.js";
@@ -210,25 +213,28 @@ export * from "./schemas/secrets.js";
 export * from "./schemas/netdisk.js";
 export * from "./schemas/sessions.js";
 export * from "./schemas/settings.js";
+export * from "./schemas/settings-history.js";
 export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
 export * from "./schemas/system-prompt.js";
 export * from "./schemas/system.js";
 export * from "./schemas/terminal.js";
 export * from "./schemas/turn-break.js";
+export * from "./schemas/keep-warm.js";
 export * from "./schemas/providers/usage.js";
 export * from "./schemas/vpn.js";
+export * from "./schemas/offload.js";
 export * from "./schemas/webext.js";
 export * from "./schemas/workflows.js";
 export * from "./schemas/workspace/workspace-repos.js";
 export * from "./schemas/workspace/workspace-search.js";
+export * from "./schemas/workspace/mainline.js";
 export * from "./schemas/workspace/workspace-setup.js";
 export * from "./schemas/workspace/workspace-tree.js";
 export * from "./state/arrival.js";
 export * from "./state/definition.js";
 export * from "./policy/search-globs.js";
 export * from "./state/starter.js";
-export * from "./protocol/terminal-protocol.js";
 export * from "./text/title.js";
 export * from "./state/versions.js";
 export * from "./text/model-answer.js";
@@ -277,6 +283,7 @@ export const sandboxContract = {
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
+    offload: offloadContract,
     exit: exitContract,
     netdisk: netdiskContract,
     workflows: workflowsContract,

package/src/policy/command-run.test.ts

@@ -0,0 +1,35 @@
+import type { CommandRun } from "../schemas/ci.js";
+import { followCommandRun } from "./command-run.js";
+
+const RUNNING: CommandRun = { status: "running", command: "pnpm test", output: "" };
+const PASSED: CommandRun = { status: "passed", command: "pnpm test", output: "ok" };
+
+test("a poll that fails is reported and retried, and the run is still followed to its verdict", async () => {
+    const answers: Array<CommandRun | Error> = [new Error("daemon restarting"), RUNNING, PASSED];
+    const errors: unknown[] = [];
+    const settled = await followCommandRun(
+        async () => {
+            const next = answers.shift();
+            if (next instanceof Error) {
+                throw next;
+            }
+            return next as CommandRun;
+        },
+        { intervalMs: 1, onError: (cause) => errors.push(cause) },
+    );
+    expect(settled).toEqual(PASSED);
+    expect(errors).toEqual([new Error("daemon restarting")]);
+});
+
+test("a throw from onState is the caller's bug and reaches the caller, not a poll failure retried forever", async () => {
+    const errors: unknown[] = [];
+    const following = followCommandRun(async () => RUNNING, {
+        intervalMs: 1,
+        onState: () => {
+            throw new TypeError("state.session is undefined");
+        },
+        onError: (cause) => errors.push(cause),
+    });
+    await expect(following).rejects.toThrow("state.session is undefined");
+    expect(errors).toEqual([]);
+});

package/src/policy/command-run.ts

@@ -10,8 +10,9 @@ export interface FollowRunOptions<R extends CommandRun> {
     readonly signal?: AbortSignal | undefined;
     // Every state read, settled or not, for a surface that draws progress.
     readonly onState?: ((run: R) => void) | undefined;
-    // A poll that failed, not a run that failed: the run is still going, and following continues.
-    readonly onError?: ((cause: unknown) => void) | undefined;
+    // A poll that failed, not a run that failed: the run is still going, and following continues. Required, since a
+    // loop that retries a failing read forever with nobody told looks exactly like a run that is still going.
+    readonly onError: (cause: unknown) => void;
 }
 
 // Follows a run to its verdict: reads state until it is no longer running. The one shared loop, so a dropped poll isn't
@@ -22,14 +23,18 @@ export const followCommandRun = async <R extends CommandRun>(read: () => Promise
         if (signal?.aborted === true) {
             return undefined;
         }
+        // Only the read is a poll that may fail and be retried; a throw from `onState` is the caller's own bug.
+        let run: R | undefined;
         try {
-            const run = await read();
+            run = await read();
+        } catch (cause) {
+            onError(cause);
+        }
+        if (run !== undefined) {
             onState?.(run);
             if (run.status !== "running") {
                 return run;
             }
-        } catch (cause) {
-            onError?.(cause);
         }
         await sleep(intervalMs, { signal });
     }

package/src/protocol/container-requirements.test.ts

@@ -38,9 +38,8 @@ describe(`containerDrift`, () => {
         expect(containerDrift({ SANDBOX_PUBLIC_URL: `` })).toEqual([]);
     });
 
-    // A hosted Fly microVM has no grant by design, so this reports nothing on it.
-    it(`stays quiet on a hosted machine, which serves its address without dialling out`, () => {
-        expect(containerDrift({ SANDBOX_PUBLIC_URL: CURRENT.SANDBOX_PUBLIC_URL, SANDBOX_VM: `1` })).toEqual([]);
+    it(`holds a hosted machine to the same grant, since it dials the edge like any sandbox`, () => {
+        expect(containerDrift({ SANDBOX_PUBLIC_URL: CURRENT.SANDBOX_PUBLIC_URL, SANDBOX_VM: `1` }).map((gap) => gap.key)).toEqual([`reachability`]);
     });
 });
 

package/src/protocol/container-requirements.ts

@@ -7,8 +7,6 @@ export interface ContainerRequirement {
     readonly requires: readonly string[];
     // Absent `given` evidence means this sandbox never had the capability: not a fault, just unconfigured.
     readonly given: readonly string[];
-    // Row stays silent if any `unless` key is present: an alternate mechanism already satisfies the evidence.
-    readonly unless?: readonly string[];
     readonly enables: string;
     readonly lost: string;
     readonly repair: string;
@@ -25,8 +23,6 @@ export const CONTAINER_REQUIREMENTS: readonly ContainerRequirement[] = [
         key: "reachability",
         requires: ["SANDBOX_GRANT", "INGRESS_URL"],
         given: ["SANDBOX_PUBLIC_URL"],
-        // A Fly microVM's edge replays directly to it, so it holds no grant by design.
-        unless: ["SANDBOX_VM"],
         enables: "reaching this sandbox at its public address, from anywhere",
         lost:
             "Its public address answers 502 to everyone, including this browser when it is not on the same machine as the sandbox. " +
@@ -45,9 +41,7 @@ export interface ContainerGap {
 
 /** Empty means every requirement is met or not applicable; non-empty always means a setup rerun is needed. */
 export const containerDrift = (env: ContainerEnv): readonly ContainerGap[] =>
-    CONTAINER_REQUIREMENTS.filter(
-        (requirement) => requirement.given.every((name) => present(env, name)) && !(requirement.unless ?? []).some((name) => present(env, name)),
-    )
+    CONTAINER_REQUIREMENTS.filter((requirement) => requirement.given.every((name) => present(env, name)))
         .map((requirement) => ({
             key: requirement.key,
             missing: requirement.requires.filter((name) => !present(env, name)),