@intentic/sandbox-contract 1.331.0 → 1.333.0

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

package/src/schemas/automations.ts

@@ -180,11 +180,15 @@ export type AutomationTarget = z.infer<typeof AutomationTargetSchema>;
 export const FireOnSchema = z.enum(["pass", "change"]);
 export type FireOn = z.infer<typeof FireOnSchema>;
 // What the daemon remembers of a watch between checks (.intentic/records/automation-watch.json), and what the list
-// shows under it. Values are kept whole up to a bound, so the next check can say what changed.
+// shows under it. Values are kept whole up to a bound, so the next check can say what changed; whether anything changed
+// is decided on the digest of the whole value, so a page longer than the bound is not "changed" on every check.
 export const WatchStateSchema = z.object({
     armedAt: z.number().describe("When it was first checked, in milliseconds."),
     checkedAt: z.number().describe("When it was last checked, in milliseconds."),
-    value: z.string().optional().describe("What the last passing check saw. Absent until one has passed."),
+    value: z.string().optional().describe("What the last passing check saw, cut to a bound. Absent until one has passed."),
+    digest: z.string().optional().describe("sha256 of the whole of what the last passing check saw, before any cut."),
+    // A watch edited to check something else starts over: what the old check saw says nothing about the new one.
+    condition: z.string().optional().describe("Which check this state belongs to: a digest of the guard or source it was recorded for."),
     changedAt: z.number().optional().describe("When what it saw last changed, in milliseconds."),
     firedAt: z.number().optional().describe("When it last set something off, in milliseconds."),
     // Why the last check did not pass, when it did not.
@@ -431,7 +435,7 @@ export const AutomationSchema = z.object({
     enabled: z.boolean().describe("Whether it fires at all."),
 });
 export type Automation = z.infer<typeof AutomationSchema>;
-// A wake held for owner approval (.intentic/records/approvals/<id>.json); snapshots the trigger payload so an approved
+// A wake held for owner approval (automation-holds/<id>.json on the history volume); snapshots the trigger payload so an approved
 // run replays exactly what fired, even across a daemon restart.
 export const AutomationApprovalSchema = z.object({
     id: entryId.describe("This waiting item's own id, which approving and rejecting take."),
@@ -472,7 +476,7 @@ export const AutomationApprovalSchema = z.object({
         .number()
         .optional()
         .describe(
-            "When it goes ahead on its own, in milliseconds, for a hold that is only a delay. Absent for one that genuinely waits on a person.",
+            "When it goes ahead on its own, in milliseconds, for a hold that is only a delay. Absent for one that genuinely waits on a person, and for one the sandbox did not itself queue, which only a person releases.",
         ),
 });
 export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
@@ -480,7 +484,14 @@ export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
 // Whether a held wake waits on a person. A countdown hold (`autoRunAt`) releases itself, so counting it would ask the
 // owner about something already about to happen on its own.
 export const awaitsOwner = (wake: Pick<AutomationApproval, "autoRunAt">): boolean => wake.autoRunAt === undefined;
-export const AutomationApprovalsListSchema = z.object({ approvals: z.array(AutomationApprovalSchema).describe("Everything waiting for a yes.") });
+export const AutomationApprovalsListSchema = z.object({
+    approvals: z.array(AutomationApprovalSchema).describe("Everything waiting for a yes."),
+    // Reported, never dropped: a file in the queue the sandbox cannot read would otherwise be a hold that never runs and never says why.
+    unreadable: z
+        .array(z.string())
+        .default([])
+        .describe("Files in the queue this sandbox could not read, by name. Each is a held wake that cannot be released until it is fixed or removed."),
+});
 export const AutomationApprovalIdParamSchema = z.object({ id: z.string().describe("Which waiting item.") });
 export const AutomationRunSchema = z.object({
     at: z.number(),

package/src/schemas/daemon-health.test.ts

@@ -0,0 +1,28 @@
+import { type DaemonHealth, DaemonHealthReadingSchema, DaemonHealthSchema } from "./system.js";
+
+const answer: DaemonHealth = {
+    ok: true,
+    sandboxId: "0123456789ab",
+    profile: "workspace",
+    boot: { ready: true, startedAt: 1, steps: [] },
+    state: { journal: "none", engine: 84 },
+    announce: { state: "registered", at: 2 },
+    reach: { state: "reachable", at: 3 },
+    reachedBy: "tunnel",
+    build: { version: "1.2.3" },
+};
+
+test("the daemon's answer parses whole as the contract's health", () => {
+    expect(DaemonHealthSchema.parse(answer)).toEqual(answer);
+});
+
+test("a reader takes any daemon's answer, a field of the wrong shape reading as missing", () => {
+    expect(DaemonHealthReadingSchema.parse({ ok: true, ready: false, boot: "starting", state: { journal: 7 }, reachedBy: "tunnel" })).toEqual({
+        ok: true,
+        ready: false,
+        boot: undefined,
+        state: { journal: undefined },
+        reachedBy: "tunnel",
+    });
+    expect(DaemonHealthReadingSchema.parse(answer)).toMatchObject({ sandboxId: "0123456789ab", boot: { ready: true }, announce: { state: "registered" } });
+});

package/src/schemas/device-swaps.test.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { DeviceSwapsSchema } from "./device-swaps.js";
+
+// The rows `ic sandbox swaps --json` answers, as examples: golden/swap-verdicts.json holds each of ic's records and the
+// row it gives (the Rust test, _sandbox/ic/src/sandbox/swaps.rs, builds every one; the machine agent's fallback is held
+// to the same rows). This is the TS half: the rows ic gives are the rows the contract reads, to the field.
+
+interface VerdictCase {
+    readonly name: string;
+    readonly record: string;
+    readonly now: number;
+    readonly swap: Record<string, unknown> | null;
+}
+
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "swap-verdicts.json"), "utf8")) as {
+    readonly slug: string;
+    readonly cases: readonly VerdictCase[];
+};
+const rows: unknown[] = GOLDEN.cases.flatMap((one) => (one.swap === null ? [] : [one.swap]));
+
+test("every row ic gives for the golden records is a row the contract reads, field for field", () => {
+    expect(rows.length).toBeGreaterThan(8);
+    const read: unknown = DeviceSwapsSchema.parse(rows);
+    expect(read).toEqual(rows);
+});
+
+test("a row from a newer ic keeps the swap going on: an unknown phase and an extra field still read", () => {
+    const [row] = DeviceSwapsSchema.parse([{ slug: "work", phase: "staging", at: 5, cutoverInProgress: false, next: "later" }]);
+    expect(row).toMatchObject({ slug: "work", phase: "staging", at: 5, cutoverInProgress: false });
+});
+
+test("a field of the wrong type is a field that is not there, but a row without its verdict is no row", () => {
+    const [row] = DeviceSwapsSchema.parse([{ slug: "work", phase: "cutover", at: 5, alive: "soon", cutoverInProgress: true }]);
+    expect(row?.alive).toBeUndefined();
+    expect(DeviceSwapsSchema.safeParse([{ slug: "work", phase: "cutover", at: 5 }]).success).toBe(false);
+});

package/src/schemas/device-swaps.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+// WHAT `ic sandbox swaps --json` ANSWERS, one row per sandbox whose channel record names a swap in flight or on
+// probation. `ic` is the one reader of its own swap records: `cutoverInProgress` is its verdict (a live ic run's
+// heartbeat, `swap_alive`, is fresh), and every other process asks for it here instead of judging the record again. The
+// command reads ic's home and not Docker, so it answers while Docker is down. golden/swap-verdicts.json holds each
+// record's row, and ic's Rust test and the machine agent's tests both read it.
+
+// Read loosely: a `phase` a newer ic adds is still a swap going on, and a field of an unexpected shape is a field that
+// is not there. A row that lacks its identity or its verdict is no row at all (the caller falls back to the records).
+export const DeviceSwapSchema = z.looseObject({
+    slug: z.string().min(1),
+    // ic's word: `cutover` (the old container is parked, the new one not yet proven) or `probation` (it is being watched).
+    phase: z.string().min(1),
+    // When the cutover began, epoch milliseconds.
+    at: z.number().int().nonnegative(),
+    // The last heartbeat of the ic run doing the cutover.
+    alive: z.number().int().nonnegative().optional().catch(undefined),
+    // When a probation ends and the parked container is let go.
+    probationUntil: z.number().int().nonnegative().optional().catch(undefined),
+    // ic's verdict at the moment it answered: this cutover is being done right now by a live ic run.
+    cutoverInProgress: z.boolean(),
+});
+export type DeviceSwap = z.infer<typeof DeviceSwapSchema>;
+
+export const DeviceSwapsSchema = z.array(DeviceSwapSchema);

package/src/schemas/devices.ts

@@ -101,6 +101,9 @@ export const DeviceSandboxSchema = z.object({
     // so this side adopted it for its rounds: `keptElsewhere` is left out, and these say whose it was and since when.
     adoptedFrom: z.string().optional(),
     keeperSilentSince: z.number().optional(),
+    // (2026-10-10) Stopped by the machine's keeper after a stretch nobody needed it (`ic sandbox sleep`), and started
+    // again by itself when somebody opens it. `running` is false while this is true.
+    asleep: z.boolean().optional(),
 });
 export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
@@ -318,12 +321,18 @@ export const DeviceSandboxIdSchema = z
     .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
 // A folder on the DEVICE for `sync-install` to keep in step. The only caller-supplied string that reaches a command
 // line, so its shape is the guard: `~`, an absolute POSIX path or a drive letter, and none of the characters that would
-// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here.
+// end the argument it sits in. `~` is expanded by the daemon, which is why `$` is not allowed to arrive here. The line
+// may be PowerShell, which reads the typographic quotes “ ” „ as double quotes and ‘ ’ ‚ ‛ as single quotes beside the
+// ASCII ones, so those are refused too: the daemon quotes the folder, and this keeps a second guard where one quoter
+// misses a character.
 export const DeviceLocalDirSchema = z
     .string()
     .min(1)
     .max(4096)
-    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r]*$/);
+    // The curly quotes as escapes: bun's transpiler rewrites a literal one in a regex to its escape and tsgo keeps it,
+    // so spelled literally the pattern reads differently from source and from dist, and contract.lock.json can match
+    // only one of them.
+    .regex(/^(?:~|\/|[A-Za-z]:[\\/])[^"'`$;|&\n\r\u201C\u201D\u201E\u2018\u2019\u201A\u201B]*$/);
 // A TCP port number, the one value a caller supplies that reaches a command line as a number rather than a string.
 export const PortNumberSchema = z.number().int().min(1).max(65535);
 export const DeviceCommandInputSchema = z.object({

package/src/schemas/engines.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 // An engine is the installed program a runtime (agent-catalog.ts) spawns or imports — the `claude` binary, `codex`
 // wrapper, `@cursor/sdk`, `opencode`, `cli-proxy-api` — not the loop itself; one engine can back several runtimes.
 
-export const ENGINE_IDS = ["claude", "codex", "cursor", "opencode", "translator"] as const;
+export const ENGINE_IDS = ["claude", "codex", "cursor", "devin", "opencode", "translator"] as const;
 export type EngineId = (typeof ENGINE_IDS)[number];
 export const EngineIdSchema = z.enum(ENGINE_IDS);
 

package/src/schemas/environment.ts

@@ -216,3 +216,7 @@ export const BundleExportSchema = z.object({
 });
 export type BundleExport = z.infer<typeof BundleExportSchema>;
 export const BundleExportsSchema = z.object({ exports: z.array(BundleExportSchema) });
+// POST /bundles names the export it started, which fills in as it packs.
+export const BundleStartedSchema = z.object({ name: z.string() });
+// POST /bundles/ticket: the short-lived credential a download navigation carries, since it cannot send a bearer header.
+export const BundleTicketSchema = z.object({ ticket: z.string(), expiresAt: z.number() });

package/src/schemas/git/git-scope.test.ts

@@ -0,0 +1,91 @@
+import { type GitChange, UNATTRIBUTED_ORIGIN } from "./git.js";
+import { changeIsFrom, DISCARDABLE_SIDES, discardOutcome, isWholeRepo, scopedPaths, STAGEABLE_SIDES, UNSTAGEABLE_SIDES } from "./git-scope.js";
+
+const change = (path: string, extra: Partial<GitChange> = {}): GitChange => ({ path, status: "modified", ...extra });
+
+// Shape a scan produces: small enough to read, with something on every side.
+const sides = {
+    conflicted: [change("merge.ts", { status: "conflicted" })],
+    staged: [change("staged.ts"), change("moved.ts", { status: "renamed", from: "old.ts" })],
+    unstaged: [change("edited.ts"), change("new.ts", { status: "added" })],
+};
+
+test("a scope with no side reads every side the verb can move, and no others", () => {
+    // Staged is deliberately absent from stageable: re-adding it would sweep in worktree edits made after the freeze.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, {})).toEqual(["edited.ts", "new.ts", "merge.ts"]);
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, {})).toEqual(["staged.ts", "moved.ts", "old.ts"]);
+    expect(scopedPaths(sides, DISCARDABLE_SIDES, {})).toEqual(["merge.ts", "staged.ts", "moved.ts", "old.ts", "edited.ts", "new.ts"]);
+});
+
+test("a scope narrows the verb's sides and can never widen them", () => {
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "unstaged" })).toEqual(["edited.ts", "new.ts"]);
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "conflicted" })).toEqual(["merge.ts"]);
+    // Staging the one side it can't move answers empty, not everything: the honest answer to an impossible request.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "staged" })).toEqual([]);
+});
+
+test("both legs of a rename resolve together, so no verb acts on half a move", () => {
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, { side: "staged" })).toContain("old.ts");
+});
+
+test("an origin scope keeps only what that conversation landed, either leg of a rename counting", () => {
+    const origins = { "edited.ts": ["agent-a"], "new.ts": ["agent-b"], "old.ts": ["agent-a"] };
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { origin: "agent-a" }, origins)).toEqual(["edited.ts"]);
+    // `moved.ts` attributes through the path it came from, the leg the land recorded.
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, { origin: "agent-a" }, origins)).toEqual(["moved.ts", "old.ts"]);
+    // A side and an origin compose as an intersection, not either alone.
+    expect(scopedPaths(sides, DISCARDABLE_SIDES, { side: "unstaged", origin: "agent-b" }, origins)).toEqual(["new.ts"]);
+    // No matching attribution resolves to nothing, not a fallback to everyone's work.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { origin: "agent-a" })).toEqual([]);
+});
+
+// The Changes panel's "You" chip sends this; it used to resolve to nothing, so its Stage all, Discard and commit
+// each moved no file at all.
+test("the unattributed origin keeps exactly what no conversation landed, a rename counting only when neither leg was", () => {
+    const origins = { "edited.ts": ["agent-a"], "old.ts": ["agent-a"] };
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { origin: UNATTRIBUTED_ORIGIN }, origins)).toEqual(["new.ts", "merge.ts"]);
+    // `moved.ts` came from a landed path, so it is the agent's work, not the owner's.
+    expect(scopedPaths(sides, UNSTAGEABLE_SIDES, { origin: UNATTRIBUTED_ORIGIN }, origins)).toEqual(["staged.ts"]);
+    // With nothing attributed, every row is the owner's.
+    expect(scopedPaths(sides, STAGEABLE_SIDES, { side: "unstaged", origin: UNATTRIBUTED_ORIGIN })).toEqual(["edited.ts", "new.ts"]);
+});
+
+test("a path listed on two sides at once resolves to one entry", () => {
+    const both = { conflicted: [], staged: [change("a.ts")], unstaged: [change("a.ts")] };
+    expect(scopedPaths(both, DISCARDABLE_SIDES, {})).toEqual(["a.ts"]);
+});
+
+test("a scope that narrows nothing is the whole repository", () => {
+    expect(isWholeRepo({})).toBe(true);
+    expect(isWholeRepo({ side: "unstaged" })).toBe(false);
+    expect(isWholeRepo({ origin: "agent-a" })).toBe(false);
+});
+
+// The panel's count, its discard question and the daemon's scope all read this one predicate, so a rename out of an
+// agent's file cannot be "yours" in the question and the agent's in the action.
+test("a row is an origin's when either leg was landed by it, and the owner's only when neither was", () => {
+    const origins = { "util.ts": ["agent-a"] };
+    const renamed = change("helpers.ts", { status: "renamed", from: "util.ts" });
+    expect(changeIsFrom(renamed, "agent-a", origins)).toBe(true);
+    expect(changeIsFrom(renamed, UNATTRIBUTED_ORIGIN, origins)).toBe(false);
+    expect(changeIsFrom(change("mine.ts"), UNATTRIBUTED_ORIGIN, origins)).toBe(true);
+    expect(changeIsFrom(change("mine.ts"), "agent-a", origins)).toBe(false);
+});
+
+test("a discard names what leaves the disk apart from what returns to its last commit", () => {
+    const changed = {
+        conflicted: [],
+        staged: [
+            change("helpers.ts", { status: "renamed", from: "util.ts" }),
+            change("fresh.ts", { status: "added" }),
+            change("gone.ts", { status: "deleted" }),
+        ],
+        // `gone.ts` deleted in the index and recreated on disk reads untracked, yet the last commit still holds it.
+        unstaged: [change("edited.ts"), change("scratch.ts", { status: "added" }), change("gone.ts", { status: "added" })],
+    };
+    const paths = scopedPaths(changed, DISCARDABLE_SIDES, {});
+    expect(discardOutcome(changed, paths)).toEqual({
+        deletes: ["helpers.ts", "fresh.ts", "scratch.ts"],
+        restores: ["util.ts", "gone.ts", "edited.ts"],
+    });
+});