@intentic/sandbox-contract 1.331.0 → 1.332.0

package/src/policy/tests/secret-hosts.test.ts

@@ -1,4 +1,4 @@
-import { hostAllowed, hostMatches, normalizeHost, normalizeHostPattern, tightensHostGuard } from "../secret-hosts.js";
+import { hostAllowed, hostCovers, hostMatches, normalizeHost, normalizeHostPattern, tightensHostGuard } from "../secret-hosts.js";
 
 // The pattern a person writes against the host a use would reach. Every boundary a limit turns on is pinned by value:
 // the apex a wildcard leaves out, the look-alike that only shares a suffix, and which edits take hosts away.
@@ -87,3 +87,19 @@ describe("tightensHostGuard", () => {
         expect(tightensHostGuard(on("api.github.com"), on("*.api.github.com"))).toBe(false);
     });
 });
+
+describe("hostCovers", () => {
+    it("reads a plain entry as a domain and every host under it, never a lookalike", () => {
+        expect(hostCovers("example.com", "example.com")).toBe(true);
+        expect(hostCovers("example.com", "api.example.com")).toBe(true);
+        expect(hostCovers("example.com", "a.b.example.com")).toBe(true);
+        expect(hostCovers("example.com", "notexample.com")).toBe(false);
+        expect(hostCovers("example.com", "example.com.evil.net")).toBe(false);
+    });
+
+    it("reads a wildcard as the hosts under it only", () => {
+        expect(hostCovers("*.example.com", "api.example.com")).toBe(true);
+        expect(hostCovers("*.example.com", "example.com")).toBe(false);
+        expect(hostCovers("*.example.com", "notexample.com")).toBe(false);
+    });
+});

package/src/policy/turned-away.ts

