@intentic/sandbox-contract 1.317.0 → 1.318.0

package/src/contracts/device.contract.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { DeviceAgentFlowSchema, DeviceFlowLineSchema, DeviceReportSchema, DeviceSandboxFlowSchema } from "../schemas/devices.js";
 import { DeviceScopesSchema } from "../schemas/capabilities.js";
 import { DeviceFactsSchema } from "../schemas/hosts.js";
+import { LoopbackCatchEventSchema, LoopbackCatchSchema } from "../schemas/loopback-catch.js";
 import { OkSchema } from "../schemas/shared.js";
 
 // What a connected device can be asked, over the socket it opened; the machine is the oRPC server, the daemon the
@@ -26,4 +27,8 @@ export const deviceContract = {
     runSandboxFlow: oc.input(DeviceSandboxFlowSchema).output(streamOf(DeviceFlowLineSchema)),
     // Spawns the work detached from the socket, so restarting the agent process cannot brick a swap in progress.
     runAgentFlow: oc.input(DeviceAgentFlowSchema).output(streamOf(DeviceFlowLineSchema)),
+    // Watches one loopback address on this machine for a sign-in's redirect (schemas/loopback-catch.ts); only the
+    // daemon arms it, never a tool, and aborting the stream is how it stops. Sent only to an agent advertising
+    // `loopback-catch`.
+    catchLoopback: oc.input(LoopbackCatchSchema).output(streamOf(LoopbackCatchEventSchema)),
 };

package/src/contracts/endpoints.contract.ts

@@ -34,12 +34,21 @@ export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;
 export const LocalModelGpuSchema = z.enum(["granted", "unsupported", "absent"]);
 export type LocalModelGpu = z.infer<typeof LocalModelGpuSchema>;
 
