@intentic/sandbox-contract 1.330.0 → 1.332.0

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

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.

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/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

@@ -45,12 +45,37 @@ export type RuntimeInstall = z.infer<typeof RuntimeInstallSchema>;
 // (`environment propose`) clears its tool's entries.
 export const SettledDraftSchema = z.object({ tool: z.string(), hash: z.string(), at: z.number() });
 export type SettledDraft = z.infer<typeof SettledDraftSchema>;
+// One overlay the daemon composed, by the hash a rebuild is stamped with, and the custom-section blocks it carried (each
+// by name and the hash of its trimmed steps). Kept so "is this tool in the image" is answered against the overlay the
+// running container was actually built from, which is rarely the newest one composed: every approval, capability change
+// and daemon update composes again, and a rebuild builds whatever was newest when it started.
+export const EnvironmentCompositionSchema = z.object({
+    hash: z.string(),
+    at: z.number(),
+    blocks: z.array(z.object({ name: z.string(), hash: z.string() })),
+});
+export type EnvironmentComposition = z.infer<typeof EnvironmentCompositionSchema>;
+// A draft the daemon wrote on its own (a recurring runtime install, a cache-rule revision of an approved block), by the
+// name its file carries and the hash of its steps. A draft that later vanishes with no answer on record was thrown away
+// by hand (the Changes panel's discard, a git clean): that is read as a no, rather than writing it back on the next
+// sweep. `install` is the ledger entry an auto-draft came from, which a no declines.
+export const EnvironmentOfferSchema = z.object({
+    tool: z.string(),
+    hash: z.string(),
+    at: z.number(),
+    install: z.string().optional(),
+});
+export type EnvironmentOffer = z.infer<typeof EnvironmentOfferSchema>;
 export const RuntimeInstallsFileSchema = z.object({
     installs: z.array(RuntimeInstallSchema),
     // The last drift snapshot, persisted so a daemon restart does not blank the card until the next sweep.
     drift: EnvironmentDriftSchema.optional(),
     // Drafts already answered, newest last and capped; absent on a ledger written before removal existed.
     settled: z.array(SettledDraftSchema).optional(),
+    // Overlays composed, oldest first and capped; absent on a ledger written before they were kept.
+    compositions: z.array(EnvironmentCompositionSchema).optional(),
+    // Drafts the daemon wrote that nobody has answered yet; absent on a ledger written before they were kept.
+    offered: z.array(EnvironmentOfferSchema).optional(),
 });
 export type RuntimeInstallsFile = z.infer<typeof RuntimeInstallsFileSchema>;
 // Ledger entry as the Environment card shows it: recurrence joined with whether it's present in the live container

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"],
+    });
+});