@@ -13,6 +13,8 @@ const TURNED_AWAY: ReadonlySet<string> = new Set([
     "model-helper-only",
     // The privacy shield refused an untrusted provider on a runtime it cannot read by content at all.
     "privacy-unshielded",
+    // The turn carries a tool list its runtime cannot keep.
+    "tools-unenforced",
     // The protected execution boundary refused admission, not an executed provider/runtime failure.
     "agent-domain-refused",
     // The privacy shield found personal data in instructions a runtime loads itself, where it could not mask them.

package/src/protocol/doors/runner-protocol.ts

@@ -20,6 +20,10 @@ export const RunnerHelloSchema = z.object({
     // Compared against what the parent runs to report parity (outdated → rebuild action); an outdated runner still runs
     // turns rather than being refused.
     image: z.string(),
+    // The image `image` was composed from (SANDBOX_BASE_IMAGE). Parity compares this, not `image`: an overlay build's
+    // tag names its own container (`intentic-sandbox-env-<slug>:<hash>`), so two sides on one base and one overlay
+    // never share it. Absent on an old image, which is then compared by `image` alone.
+    baseImage: z.string().optional(),
     channel: z.string().optional(),
     overlayHash: z.string().optional(),
     // Runner's declared settings-only sandbox.toml (definition.ts), diffed against the parent's to itemize drift;
@@ -106,13 +110,22 @@ export type RunnerCredentialRefreshRequest = z.infer<typeof RunnerCredentialRefr
 export const RunnerCredentialRefreshSchema = z.object({ accessToken: z.string().optional() });
 export type RunnerCredentialRefresh = z.infer<typeof RunnerCredentialRefreshSchema>;
 
-// What a runner is, hardware-wise: what the placement picker shows and a future scheduler would weigh.
+// What a runner is, hardware-wise, and how full it is right now: what the placement picker shows and the fleet advice
+// (runners/fleet-advice.ts) weighs. Re-asked on demand rather than only at connect, so the live half stays live.
 export const RunnerFactsSchema = z.object({
     cpus: z.number().int().positive(),
     memoryMb: z.number().int().positive(),
     freeDiskMb: z.number().int().nonnegative(),
     // 0..1 over the last minute; a coarse busy signal for a picker, not a metrics feed.
     load: z.number().nonnegative(),
+    // The runner's own resource budget, the figures its turn door admits by: what is free under its memory limit, and
+    // that limit. Absent from a runner that predates them, which is then sized by `memoryMb` alone.
+    memoryFreeMb: z.number().int().nonnegative().optional(),
+    memoryLimitMb: z.number().int().positive().optional(),
+    // Pressure stall over the last ten seconds, in percent: anything waiting for a CPU, everything waiting on memory.
+    // Absent where the kernel does not report it.
+    cpuPressure: z.number().nonnegative().optional(),
+    memoryStall: z.number().nonnegative().optional(),
 });
 export type RunnerFacts = z.infer<typeof RunnerFactsSchema>;
 

package/src/protocol/pairing-redeem.test.ts

@@ -0,0 +1,86 @@
+import { redeemWhileWarming, type RedeemRetry } from "./pairing-redeem.js";
+
+/* The redeem loop both pairing peers run, over a sandbox the test plays one answer at a time. */
+
+const scripted = (answers: readonly (number | "offline" | "hang")[]) => {
+    const tries: number[] = [];
+    const send = async (attempt: number, signal: AbortSignal | undefined): Promise<Response> => {
+        tries.push(attempt);
+        const next = answers[attempt - 1] ?? answers.at(-1) ?? "offline";
+        if (next === "offline") {
+            throw new TypeError("fetch failed");
+        }
+        if (next === "hang") {
+            return new Promise<Response>((_resolve, reject) => signal?.addEventListener("abort", () => reject(signal.reason)));
+        }
+        return new Response(`status ${next}`, { status: next });
+    };
+    return { tries, send };
+};
+
+const statusOf = (outcome: Awaited<ReturnType<typeof redeemWhileWarming>>): number | undefined =>
+    outcome.kind === "answered" ? outcome.response.status : undefined;
+
+describe("redeemWhileWarming", () => {
+    it("answers the first reply below 500 without asking again", async () => {
+        const { tries, send } = scripted([200]);
+        expect(statusOf(await redeemWhileWarming(send, { attempts: 3, delayMs: 0 }))).toBe(200);
+        expect(tries).toEqual([1]);
+    });
+
+    it("asks again through a warming sandbox and an unreachable one, saying why each time", async () => {
+        const { tries, send } = scripted(["offline", 502, 200]);
+        const heard: { attempt: number; why: RedeemRetry["kind"] }[] = [];
+        const outcome = await redeemWhileWarming(send, { attempts: 5, delayMs: 0, onRetry: (attempt, why) => heard.push({ attempt, why: why.kind }) });
+        expect(statusOf(outcome)).toBe(200);
+        expect(tries).toEqual([1, 2, 3]);
+        expect(heard).toEqual([
+            { attempt: 1, why: "unreachable" },
+            { attempt: 2, why: "warming" },
+        ]);
+    });
+
+    it("hands back a 401 at once: an expired code is an answer, not a blip", async () => {
+        const { tries, send } = scripted([401, 200]);
+        expect(statusOf(await redeemWhileWarming(send, { attempts: 5, delayMs: 0 }))).toBe(401);
+        expect(tries).toEqual([1]);
+    });
+
+    it("answers the last 5xx when the sandbox is still warming after every try", async () => {
+        const { tries, send } = scripted([503]);
+        const heard: number[] = [];
+        const outcome = await redeemWhileWarming(send, { attempts: 3, delayMs: 0, onRetry: (attempt) => heard.push(attempt) });
+        expect(outcome.kind).toBe("answered");
+        expect(outcome.kind === "answered" ? await outcome.response.text() : undefined).toBe("status 503");
+        expect(tries).toEqual([1, 2, 3]);
+        // The last try is not retried, so it is not narrated as one.
+        expect(heard).toEqual([1, 2]);
+    });
+
+    it("is unreachable, with the last try's failure, when nothing ever answered", async () => {
+        const { tries, send } = scripted(["offline"]);
+        const outcome = await redeemWhileWarming(send, { attempts: 2, delayMs: 0 });
+        expect(outcome.kind).toBe("unreachable");
+        expect(outcome.kind === "unreachable" ? outcome.error : undefined).toBeInstanceOf(TypeError);
+        expect(tries).toEqual([1, 2]);
+    });
+
+    it("abandons a try that outlives its timeout and asks again", async () => {
+        const { tries, send } = scripted(["hang", 200]);
+        expect(statusOf(await redeemWhileWarming(send, { attempts: 2, delayMs: 0, timeoutMs: 10 }))).toBe(200);
+        expect(tries).toEqual([1, 2]);
+    });
+
+    it("rejects with the stop's reason rather than answering when its signal aborts", async () => {
+        const stop = new AbortController();
+        const { tries, send } = scripted([502]);
+        const running = redeemWhileWarming(send, {
+            attempts: 5,
+            delayMs: 60_000,
+            signal: stop.signal,
+            onRetry: () => stop.abort(new Error("stopped")),
+        });
+        await expect(running).rejects.toThrow("stopped");
+        expect(tries).toEqual([1]);
+    });
+});

package/src/protocol/pairing-redeem.ts

@@ -0,0 +1,79 @@
+import { retry, withDeadline } from "@intentic/base/async";
+
+// Redeeming a pairing code's one-time token, as every peer that takes one does it (the machine agent's
+// `postWhileWarming`, the webext's `redeemPairing`): a sandbox still warming up answers 5xx through its tunnel, or
+// nothing at all, and is asked again. Any other answer, a 401 above all (the code has expired), is the caller's to read
+// at once: asking again would only delay the fresh code the person has to fetch.
+
+// Why a try is being asked again: no answer at all, or a 5xx from a sandbox not ready yet.
+export type RedeemRetry = { readonly kind: "unreachable"; readonly error: unknown } | { readonly kind: "warming"; readonly status: number };
+
+export type RedeemOutcome =
+    // The sandbox's answer: below 500 at once, or still 5xx when the tries ran out.
+    | { readonly kind: "answered"; readonly response: Response }
+    // No answer at all on the last try; `error` is that try's failure.
+    | { readonly kind: "unreachable"; readonly error: unknown };
+
+export interface RedeemOptions {
+    // Tries in all, the first included.
+    readonly attempts: number;
+    // The wait between tries.
+    readonly delayMs: number;
+    // How long one try may take before it is abandoned and counts as unreachable; none when absent.
+    readonly timeoutMs?: number | undefined;
+    // Stops the tries: a stop rejects with the signal's reason rather than answering.
+    readonly signal?: AbortSignal | undefined;
+    // Hears each try that is about to be asked again, before the wait.
+    readonly onRetry?: ((attempt: number, why: RedeemRetry) => void) | undefined;
+}
+
+// A 5xx carried out of a try so `retry` asks again, and handed back as the answer when the tries run out.
+class Warming extends Error {
+    constructor(readonly response: Response) {
+        super(`the sandbox is warming up (HTTP ${response.status})`);
+    }
+}
+
+// Runs `send` (one POST, handed the try's number and a signal to pass to its fetch, undefined when there is neither a
+// deadline nor a stop) until the sandbox answers below 500 or the tries run out.
+export const redeemWhileWarming = async (
+    send: (attempt: number, signal: AbortSignal | undefined) => Promise<Response>,
+    options: RedeemOptions,
+): Promise<RedeemOutcome> => {
+    const { attempts, delayMs, timeoutMs, signal, onRetry } = options;
+    const once = (attempt: number): Promise<Response> =>
+        timeoutMs === undefined ? send(attempt, signal) : withDeadline((bounded) => send(attempt, bounded), timeoutMs, { signal });
+    try {
+        const response = await retry(
+            async (attempt) => {
+                let answer: Response;
+                try {
+                    answer = await once(attempt);
+                } catch (error) {
+                    if (attempt < attempts && signal?.aborted !== true) {
+                        onRetry?.(attempt, { kind: "unreachable", error });
+                    }
+                    throw error;
+                }
+                if (answer.status < 500) {
+                    return answer;
+                }
+                if (attempt < attempts) {
+                    onRetry?.(attempt, { kind: "warming", status: answer.status });
+                }
+                throw new Warming(answer);
+            },
+            { attempts, delayMs: () => delayMs, signal },
+        );
+        return { kind: "answered", response };
+    } catch (error) {
+        if (signal?.aborted === true) {
+            // oxlint-disable-next-line typescript/only-throw-error -- the stop's own reason, as an aborted fetch rejects with it
+            throw signal.reason;
+        }
+        if (error instanceof Warming) {
+            return { kind: "answered", response: error.response };
+        }
+        return { kind: "unreachable", error };
+    }
+};

package/src/protocol/peer-mcp-server.ts

@@ -2,6 +2,7 @@
 // namespace keeps zod's 60 locales (~250 kB) that esbuild can otherwise drop. _devices/webext/scripts/size-budget.mjs holds the ceiling.
 import { prettifyError, toJSONSchema } from "zod";
 import type * as z from "zod";
+import { isRecord } from "@intentic/base/escape";
 
 // The MCP version every peer announces, here rather than in host-protocol.ts because a browser extension bundles this
 // module and would otherwise carry the machine handshake's schemas to a store. Also read by the daemon's peer bridge,
@@ -99,8 +100,6 @@ export interface McpServerSpec<Ctx> {
     readonly audit: (entry: McpAuditEntry) => Promise<void> | void;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
-
 // Handles one JSON-RPC message; returns undefined for a notification. `ctx` is read per call, so a grant pushed
 // mid-session takes effect on the next call.
 export const createMcpServer = <Ctx>(spec: McpServerSpec<Ctx>): ((message: unknown, ctx: Ctx) => Promise<Record<string, unknown> | undefined>) => {

package/src/protocol/raw/raw-json-routes.ts

@@ -10,6 +10,7 @@ import {
 } from "../../schemas/environment.js";
 import { MemberEmailSchema, MemberGrantSchema, MembersListSchema, MembersRosterSchema } from "../../schemas/members.js";
 import { OkSchema } from "../../schemas/shared.js";
+import { EnrollCodeAnswerSchema, EnrollCodeRequestSchema } from "../../schemas/short-codes.js";
 import { DefinitionDiffSchema, DefinitionExportSchema, WorkspacePublishResultSchema, WorkspacePublishSchema, WorkspaceRemoteSchema } from "../../state/definition.js";
 import type { RawRouteKey } from "./raw-routes.js";
 
@@ -24,6 +25,8 @@ export interface RawJsonRoute {
 }
 
 export const RAW_JSON_ROUTES = {
+    // A server-connect code for the owner's command (short-codes.ts).
+    "POST /system/enroll/code": { input: EnrollCodeRequestSchema, output: EnrollCodeAnswerSchema },
     // The roster is ownership's; every write answers the roster after it.
     "GET /members": { output: MembersRosterSchema },
     "POST /members": { input: MemberGrantSchema, output: MembersListSchema },

package/src/protocol/raw/raw-routes.ts

@@ -49,6 +49,8 @@ export const RAW_ROUTES = {
     "GET /system/desktop-view": { auth: "door", beforeBoot: true, control: "never" },
     // Deploy-target enrollment, gated by the connect token.
     "POST /enroll": { auth: "door", control: "never" },
+    // A server-connect code for the owner's command: its single-use enroll token stands in for the connect token.
+    "POST /system/enroll/code": { floor: "owner", control: "never" },
     // An event automation's webhook, gated by the automation's own token.
     "POST /automations/{id}/fire": { auth: "door" },
     // The release gate a pipeline runner waits on, gated by the workflow's minted gate token.
@@ -154,6 +156,9 @@ export const RAW_ROUTES = {
     "POST /ci/webhook/{host}": { auth: "door" },
     // Below maintainer a pairing is capped to port-mirror, so a collaborator may mint a preview tunnel.
     "POST /system/sync/pair": { floor: "collaborator", control: "never" },
+    // A copy-paste command's short code, redeemed by the install script it was handed to: a device's first contact,
+    // gated by the code itself and a limit on failed attempts (peers/redeem-codes.ts).
+    "POST /system/redeem/{code}": { auth: "door", control: "never" },
     // The peer doors: a device, browser or runner redeems its pairing at `enroll` and dials `connect` with the token.
     "POST /system/hosts/pair": { control: "never" },
     "POST /system/hosts/enroll": { auth: "door", control: "never" },

package/src/protocol/sse.test.ts

@@ -1,4 +1,4 @@
-import { sseData, sseFrames } from "./sse.js";
+import { parseSseText, type SseEvent, sseData, sseEvents, sseFrames, sseJson } from "./sse.js";
 
 const encoder = new TextEncoder();
 
@@ -47,3 +47,52 @@ it("reads a frame's data line as JSON, and nothing from a frame without one or w
     expect(sseData(`: keep-alive`)).toBeUndefined();
     expect(sseData(`data: {not json`)).toBeUndefined();
 });
+
+const collectEvents = async (events: AsyncGenerator<SseEvent>): Promise<SseEvent[]> => {
+    const seen: SseEvent[] = [];
+    for await (const event of events) {
+        seen.push(event);
+    }
+    return seen;
+};
+
+it("ends events at CRLF, CR and LF blank lines alike, a CRLF split across chunks included", async () => {
+    const { stream } = body([`data: 1\r\n\r`, `\ndata: 2\r\rdata: 3\n\n`], true);
+    expect((await collectEvents(sseEvents(stream))).map((event) => event.data)).toEqual([`1`, `2`, `3`]);
+});
+
+it("joins every data line of an event with a newline", () => {
+    expect(parseSseText(`data: {"a":\ndata: 1}\n\n`).map((event) => event.data)).toEqual([`{"a":\n1}`]);
+    expect(sseData(`data: {"a":\ndata: 1}`)).toEqual({ a: 1 });
+});
+
+it("reads event, id and retry, keeps the last id across events, and skips comments", () => {
+    const events = parseSseText(`: hello\nevent: turn\nid: 7\nretry: 3000\ndata: x\n\ndata: y\n\n`);
+    expect(events.map(({ event, data, id, retry }) => ({ event, data, id, retry }))).toEqual([
+        { event: `turn`, data: `x`, id: `7`, retry: 3000 },
+        { event: undefined, data: `y`, id: `7`, retry: undefined },
+    ]);
+});
+
+it("drops one space after the colon and no more, and a leading byte-order mark", () => {
+    expect(parseSseText(`\uFEFFdata:  two spaces\n\n`).map((event) => event.data)).toEqual([` two spaces`]);
+});
+
+it("keeps each event's raw text, its blank line included, for a reader forwarding it unchanged", () => {
+    expect(parseSseText(`event: a\r\ndata: 1\r\n\r\n: ping\n\n`).map((event) => event.raw)).toEqual([`event: a\r\ndata: 1\r\n\r\n`, `: ping\n\n`]);
+});
+
+it("dispatches an event the stream ended inside", async () => {
+    const { stream } = body([`data: last`], true);
+    expect((await collectEvents(sseEvents(stream))).map((event) => event.data)).toEqual([`last`]);
+});
+
+it("ends an event stream that goes silent past the idle window", async () => {
+    const { stream, cancelled } = body([`data: 1\n\n`], false);
+    expect((await collectEvents(sseEvents(stream, 20))).map((event) => event.data)).toEqual([`1`]);
+    expect(cancelled()).toBe(true);
+});
+
+it("sseJson reads a parsed event's data", () => {
+    expect([sseJson(parseSseText(`data: [1]\n\n`)[0]!), sseJson(parseSseText(`: c\n\n`)[0]!)]).toEqual([[1], undefined]);
+});

package/src/protocol/sse.ts

@@ -1,36 +1,166 @@
-// Low-level SSE framing for the daemon's streamed routes (oRPC eventIterator over HTTP): frames separated by
-// a blank line, each carrying one `data: <JSON>` line. Protocol-only (no domain shapes), shared by every
-// consumer of the wire: the web's chat/intentic streams and the ACP bridge's daemon client.
+// Server-Sent Events as the WHATWG event-stream grammar defines them, read off a byte stream that may be cut anywhere:
+// inside a UTF-8 character, inside a `\r\n`, inside an event. Protocol-only (no domain shapes). Its readers: the ACP
+// bridge and the extension SDK on the daemon's streamed routes, the privacy gateway's restorers, and the daemon's own
+// MCP calls (an app's tool calls, a capability probe's `initialize`). Each had a parser of its own, and they disagreed:
+// this one used to split on `\n\n` only and read the first `data:` line of an event, where the grammar allows `\r\n`
+// and `\r` and joins every data line with `\n`. The webchat widget reads its replies with it too, through the `./sse`
+// subpath: a bundle on customers' pages may take only modules with no imports, as this one is and must stay.
 
 // A live daemon writes to a stream at least this often (oRPC's keep-alive comment every 5 s, a heartbeat on the rest), so
 // this long with no bytes means the connection is dead even though nothing closed it.
 export const SSE_IDLE_MS = 120_000;
 
-// Yields each raw SSE frame (the text between blank-line separators) as it arrives, reassembling frames split
-// across network chunks. Ends, cancelling the reader, after `idleMs` of silence, so a reader of a daemon that went quiet
-// without closing (a sleeping laptop's tunnel, a wedged proxy) finishes instead of hanging.
-export async function* sseFrames(body: ReadableStream<Uint8Array>, idleMs: number = SSE_IDLE_MS): AsyncGenerator<string> {
+export interface SseEvent {
+    // The `event:` field, undefined when the event named none (a listener reads that as "message").
+    readonly event: string | undefined;
+    // The data lines joined with `\n`; undefined for a block with none (a comment, a keep-alive, a stray blank line).
+    readonly data: string | undefined;
+    // The last event id the stream has set, as EventSource carries it: it persists across events until set again.
+    readonly id: string | undefined;
+    // The reconnection time an event asked for, in milliseconds.
+    readonly retry: number | undefined;
+    // The event's own text as it arrived, its terminating blank line included, for a reader that forwards it unchanged.
+    readonly raw: string;
+}
+
+export interface SseParser {
+    readonly feed: (text: string) => void;
+    // The stream ended: an event it ended inside is dispatched as it stands.
+    readonly end: () => void;
+}
+
+interface Pending {
+    raw: string;
+    name: string | undefined;
+    data: string[] | undefined;
+    retry: number | undefined;
+}
+
+const fresh = (): Pending => ({ raw: ``, name: undefined, data: undefined, retry: undefined });
+
+// Fields per the grammar: `field: value` (one leading space dropped), `:` starts a comment, a blank line ends the event.
+// Every block is dispatched, a comment-only one too, so a reader forwarding the stream loses nothing; a reader of
+// messages skips the ones whose `data` is undefined.
+export const createSseParser = (dispatch: (event: SseEvent) => void): SseParser => {
+    let buffer = ``;
+    // How far into `buffer` is known to hold no terminator, so a long line arriving in small chunks is scanned once.
+    let scanned = 0;
+    let started = false;
+    let lastId: string | undefined;
+    let pending = fresh();
+
+    const emit = (): void => {
+        dispatch({ event: pending.name, data: pending.data?.join(`\n`), id: lastId, retry: pending.retry, raw: pending.raw });
+        pending = fresh();
+    };
+
+    const field = (name: string, value: string): void => {
+        if (name === `event`) {
+            pending.name = value;
+        } else if (name === `data`) {
+            pending.data = [...(pending.data ?? []), value];
+        } else if (name === `id` && !value.includes(`\0`)) {
+            lastId = value;
+        } else if (name === `retry` && /^\d+$/.test(value)) {
+            pending.retry = Number(value);
+        }
+    };
+
+    const line = (text: string, terminator: string): void => {
+        pending.raw += text + terminator;
+        if (text === ``) {
+            emit();
+            return;
+        }
+        if (text.startsWith(`:`)) {
+            return;
+        }
+        const colon = text.indexOf(`:`);
+        field(colon < 0 ? text : text.slice(0, colon), colon < 0 ? `` : text.slice(colon + (text.charAt(colon + 1) === ` ` ? 2 : 1)));
+    };
+
+    const lines = (final: boolean): void => {
+        const terminators = /\r\n|\r|\n/gu;
+        terminators.lastIndex = scanned;
+        let start = 0;
+        for (let found = terminators.exec(buffer); found !== null; found = terminators.exec(buffer)) {
+            // A `\r` that ends the buffer may be the first half of a `\r\n` still in flight.
+            if (found[0] === `\r` && found.index === buffer.length - 1 && !final) {
+                break;
+            }
+            line(buffer.slice(start, found.index), found[0]);
+            start = found.index + found[0].length;
+        }
+        buffer = buffer.slice(start);
+        scanned = Math.max(0, buffer.length - 1);
+    };
+
+    return {
+        feed: (text) => {
+            let next = text;
+            // The grammar drops one byte-order mark at the very start; it stays in the first event's raw text.
+            if (!started && next !== ``) {
+                started = true;
+                if (next.startsWith(`\uFEFF`)) {
+                    pending.raw += `\uFEFF`;
+                    next = next.slice(1);
+                }
+            }
+            buffer += next;
+            lines(false);
+        },
+        end: () => {
+            lines(true);
+            if (buffer !== ``) {
+                line(buffer, ``);
+                buffer = ``;
+            }
+            if (pending.raw !== ``) {
+                emit();
+            }
+        },
+    };
+};
+
+// Every event in a body already read whole (a short MCP answer), the last one dispatched even without its blank line.
+export const parseSseText = (text: string): SseEvent[] => {
+    const events: SseEvent[] = [];
+    const parser = createSseParser((event) => events.push(event));
+    parser.feed(text);
+    parser.end();
+    return events;
+};
+
+// Yields each event as it arrives. Ends, cancelling the reader, after `idleMs` of silence, so a reader of a daemon that
+// went quiet without closing (a sleeping laptop's tunnel, a wedged proxy) finishes instead of hanging.
+export async function* sseEvents(body: ReadableStream<Uint8Array>, idleMs: number = SSE_IDLE_MS): AsyncGenerator<SseEvent> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
-    let buffer = "";
+    let ready: SseEvent[] = [];
+    const parser = createSseParser((event) => ready.push(event));
     try {
         for (;;) {
             let timer: ReturnType<typeof setTimeout> | undefined;
-            const idle = new Promise<"idle">((resolve) => {
-                timer = setTimeout(() => resolve("idle"), idleMs);
+            const idle = new Promise<`idle`>((resolve) => {
+                timer = setTimeout(() => resolve(`idle`), idleMs);
             });
             // oxlint-disable-next-line eslint/no-await-in-loop -- streaming reader; each chunk must be awaited in order as it arrives
             const result = await Promise.race([reader.read(), idle]);
             clearTimeout(timer);
-            if (result === "idle" || result.done) {
+            if (result === `idle`) {
                 return;
             }
-            buffer += decoder.decode(result.value, { stream: true });
-            let separator = buffer.indexOf("\n\n");
-            while (separator !== -1) {
-                yield buffer.slice(0, separator);
-                buffer = buffer.slice(separator + 2);
-                separator = buffer.indexOf("\n\n");
+            if (result.done) {
+                parser.feed(decoder.decode());
+                parser.end();
+            } else {
+                parser.feed(decoder.decode(result.value, { stream: true }));
+            }
+            const events = ready;
+            ready = [];
+            yield* events;
+            if (result.done) {
+                return;
             }
         }
     } finally {
@@ -39,20 +169,36 @@ export async function* sseFrames(body: ReadableStream<Uint8Array>, idleMs: numbe
     }
 }
 
-// The parsed JSON payload of a frame's `data:` line, or undefined for a frame with no data line, an empty
-// payload, or malformed JSON (all cases the callers skip).
-export const sseData = (frame: string): unknown => {
-    const dataLine = frame.split("\n").find((line) => line.startsWith("data:"));
-    if (dataLine === undefined) {
-        return undefined;
+// Each event's text as it arrived, without the blank line that ended it: for a reader that keeps the frame and reads
+// it with `sseData`. The same idle window as `sseEvents`.
+export async function* sseFrames(body: ReadableStream<Uint8Array>, idleMs: number = SSE_IDLE_MS): AsyncGenerator<string> {
+    for await (const event of sseEvents(body, idleMs)) {
+        yield event.raw.replace(/(?:\r\n|\r|\n)+$/u, ``);
     }
-    const payload = dataLine.slice(5).trim();
-    if (payload.length === 0) {
+}
+
+// What a data payload parses to, before a caller's schema reads it.
+export type SseJsonValue = string | number | boolean | null | readonly SseJsonValue[] | { readonly [key: string]: SseJsonValue };
+
+// An event's data as JSON, or undefined for an event with no data, an empty payload, or malformed JSON (all cases
+// the callers skip).
+export const sseJson = (event: SseEvent): SseJsonValue | undefined => {
+    if (event.data === undefined || event.data.trim() === ``) {
         return undefined;
     }
     try {
-        return JSON.parse(payload);
+        // SAFETY: JSON.parse returns only JSON values; each caller's schema reads the shape it expects.
+        return JSON.parse(event.data) as SseJsonValue;
     } catch {
         return undefined; // Skip a malformed frame.
     }
 };
+
+// The same, for a frame's text as `sseFrames` yields it.
+export const sseData = (frame: string): SseJsonValue | undefined => {
+    const event = parseSseText(frame).find((parsed) => parsed.data !== undefined);
+    return event === undefined ? undefined : sseJson(event);
+};
+
+// The `event:` name of a frame's text, for a reader holding the frame rather than the parsed event.
+export const sseEventName = (frame: string): string | undefined => parseSseText(frame)[0]?.event;

package/src/schemas/agent.ts

@@ -128,6 +128,10 @@ export const ForkedFromSchema = z.object({
 });
 export type ForkedFrom = z.infer<typeof ForkedFromSchema>;
 // The turn's fields before the cross-field refinements below, so a subset (TurnProfileSchema) can be picked from them.
+// How many files one turn may carry. A batch of a person's queued messages joins their files, so the admission splits a
+// batch rather than build a turn past this (turn-admission.ts, together): a turn the daemon makes must parse back.
+export const ATTACHMENT_LIMIT = 20;
+
 const AgentTurnFieldsSchema = z.object({
     prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
     errand: TurnErrandSchema.optional().describe(
@@ -151,7 +155,7 @@ const AgentTurnFieldsSchema = z.object({
     // Already uploaded via /workspace/upload; Claude reads them via Read, Codex gets images as native input.
     attachments: z
         .array(z.string().min(1))
-        .max(20)
+        .max(ATTACHMENT_LIMIT)
         .optional()
         .describe("Files to hand the agent along with the prompt, as workspace paths. Upload them first."),
     // Read out of the prompt's own `@path` tokens rather than chosen: a tokenizer over pasted text guesses, so a
@@ -450,7 +454,7 @@ export const runPickOf = (choice: {
     ...(choice.thinking === undefined ? {} : { thinking: choice.thinking }),
     ...(choice.fast === undefined ? {} : { fast: choice.fast }),
 });
-/* ONE ENTRY OF ONE ROLE'S MODEL LIST (settings.modelRoles): the standing version of the pick above, and not merely which model but HOW it is to be run. */
+/* ONE ENTRY OF ONE SETUP'S MODEL LIST (settings.modelSetups): the standing version of the pick above, and not merely which model but HOW it is to be run. */
 export const ModelPinSchema = z.object({
     provider: AgentProviderSchema.describe("Which provider serves this work."),
     model: z.string().min(1).describe("Which of its models. Both halves, because a model name only means anything to the provider that serves it."),
@@ -538,12 +542,29 @@ export const ConversationQueueSchema = z.object({
     ),
 });
 export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
+// What taking a waiting message back left: the queue, and whether the conversation went with the message. A conversation
+// its scheduled message opened, in which nothing has happened since, exists only for that message.
+export const QueueTakenBackSchema = ConversationQueueSchema.extend({
+    unopened: z
+        .boolean()
+        .optional()
+        .describe(
+            "True when the message was the only thing in a conversation it had opened by being scheduled: no turn ran and nothing else waits. The conversation went with it, so its card is off the board and its id is free to open again. Absent otherwise, and from sandboxes older than the field.",
+        ),
+});
+export type QueueTakenBack = z.infer<typeof QueueTakenBackSchema>;
 // What resuming a queue did: started a turn with what waited, when nothing else ran.
 export const QueueResumedSchema = z.object({
     run: z.string().optional().describe("The turn the waiting messages started. Absent when a turn was already running, and they go after it."),
     queue: ConversationQueueSchema.optional().describe(
         "The queue the release left: what still waits once the turn took what it could. Absent from sandboxes older than the field.",
     ),
+    reason: z
+        .string()
+        .optional()
+        .describe(
+            "Why nothing went out though messages still wait, in a sentence: a spent allowance whose window is shut, a recovery the sandbox runs first, a paused queue. Absent when something went out, when they simply go after a running turn, and from sandboxes older than the field.",
+        ),
 });
 export type QueueResumed = z.infer<typeof QueueResumedSchema>;
 // Attaches to a conversation's newest run (live, or finished within retention); no cursor to resume from, the head