+// Which one device a model runs at full speed on: the GPU when one reached this sandbox, else the host's RAM. One, never
+// a sum: a model split between a card and the CPU runs at the CPU's pace.
+export const LocalModelDeviceSchema = z.enum(["gpu", "host"]);
+export type LocalModelDevice = z.infer<typeof LocalModelDeviceSchema>;
+
 // One window rung priced against one model, so a surface never has to redo the arithmetic the start check will.
 const LocalModelWindowFitSchema = z.object({
     tokens: z.number().int().positive(),
     // Weights + KV cache + the runtime's own floor: the same estimate the admission check refuses a start on.
     totalBytes: z.number().int().nonnegative(),
+    // Whether it can load at all, GPU and host together: what a start is refused on.
     fits: z.boolean(),
+    // Whether all of it fits in the free memory of the one device, so it runs at that device's pace. A rung can fit and
+    // still run mostly on the CPU. Absent from a daemon older than the distinction.
+    fullSpeed: z.boolean().optional(),
 });
 
 const LocalModelOptionFitSchema = z.object({
@@ -72,14 +81,21 @@ export const LocalModelFitSchema = z.object({
     memoryCapped: z.boolean(),
     gpu: LocalModelGpuSchema,
     gpuMemoryBytes: z.number().int().nonnegative(),
-    // The budget a start is actually admitted against, not the raw total: a view that sizes against anything else can
-    // recommend a model the daemon then refuses.
+    // The GPU's free memory, on the card with the most of it; zero before the grant. Absent from an older daemon.
+    gpuFreeBytes: z.number().int().nonnegative().optional(),
+    // What a start is refused on: the host and the GPU together, since llama.cpp can split a model between them. Only a
+    // model that cannot load at all is turned away here; a model that fits only this way runs mostly on the CPU.
     budgetBytes: z.number().int().nonnegative(),
+    // What a model may take and still run at full speed: the free memory of one device (fullSpeedDevice), plus whatever
+    // this sandbox's own local model holds there now, since a start stops it first. Both offers are sized against this,
+    // never against the sum. Zero means unmeasurable. Absent from a daemon older than the distinction.
+    fullSpeedBytes: z.number().int().nonnegative().optional(),
+    fullSpeedDevice: LocalModelDeviceSchema.optional(),
     // Whether llama-server is in this image. False means the local lane costs a rebuild before it can serve anything.
     serverReady: z.boolean(),
     options: z.array(LocalModelOptionFitSchema),
     // The two the connect view offers by name. Each is a model plus the window it was priced at, ready to be added
-    // verbatim; absent where nothing on the list fits this machine, which is an answer, not an error.
+    // verbatim, and each runs at full speed; absent where nothing on the list does, which is an answer, not an error.
     instant: z.object({ model: z.string(), context: z.string() }).optional(),
     best: z.object({ model: z.string(), context: z.string() }).optional(),
     prefetch: LocalModelPrefetchSchema,
@@ -114,7 +130,7 @@ export const endpointsContract = {
             path: "/endpoints/local-model/fit",
             summary: "Which local models this machine can actually run",
             description:
-                "The memory this sandbox may use, whether a GPU reached it, and every curated model priced against both, plus the two the connect view offers: one that downloads in a minute and one that is the best this machine can hold. Nothing here is a preference; it is what a start would be admitted or refused on.",
+                "The memory this sandbox may use, whether a GPU reached it, and every curated model priced two ways: whether it fits on one device's free memory and so runs at full speed, and whether it can load at all. The two the connect view offers, one that downloads in a minute and the best this machine runs at full speed, come from the first; a start is refused only on the second.",
         })
         .output(LocalModelFitSchema),
     // Start or stop fetching the instant model's weights before anyone has asked for them, so the first local turn does

package/src/contracts/secrets.contract.ts

@@ -9,6 +9,9 @@ import {
     SecretKeyParamSchema,
     SecretGeneratedSchema,
     SecretGenerateSchema,
+    SecretHostGuardSetResultSchema,
+    SecretHostGuardSetSchema,
+    SecretHostGuardsSchema,
     SecretKeysSchema,
     SecretRevealSchema,
     SecretSetSchema,
@@ -113,6 +116,31 @@ export const secretsContract = {
         })
         .input(CredentialGuardSubjectParamSchema)
         .output(OkSchema),
+    // The host guard, the gate's second half: kept beside the gates, off the agent-editable config for the same reason. The
+    // agent reads it so a use can aim where it may go, and may tighten it; loosening waits for the owner's click.
+    hosts: secretRoute
+        .route({
+            method: "GET",
+            path: "/secrets/hosts",
+            summary: "Which secrets are host-guarded, and where they may go",
+            description:
+                "Every secret and connected account whose host guard is set, on or off, and its hosts. With the guard on, a use aimed off the list, or anywhere a command's text does not show, asks a person first, whatever the safety judge says. Names and hosts only, never values.",
+        })
+        // The `secrets gates` and `secrets hosts` CLI's read, on the agent token.
+        .meta({ agent: true })
+        .output(SecretHostGuardsSchema),
+    setHosts: secretRoute
+        .route({
+            method: "PUT",
+            path: "/secrets/hosts/{subject}",
+            summary: "Turn a secret's host guard on or off, and set its hosts",
+            description:
+                "Replaces one secret's host guard. Anybody who may use secrets can turn it on or take hosts away; turning it off or adding a host is the owner's: from the agent it raises a card for the owner in the live conversation and waits for their answer.",
+        })
+        // The `secrets hosts` CLI's edits, on the agent token; the route itself decides what needs the owner.
+        .meta({ agent: true })
+        .input(SecretHostGuardSetSchema)
+        .output(SecretHostGuardSetResultSchema),
     request: secretRoute
         .route({
             method: "POST",

package/src/contracts/settings.contract.ts

@@ -1,7 +1,10 @@
 import { FIELD_NOTES_FILE } from "@intentic/constants";
 import { procedure } from "../protocol/route-meta.js";
 import {
+    AudienceAnswerSchema,
+    AudienceStateSchema,
     BuiltinPromptSchema,
+    MemberAudienceSchema,
     BuiltinPromptTextSchema,
     FieldNotesStatusSchema,
     REPO_CHECKS_FILE,
@@ -103,6 +106,32 @@ export const settingsContract = {
         })
         .input(TimezoneOfferSchema)
         .output(TimezoneStateSchema),
+    // A person's own preference rather than a sandbox setting: kept per member, so every device a person opens this
+    // sandbox on reads it, and nobody's answer changes another member's screen. Anyone signed in may read and give their
+    // own, a guest included, since it changes nothing but the words they are shown.
+    audience: procedure
+        .route({
+            method: "GET",
+            path: "/settings/audience",
+            summary: "Which words the editor uses for you here",
+            description:
+                "Whether your editor speaks git's own words (developer) or plain ones (maker) on this sandbox, in every browser and on every device. Absent until you have chosen here.",
+        })
+        .meta({ guest: true })
+        .output(MemberAudienceSchema),
+    // A browser handing over the answer it kept on its own must not overwrite one the person already gave on another
+    // device, which is what `offer` says; a plain answer replaces it.
+    setAudience: procedure
+        .route({
+            method: "POST",
+            path: "/settings/audience",
+            summary: "Choose which words the editor uses for you here",
+            description:
+                "Sets whether your editor speaks git's own words (developer) or plain ones (maker) on this sandbox, for every browser and device you open it on. Other members keep their own. With `offer` it is taken only while you have none kept, and the kept answer comes back unchanged.",
+        })
+        .meta({ guest: true, floor: "viewer" })
+        .input(AudienceAnswerSchema)
+        .output(AudienceStateSchema),
     adoptRepoChecks: procedure
         .route({
             method: "POST",

package/src/contracts/system.contract.ts

@@ -1,7 +1,6 @@
 import { procedure } from "../protocol/route-meta.js";
 import { streamOf } from "../protocol/routes.js";
 import { z } from "zod";
-import { SessionTranscriptSchema } from "../events/transcript.js";
 import { SystemEventSchema } from "../events/system-events.js";
 import {
     DeviceAgentFlowInputSchema,
@@ -19,7 +18,6 @@ import { SkipUpdateInputSchema } from "../schemas/updates.js";
 import {
     BrowserNameParamSchema,
     BrowsersListSchema,
-    SubagentIdParamSchema,
     SubagentsListSchema,
     TerminalNameParamSchema,
     TerminalScrollbackQuerySchema,
@@ -228,26 +226,19 @@ export const systemContract = {
         })
         .input(BrowserNameParamSchema)
         .output(OkSchema),
-    // SDK subagents and delegated runs alike; watched via transcript, not a socket, live then from stored history.
+    // In-process and spawned alike: the board draws each under the card of the conversation that started it, and a chat
+    // draws it on the card of the call that started it. Pushed through the `subagents` runtime domain, never polled. A
+    // subagent's work is read where it lives: an in-process one's on its delegation's card in its parent's record, a
+    // spawned one's in its own conversation (agents.transcript), so there is no second transcript door here.
     subagents: systemRoute
         .route({
             method: "GET",
             path: "/system/subagents",
             summary: "Subagents the agents have started",
             description:
-                "Every subagent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.",
+                "Every subagent that conversations the caller can see have delegated work to, whichever tool started it, with what each one is doing: all that are still working, and the most recent that have settled.",
         })
         .output(SubagentsListSchema),
-    subagentTranscript: systemRoute
-        .route({
-            method: "GET",
-            path: "/system/subagents/{id}/transcript",
-            summary: "A subagent's record",
-            description:
-                "The full record of one delegated subagent, in the same shape as any other conversation. It comes live from the parent turn while it works, and from stored history once it has finished.",
-        })
-        .input(SubagentIdParamSchema)
-        .output(SessionTranscriptSchema),
     // On the contract, not a hand-written route beside it: this payload is what every "do it out there" button is
     // gated on, so its shape has to be fingerprinted like any other, or a daemon older than the app disagrees about
     // it silently and the buttons just stop being drawn.

package/src/contracts/translator.contract.ts

@@ -12,7 +12,8 @@ import { OkSchema } from "../schemas/shared.js";
 //
 // Two login shapes ride one pair of routes. Codex, Grok and Kimi use device authorization: the translator polls
 // to completion in the background, so the UI polls the attempt. Google redirects the browser to a loopback
-// URL this sandbox can't receive, so `complete` hands the landing URL to the translator. `connect.flow` tells the
+// URL this sandbox can't receive: a device or browser of the owner's catches it where one can (`connect.catchers`),
+// otherwise `complete` takes the landing URL pasted back; either way it reaches the translator the same way. `connect.flow` tells the
 // card which mechanic it received without inferring it from whether an optional device code happened to exist.
 export const translatorContract = {
     accounts: procedure

package/src/contracts/webext.contract.ts

@@ -2,6 +2,8 @@ import { oc } from "@orpc/contract";
 // Named imports rather than the `z` namespace: this module is bundled into the browser extension, where the
 // namespace keeps zod's 60 locales (~250 kB) that esbuild can otherwise drop. _devices/webext/scripts/size-budget.mjs holds the ceiling.
 import { unknown } from "zod";
+import { streamOf } from "../protocol/stream-of.js";
+import { LoopbackCatchEventSchema, LoopbackCatchSchema } from "../schemas/loopback-catch.js";
 import { OkSchema } from "../schemas/shared.js";
 import { WebExtFactsSchema, WebExtScopesSchema } from "../schemas/webext.js";
 
@@ -9,7 +11,8 @@ import { WebExtFactsSchema, WebExtScopesSchema } from "../schemas/webext.js";
 // inverted from device.contract.ts, since a browser cannot be dialled.
 // `mcp` stays one opaque procedure so a browser can gain a tool without a matching daemon release; the payload is
 // validated in the extension against the tool's own schema.
-// No `runSandboxFlow` twin: every browser operation is a click or read that either happened or did not.
+// No `runSandboxFlow` twin: every browser operation is a click or read that either happened or did not. The one stream
+// is `catchLoopback`, the device agent's own procedure answered the same way, so the daemon drives both alike.
 export const webextContract = {
     // Refetched on connect and each card read, never cached: the grant list changes in the browser, not here.
     describe: oc.output(WebExtFactsSchema),
@@ -19,4 +22,7 @@ export const webextContract = {
     ping: oc.output(OkSchema),
     // One MCP JSON-RPC message forwarded verbatim in both directions; kept opaque, not typed per tool.
     mcp: oc.input(unknown()).output(unknown()),
+    // Watches for a tab reaching one loopback address, a sign-in's redirect (schemas/loopback-catch.ts); armed by the
+    // daemon only, and sent only to a browser whose facts list `loopback-catch`.
+    catchLoopback: oc.input(LoopbackCatchSchema).output(streamOf(LoopbackCatchEventSchema)),
 };

package/src/contracts/workspace.contract.ts

@@ -16,13 +16,6 @@ import {
     WorkspaceGraphSchema,
     WorkspaceSyncSchema,
 } from "../schemas/workspace/workspace-repos.js";
-import {
-    PushChecksSchema,
-    PushDismissResultSchema,
-    PushDismissSchema,
-    PushRecheckResultSchema,
-    PushRecheckSchema,
-} from "../schemas/workspace/push-checks.js";
 import { WorkspaceSearchQuerySchema, WorkspaceSearchResultSchema } from "../schemas/workspace/workspace-search.js";
 import { WorkspaceInstallResultSchema, WorkspaceInstallSchema, WorkspaceSetupSchema } from "../schemas/workspace/workspace-setup.js";
 import {
@@ -283,36 +276,6 @@ export const workspaceContract = {
         })
         .input(WorkspaceInstallSchema)
         .output(WorkspaceInstallResultSchema),
-    // What the pre-push hook found and let through waits here until measured gone or dismissed; with the two hands on it.
-    pushChecks: procedure
-        .route({
-            method: "GET",
-            path: "/workspace/push-checks",
-            summary: "What pushes left behind",
-            description:
-                "Every push the pre-push hook measured, newest first, with what each brought in, and what is still owed per project. The hook never refuses a push, so this is where its findings wait. Nothing here is ever sent to an agent by itself.",
-        })
-        .output(PushChecksSchema),
-    pushDismiss: procedure
-        .route({
-            method: "POST",
-            path: "/workspace/push-checks/dismiss",
-            summary: "Set aside what a push left behind",
-            description:
-                "Marks findings a push check let through as not to be fixed, so they stop counting against the project, or opens dismissed ones again. Nothing is changed in the code.",
-        })
-        .input(PushDismissSchema)
-        .output(PushDismissResultSchema),
-    pushRecheck: procedure
-        .route({
-            method: "POST",
-            path: "/workspace/push-checks/recheck",
-            summary: "Measure what a push left behind again",
-            description:
-                "Runs the project's own push measurement over its main tree now and resolves every open finding it no longer prints. A few seconds; nothing is pushed.",
-        })
-        .input(PushRecheckSchema)
-        .output(PushRecheckResultSchema),
     repos: procedure
         .route({
             method: "GET",

package/src/events/agent-events.ts

@@ -38,13 +38,16 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         remote: z.string().optional(),
     }),
     // After a clean isolated turn's delta lands or not: `landed` puts it uncommitted in the main tree, `conflicts`
-    // names paths that failed, `held` means nothing happened. `deps` covers undeclared dependencies.
+    // names paths that failed, `held` means nothing happened. `deps` covers undeclared dependencies. `into` names the
+    // parent conversation a spawned child's work went into instead of the main tree, as an in-process subagent's edits
+    // go into its parent's checkout.
     z.object({
         kind: z.literal("landed"),
         landed: z.boolean(),
         conflicts: z.array(LandConflictSchema).optional(),
         held: z.boolean().optional(),
         deps: z.object({ missing: z.number(), started: z.array(z.string()), deferred: z.boolean() }).optional(),
+        into: z.string().optional(),
     }),
     // Notes the daemon prepends to the user's message before the model reads it, verbatim, one per note. Serialized
     // from the same typed notes the wire prompt uses, so disclosure cannot drift from what the model got.
@@ -180,6 +183,17 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("account_usage"), account: z.string().optional(), windows: z.array(UsageWindowSchema) }),
     ContextUsageSchema.extend({ kind: z.literal("context_usage") }),
     z.object({ kind: z.literal("compact"), trigger: z.string(), preTokens: z.number().optional(), postTokens: z.number().optional() }),
+    // An agent's own project-dependency install was let through the command gate: where it writes, and which projects
+    // it works on, so the chat says so before its output arrives. Said by every runtime the gate stands in front of.
+    z.object({
+        kind: z.literal("install"),
+        reach: z
+            .enum(["own-copy", "main-tree"])
+            .describe("Where it writes: this conversation's own copy of the tree, or the main tree every conversation reads."),
+        projects: z
+            .array(z.string())
+            .describe("The projects it works on, workspace-relative, the workspace root as an empty string; empty when none could be named."),
+    }),
     // The four interactive cards; each parks the turn until `POST /agent/reply` resolves its `requestId`.
     PlanRequestSchema,
     QuestionRequestSchema,
@@ -252,6 +266,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // The model cannot hold a turn this size, refused before sending; retrying the same request never
                 // helps.
                 "context-window-too-small",
+                // The model can only write one-shot jobs (Model.helperOnly: its server says it cannot call tools, or
+                // it is the quick-jobs local model), refused before sending; the words wait for another model.
+                "model-helper-only",
                 // The session outgrew the model's context window mid-turn; resuming that session only overflows again,
                 // so the daemon re-runs the turn once in a fresh session carrying the hand-off.
                 "context-overflow",

package/src/events/agent-words.ts

@@ -44,6 +44,9 @@ export interface ChildReportFields {
     readonly report: string;
     // Undefined when nothing of the child's work was seen, which is not a verdict.
     readonly verification: SubagentVerification | undefined;
+    // Where its work went, in the daemon's words: into the parent's own checkout, or held off it by a clash. Undefined
+    // for a child whose work lands as any conversation's does.
+    readonly landing?: string | undefined;
 }
 
 // The wait tool's `verification` field, in words.
@@ -73,7 +76,7 @@ export const childReportPrompt = (fields: ChildReportFields): string => {
         "",
         fields.report.trim() === "" ? "(It ended without a closing report.)" : fields.report.trim(),
         "",
-        "Its changes are in its own worktree and land the way any agent's do. Its account of its own work is a claim, not " +
+        `${fields.landing ?? "Its changes are in its own worktree and land the way any agent's do."} Its account of its own work is a claim, not ` +
             "a result: check what matters before you build on it, and follow up with the subagents tools as you would mid-turn.",
     ].join("\n");
 };

package/src/events/land-breakage.ts

@@ -1,8 +1,7 @@
-// The follow-ups the daemon USED to send when the check it ran after every land went red: back to the conversation
+// The follow-ups the daemon USED to send when the check it ran after every land failed: back to the conversation
 // that landed the work, or to a fresh conversation started on it. Nothing sends either any more: nothing checks work
-// after it lands, CI checks what the owner pushes (schemas/workspace/push-checks.ts). They stay on the wire because
-// records already hold them, and the chat has to go on recognising them: a prompt nobody typed must not reach a reader
-// as their own words.
+// after it lands, CI checks what the owner pushes (schemas/ci.ts). They stay on the wire because records already hold
+// them, and the chat has to go on recognising them: a prompt nobody typed must not reach a reader as their own words.
 
 // Anchored on by the chat, so it must stay unique and stable across releases.
 export const LAND_BREAKAGE_OPENING =

package/src/events/resume.test.ts

@@ -1,4 +1,4 @@
-import { RESUME_NOTES, resumeDisclosure, withResumeNote, withoutResumeNote } from "./resume.js";
+import { RESUME_NOTES, resumeDisclosure, resumeNoticeRow, withResumeNote, withoutResumeNote } from "./resume.js";
 
 // Wrapping then unwrapping a resume note must return the exact original prompt; a mismatch leaks machine narration into
 // the user's own words on screen.
@@ -46,7 +46,7 @@ test("the spent-allowance notes do not disclose as each other", () => {
 test("a turn the door turned away discloses as its own notice, apart from the allowance's refusal", () => {
     const door = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.door));
     const refused = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.refused));
-    expect(door).toEqual({ kind: "notice", text: expect.stringContaining("turned away") });
+    expect(door).toEqual({ kind: "notice", text: expect.stringContaining("turned away"), reason: "door" });
     expect(door).not.toEqual(refused);
 });
 
@@ -60,5 +60,16 @@ test("a re-run after the window overflowed discloses as its own notice", () => {
     expect(resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.overflow))).toEqual({
         kind: "notice",
         text: "Sent again in a fresh session after the last one outgrew the model's context window.",
+        reason: "overflow",
+    });
+});
+
+// The row keeps the English line, and names the re-run so an app can say it in its reader's language.
+test("a re-run's notice row names its reason beside its words", () => {
+    const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.restart));
+    expect(disclosure?.kind === "notice" ? resumeNoticeRow(disclosure) : undefined).toEqual({
+        role: "notice",
+        text: "The sandbox came back, this turn picked up where it left off.",
+        noticeCode: { code: "resumed", params: { reason: "restart" } },
     });
 });

package/src/events/resume.ts

@@ -1,4 +1,5 @@
-import type { TurnNote } from "./transcript.js";
+import { noticeCode, type ResumeNoticeReason } from "./sandbox-notice.js";
+import type { TranscriptRow, TurnNote } from "./transcript.js";
 
 // What a resumed turn's prompt says happened; lives on the wire since the client must recognise it too.
 
@@ -46,23 +47,35 @@ export type ResumeReason = keyof typeof RESUME_NOTES;
 
 // How a resumed turn's interruption reads to a person: `notice` for the whole-turn re-runs, a muted line with the
 // repeat dropped; `note` for the answered case, the user's real answer disclosed normally.
-export type ResumeDisclosure = { readonly kind: "notice"; readonly text: string } | { readonly kind: "note"; readonly note: TurnNote };
+// A notice names its reason too, so the row it becomes can say it in the reader's language (sandbox-notice.ts).
+export type ResumeDisclosure =
+    | { readonly kind: "notice"; readonly text: string; readonly reason: ResumeNoticeReason }
+    | { readonly kind: "note"; readonly note: TurnNote };
+
+const notice = (reason: ResumeNoticeReason, text: string): ResumeDisclosure => ({ kind: "notice", text, reason });
 
 const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
-    auth: { kind: "notice", text: "Claude sign-in renewed, this turn picked up where it left off." },
-    outage: { kind: "notice", text: "The model provider came back, this turn picked up where it left off." },
-    restart: { kind: "notice", text: "The sandbox came back, this turn picked up where it left off." },
-    stopped: { kind: "notice", text: "Sent again after the turn stopped short, picking up where it left off." },
+    auth: notice("auth", "Claude sign-in renewed, this turn picked up where it left off."),
+    outage: notice("outage", "The model provider came back, this turn picked up where it left off."),
+    restart: notice("restart", "The sandbox came back, this turn picked up where it left off."),
+    stopped: notice("stopped", "Sent again after the turn stopped short, picking up where it left off."),
     // None of these four auto-resumed, a person pressed Continue; `switched`/`carried` name the differing account.
-    limit: { kind: "notice", text: "Sent again after the allowance ran out mid-turn, picking up where it left off." },
-    switched: { kind: "notice", text: "Sent again on the switched account after the allowance ran out mid-turn, in a fresh session." },
-    carried: { kind: "notice", text: "Sent again on the switched account after the allowance ran out mid-turn, carrying the session with it." },
-    refused: { kind: "notice", text: "Sent again after the allowance refused it: nothing had run." },
-    door: { kind: "notice", text: "Sent again: the first attempt was turned away before anything ran." },
-    overflow: { kind: "notice", text: "Sent again in a fresh session after the last one outgrew the model's context window." },
+    limit: notice("limit", "Sent again after the allowance ran out mid-turn, picking up where it left off."),
+    switched: notice("switched", "Sent again on the switched account after the allowance ran out mid-turn, in a fresh session."),
+    carried: notice("carried", "Sent again on the switched account after the allowance ran out mid-turn, carrying the session with it."),
+    refused: notice("refused", "Sent again after the allowance refused it: nothing had run."),
+    door: notice("door", "Sent again: the first attempt was turned away before anything ran."),
+    overflow: notice("overflow", "Sent again in a fresh session after the last one outgrew the model's context window."),
     answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
 };
 
+/** The row a whole-turn re-run stands in for its repeated words with, wherever a reader restores one. */
+export const resumeNoticeRow = (resume: Extract<ResumeDisclosure, { kind: "notice" }>): TranscriptRow => ({
+    role: "notice",
+    text: resume.text,
+    noticeCode: noticeCode({ code: "resumed", params: { reason: resume.reason } }),
+});
+
 // What a stored prompt's resume note should be shown as; undefined when the prompt isn't a resume, so any reader can
 // ask without checking first.
 export const resumeDisclosure = (prompt: string): ResumeDisclosure | undefined => {

package/src/events/sandbox-notice.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+// The sandbox's own notice rows (a land, a hold, a renewal, a stop), as a code and the facts they were worded from. The
+// row's `text` stays the English sentence, which older apps, stored transcripts and agents reading their own history
+// go on reading; `noticeCode` beside it is what lets an app say the same thing in the reader's language and words.
+
+// On the wire a code is any string and its facts a flat record: a transcript page carrying a code newer than its reader
+// still parses, and that reader draws `text`. The codes this build writes, with their facts typed, are
+// SandboxNoticeSchema below.
+export const NoticeCodeSchema = z.object({
+    code: z.string().describe("Which of the sandbox's notices this row is, by name. A reader that does not know the name shows the row's text."),
+    params: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe("The facts the notice was worded from, by name: counts, names, and the provider's own sentence where the notice quotes one."),
+});
+export type NoticeCode = z.infer<typeof NoticeCodeSchema>;
+
+const count = z.number().int().nonnegative();
+
+// A failure's own sentence, which the notice's clause follows: the provider's words, or the sandbox's under `error`, its
+// failure code, for a reader that words a failure it knows itself.
+const failure = {
+    message: z.string(),
+    error: z.string().optional(),
+};
+
+// The re-runs a resumed turn's row can name (events/resume.ts); a reason a reader does not know draws the row's text.
+const ResumeNoticeReasonSchema = z.enum(["auth", "outage", "restart", "stopped", "limit", "switched", "carried", "refused", "door", "overflow"]);
+export type ResumeNoticeReason = z.infer<typeof ResumeNoticeReasonSchema>;
+
+// Every code this build writes, one per sentence shape, each with the facts that shape needs.
+export const SandboxNoticeSchema = z.discriminatedUnion("code", [
+    z.object({ code: z.literal("compacted") }),
+    z.object({ code: z.literal("stopped") }),
+    // The branch was rebased onto `commits` new commits, and/or could not be in the repos named in `blocked`.
+    z.object({ code: z.literal("synced"), params: z.object({ commits: count, blocked: z.string().optional() }) }),
+    z.object({ code: z.literal("intoParent") }),
+    z.object({ code: z.literal("intoParentClash"), params: z.object({ files: count }) }),
+    z.object({ code: z.literal("landHeld") }),
+    z.object({ code: z.literal("landConflict"), params: z.object({ files: count, repos: z.string() }) }),
+    // `deps` dependencies the turn added or changed, installing now, or `queued` behind any other install.
+    z.object({ code: z.literal("landed"), params: z.object({ deps: count.optional(), queued: z.boolean().optional() }).optional() }),
+    z.object({ code: z.literal("retrying"), params: z.object({ ...failure, attempt: count, of: count }) }),
+    z.object({ code: z.literal("retried"), params: z.object({ ...failure, made: count, of: count }) }),
+    z.object({ code: z.literal("outageWaiting"), params: z.object(failure) }),
+    z.object({ code: z.literal("renewing"), params: z.object(failure) }),
+    z.object({ code: z.literal("renewalWithdrawn"), params: z.object(failure) }),
+    z.object({ code: z.literal("reconnect"), params: z.object(failure) }),
+    z.object({ code: z.literal("undelivered"), params: z.object({ ...failure, unattended: z.boolean().optional() }) }),
+    // A turn the sandbox kept whole, its message above; `memory` when a memory hold kept it.
+    z.object({ code: z.literal("kept"), params: z.object({ ...failure, memory: z.boolean().optional() }) }),
+    z.object({ code: z.literal("memoryHeld"), params: z.object(failure) }),
+    // A failure the sandbox names by code and adds nothing to.
+    z.object({ code: z.literal("failed"), params: z.object(failure) }),
+    z.object({ code: z.literal("questionDismissed") }),
+    z.object({ code: z.literal("planApproved") }),
+    z.object({ code: z.literal("keptPlanning") }),
+    // `note` is the agent's own words; `every` the interval, already worded ("5m").
+    z.object({ code: z.literal("watching"), params: z.object({ note: z.string(), every: z.string() }) }),
+    z.object({ code: z.literal("restartInterrupted") }),
+    // A turn that picked up a conversation the sandbox kept warm: `tokens` read from the cache ("305k"), or for
+    // keptCold sent again, after `span` ("2h 5m") and `refreshes` refreshes.
+    z.object({ code: z.literal("keptWarm"), params: z.object({ tokens: z.string(), span: z.string(), refreshes: count }) }),
+    z.object({ code: z.literal("keptCold"), params: z.object({ tokens: z.string(), span: z.string(), refreshes: count }) }),
+    // A turn sent thin for a small window ("16k"): what was left out, and whether the base instructions were swapped too.
+    z.object({ code: z.literal("contextTrim"), params: z.object({ window: z.string(), omitted: z.string().optional(), base: z.boolean() }) }),
+    z.object({ code: z.literal("resumed"), params: z.object({ reason: ResumeNoticeReasonSchema }) }),
+    // An agent's own dependency install starting: into its conversation's own copy (`ownCopy`) or the main tree; the
+    // workspace root (`root`) and up to three project folders named (`projects`, each with its slash, already joined),
+    // and how many `more` were not named.
+    z.object({
+        code: z.literal("installing"),
+        params: z.object({ ownCopy: z.boolean(), root: z.boolean().optional(), projects: z.string().optional(), more: count.optional() }),
+    }),
+]);
+export type SandboxNotice = z.infer<typeof SandboxNoticeSchema>;
+
+/** The wire form of one of this build's notices, facts nobody gave left off rather than sent as nothing. */
+export const noticeCode = (notice: SandboxNotice): NoticeCode => {
+    if (!("params" in notice) || notice.params === undefined) {
+        return { code: notice.code };
+    }
+    const params = Object.fromEntries(
+        Object.entries(notice.params).filter((entry): entry is [string, string | number | boolean] => entry[1] !== undefined),
+    );
+    return Object.keys(params).length === 0 ? { code: notice.code } : { code: notice.code, params };
+};
+
+/** One of this build's notices, read off a row; undefined for a row without one, or with a code or facts this build does not know. */
+export const sandboxNoticeOf = (row: { readonly noticeCode?: NoticeCode | undefined }): SandboxNotice | undefined =>
+    row.noticeCode === undefined ? undefined : SandboxNoticeSchema.safeParse(row.noticeCode).data;

package/src/events/system-events.ts

@@ -53,6 +53,13 @@ export const HelloSchema = z.object({
     shapes: z.record(z.string(), z.string()).optional(),
     build: z.string().optional(),
     boot: BootProgressSchema.optional(),
+    // A project sandbox's folder, workspace-relative (`my-app` for /work/my-app): the owner's own folder, synced live
+    // with their computer, which the browser scopes the workspace to on arrival. Absent on every other sandbox.
+    projectDir: z.string().optional(),
+    // What answers: a sandbox's daemon, or the desktop app's sidecar serving a folder on the user's own computer
+    // (_devices/local-files), whose `routes` are the few a folder has rather than a daemon's missing ones. Absent reads
+    // as a sandbox, which every daemon before this field was.
+    surface: z.enum(["sandbox", "folder"]).optional(),
 });
 export type Hello = z.infer<typeof HelloSchema>;
 

package/src/events/transcript.ts

@@ -5,6 +5,7 @@ import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
 import { NeedSchema } from "../schemas/needs.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
+import { NoticeCodeSchema } from "./sandbox-notice.js";
 import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind} from "./requests.js";
 import { browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, credentialOfferRequest, CredentialReceiptSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionAskSchema, permissionRequest, planRequest, questionRequest, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
 
@@ -105,7 +106,7 @@ export const TranscriptSubagentSchema = z.object({
         .string()
         .optional()
         .describe(
-            "Its own id, where that is not the card's: a spawned subagent is named by its own conversation, which is what the roster, `wait` and its page call it. Absent, the card's id is its id, as it is for one the runtime started in-process.",
+            "Its own id, where that is not the card's: a spawned subagent is named by its own conversation, which is what the roster, `wait` and its own chat call it. Absent, the card's id is its id, as it is for one the runtime started in-process.",
         ),
     kind: SubagentKindSchema,
     agentType: z.string().optional(),
@@ -300,6 +301,11 @@ export const TranscriptRowSchema = z.object({
         .string()
         .optional()
         .describe("Which instance of the wait this notice names, for a kind that can have several running at once."),
+    // The sandbox's own notice by name, beside its English `text` (sandbox-notice.ts); absent on every other row, and
+    // on the notices written before rows carried it, which a reader draws from `text` as it always did.
+    noticeCode: NoticeCodeSchema.optional().describe(
+        "Which of the sandbox's own notices this row is, and the facts it was worded from, so a reader can say it in the reader's own language. The text stays the English sentence.",
+    ),
     // At most one card per row; a card closes its bubble. One field per kind, so a reader reaches it by name.
     plan: TranscriptPlanSchema.optional().describe("The plan this row asked approval for, and the answer."),
     question: TranscriptQuestionSchema.optional().describe("The questions this row asked, and the picks that answered them."),

package/src/events/verify-nudge.ts

@@ -1,7 +1,7 @@
 // The follow-up the daemon USED to send when a turn ended with work it could not confirm. Nothing sends it any more:
-// nothing checks inside a conversation, CI checks what the owner pushes (schemas/workspace/push-checks.ts). It stays on
-// the wire because records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not
-// reach a reader as their own words.
+// nothing checks inside a conversation, CI checks what the owner pushes (schemas/ci.ts). It stays on the wire because
+// records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not reach a reader as
+// their own words.
 
 // Anchored on by the reader, so it must stay unique and stable across releases — a reworded opening un-recognises every
 // nudge already in a record, and they read as the user's own typing again.