@intentic/sandbox-contract 1.318.0 → 1.320.0

package/src/front/generated/browser-wire.ts

@@ -5,6 +5,42 @@
  */
 export type EdgeVerdict = "no-tunnel" | "unknown-sandbox" | "dropped";
 
+/**
+ * Where the front's control link to Node stands.
+ */
+export type NodeLink = "starting" | "up" | "restarting";
+
+/**
+ * The share of the last 10 seconds, as a percentage, in which some of the container's tasks stalled waiting for each
+ * resource: cgroup v2's `some avg10` from `cpu.pressure`, `memory.pressure` and `io.pressure`.
+ */
+export type Pressure = { cpu: number, memory: number, io: number, };
+
+/**
+ * The sandbox's proof of life, measured by the front and answered by it at [`VITALS_PATH`] whatever state Node is in:
+ * the daemon's own heartbeat rides Node's event loop, so a sandbox busy enough to starve it would otherwise look dead.
+ * It carries nothing of the workspace.
+ */
+export type SandboxVitals = { node: NodeLink, 
+/**
+ * How long Node's event loop takes to answer the front, in milliseconds: the round trip of the last ping it
+ * answered, or how long the one outstanding has waited when that is longer. The front pings every 2 s, only once
+ * the previous ping is answered. Null before the first ping, and while Node is not `up`.
+ */
+lagMs: number | null, 
+/**
+ * How many times the front restarted Node in the last 10 minutes.
+ */
+restarts: number, 
+/**
+ * Seconds since the front, and so the container, started.
+ */
+uptimeS: number, 
+/**
+ * The container's pressure stall; null where the cgroup's pressure files cannot be read.
+ */
+pressure: Pressure | null, };
+
 /**
  * What the browser sends on a terminal socket, each a JSON text message.
  */

package/src/front/generated/front-wire.json

@@ -50,6 +50,18 @@
               "plan"
             ],
             "type": "object"
+          },
+          {
+            "properties": {
+              "answer": {
+                "const": "pong",
+                "type": "string"
+              }
+            },
+            "required": [
+              "answer"
+            ],
+            "type": "object"
           }
         ]
       },
@@ -699,6 +711,19 @@
               "query"
             ],
             "type": "object"
+          },
+          {
+            "description": "Whether Node's event loop turns, and how fast: answered `pong` at once, by the link itself. The front sends one\nevery 2 s once the previous one is answered, and reports the round trip as the vitals' lag. An older Node answers\nwith a refusal, or with an answer the front cannot read, and either still counts as answered.",
+            "properties": {
+              "question": {
+                "const": "ping",
+                "type": "string"
+              }
+            },
+            "required": [
+              "question"
+            ],
+            "type": "object"
           }
         ]
       }

package/src/front/generated/wire.ts

@@ -4,7 +4,7 @@ export type Answer = { "answer": "preview", route: PreviewRoute, } | { "answer":
 /**
  * The member whose ticket opened it, lowercased; absent when the daemon runs without auth.
  */
-member?: string, };
+member?: string, } | { "answer": "pong" };
 
 /**
  * A PEM certificate chain and its PEM private key.
@@ -61,7 +61,7 @@ export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "
 /**
  * A question the front asks Node.
  */
-export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, };
+export type Question = { "question": "preview", host: string, probe: boolean, } | { "question": "terminal", query: string, } | { "question": "ping" };
 
 export type Scheme = "http" | "https";
 

package/src/front/wire-manifests.test.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { EDGE_VERDICT_HEADER, edgeVerdictOf } from "../protocol/edge-verdict.js";
 import { INGRESS_GRANT_HEADER, INGRESS_TUNNEL_PATH } from "../protocol/ingress-contract.js";
+import { VITALS_PATH } from "../protocol/vitals.js";
 import { EDGE_TRANSPORTS, TERMINAL_PATH, WEBTRANSPORT_PATH } from "./browser-wire.js";
 import { ASK_PATIENCE_MS, FRAME_LENGTH_BYTES, FRONT_SOCKET_ENV, NODE_SOCKET_ENV } from "./front-wire.js";
 
@@ -23,6 +24,7 @@ const socket = manifest("front-wire") as {
 const browser = manifest("browser-wire") as {
     edge: { verdictHeader: string; verdicts: { oneOf: { const: string }[] } };
     terminal: { path: string; upgrade: string };
+    vitals: { path: string; body: { $defs: { NodeLink: { oneOf: { const: string }[] } } } };
     webTransport: { path: string };
 };
 
@@ -58,4 +60,9 @@ describe("the wire outside oRPC, as the Rust crates define it", () => {
             upgrade: browser.terminal.upgrade,
         });
     });
+
+    it("finds the front's vitals where browser-wire says it answers them, in the states it names", () => {
+        expect(VITALS_PATH).toBe(browser.vitals.path);
+        expect(browser.vitals.body.$defs.NodeLink.oneOf.map((state) => state.const)).toEqual(["starting", "up", "restarting"]);
+    });
 });

package/src/index.ts

@@ -88,6 +88,7 @@ export { issuesContract } from "./contracts/issues.contract.js";
 export { logsContract } from "./contracts/logs.contract.js";
 export { REQUEST_ID_HEADER } from "./protocol/request-id.js";
 export * from "./protocol/edge-verdict.js";
+export * from "./protocol/vitals.js";
 export { loopsContract } from "./contracts/loops.contract.js";
 export { panelsContract } from "./contracts/panels.contract.js";
 export { portsContract } from "./contracts/ports.contract.js";

package/src/policy/secret-hosts.ts

@@ -21,6 +21,7 @@ export const normalizeHostPattern = (raw: string): string | undefined => {
     if (/^[a-z][a-z0-9+.-]*:\/\//.test(text)) {
         try {
             text = new URL(text).hostname;
+            // allow(silent-catch): A malformed URL is refused as a secret host pattern.
         } catch {
             return undefined;
         }

package/src/policy/{batch-runs.test.ts → tests/batch-runs.test.ts}

@@ -14,8 +14,8 @@ import {
     batchRunPrefix,
     batchTurnBody,
     parseBatchFile,
-} from "./batch-runs.js";
-import { ConversationIdSchema } from "../schemas/agent.js";
+} from "../batch-runs.js";
+import { ConversationIdSchema } from "../../schemas/agent.js";
 
 // The two real layouts this fits: one fans out over items, one where a run is the item.
 const FANNED: BatchRunKind = { runsDir: `records/artifacts/acceptance`, prefix: `xt`, scanRuns: 10 };

package/src/policy/{command-classes.test.ts → tests/command-classes.test.ts}

@@ -1,4 +1,4 @@
-import { classifyCommand, type CommandContext, type CommandSpan, matchCommand } from "./command-classes.js";
+import { classifyCommand, type CommandContext, type CommandSpan, matchCommand } from "../command-classes.js";
 
 // Every call states a locus (now required); these default to `device`, the wider reading, so an assertion made here
 // holds at every locus, and genuine differences get their own tests below.

package/src/policy/{command-run.test.ts → tests/command-run.test.ts}

@@ -1,5 +1,5 @@
-import type { CommandRun } from "../schemas/ci.js";
-import { followCommandRun } from "./command-run.js";
+import type { CommandRun } from "../../schemas/ci.js";
+import { followCommandRun } from "../command-run.js";
 
 const RUNNING: CommandRun = { status: "running", command: "pnpm test", output: "" };
 const PASSED: CommandRun = { status: "passed", command: "pnpm test", output: "ok" };

package/src/policy/{credential-material.test.ts → tests/credential-material.test.ts}

@@ -1,4 +1,4 @@
-import { holdsCredentialMaterial, maskCredentialMaterial } from "./credential-material.js";
+import { holdsCredentialMaterial, maskCredentialMaterial } from "../credential-material.js";
 
 // The two directions aren't symmetric: a miss just raises an extra card, a wrong clear un-gates a real credential read.
 // The "no" cases have to be exactly right; every "yes" case is a real file's real shape.

package/src/policy/{fence-paths.test.ts → tests/fence-paths.test.ts}

@@ -1,4 +1,4 @@
-import { fenceAllows, fenceCovers, fenceIntersection, fenceReaches, foldPath, pathInsideFolder } from "./fence-paths.js";
+import { fenceAllows, fenceCovers, fenceIntersection, fenceReaches, foldPath, pathInsideFolder } from "../fence-paths.js";
 
 describe("foldPath", () => {
     test("folds the spellings of one path into one answer", () => {

package/src/policy/{overlay-lint.test.ts → tests/overlay-lint.test.ts}

@@ -1,4 +1,4 @@
-import { hasOfficialBase, invalidExtensionFragment, isOfficialSandboxImage, lintOverlay, overlayBase, rewriteOverlayBase } from "./overlay-lint.js";
+import { hasOfficialBase, invalidExtensionFragment, isOfficialSandboxImage, lintOverlay, overlayBase, rewriteOverlayBase } from "../overlay-lint.js";
 
 test("accepts a RUN/ENV-only fragment, comments and blank lines included", () => {
     const fragment = `# install the postgres client\nRUN apt-get update && apt-get install -y postgresql-client\nENV PGCLIENT=1\n`;

package/src/policy/{owner-ticket.test.ts → tests/owner-ticket.test.ts}

@@ -1,6 +1,6 @@
 import { generateKeyPairSync } from "node:crypto";
-import { mintReachabilityGrant, verifyReachabilityGrant } from "../protocol/ingress-contract.js";
-import { isOwnerTicket, mintOwnerTicket, OWNER_TICKET_TTL_MS, publicKeyPemOf, verifyOwnerTicket } from "./owner-ticket.js";
+import { mintReachabilityGrant, verifyReachabilityGrant } from "../../protocol/ingress-contract.js";
+import { isOwnerTicket, mintOwnerTicket, OWNER_TICKET_TTL_MS, publicKeyPemOf, verifyOwnerTicket } from "../owner-ticket.js";
 
 const pair = generateKeyPairSync("ed25519");
 const privatePem = pair.privateKey.export({ type: "pkcs8", format: "pem" }) as string;

package/src/policy/{persona-home.test.ts → tests/persona-home.test.ts}

@@ -1,4 +1,4 @@
-import { fenceHoldsPersona, personaHome } from "./persona-home.js";
+import { fenceHoldsPersona, personaHome } from "../persona-home.js";
 
 // Where a card lives, and therefore who may wear it. This is the whole of the rule the Access tab draws and the
 // daemon refuses on, so the three shapes a card can name a place in are each pinned here.

package/src/policy/{reserved-servers.test.ts → tests/reserved-servers.test.ts}

@@ -4,7 +4,7 @@ import {
     DAEMON_MCP_SERVERS,
     MCP_SERVER_MINTING_KINDS,
     RESERVED_MCP_SERVER_NAMES,
-} from "./reserved-servers.js";
+} from "../reserved-servers.js";
 
 describe("reserved MCP server names", () => {
     test("the reserved set is exactly the daemon server rows", () => {

package/src/policy/{safety-policy.test.ts → tests/safety-policy.test.ts}

@@ -1,6 +1,6 @@
-import { COMMAND_CLASS_LABELS, COMMAND_CLASS_PATTERNS } from "./command-classes.js";
-import { COMMAND_RULE_CATALOG, DEFAULT_SAFETY_POLICY, hardRuleClasses } from "./safety-policy.js";
-import { CommandClassSchema, CommandLocusSchema } from "../schemas/agent.js";
+import { COMMAND_CLASS_LABELS, COMMAND_CLASS_PATTERNS } from "../command-classes.js";
+import { COMMAND_RULE_CATALOG, DEFAULT_SAFETY_POLICY, hardRuleClasses } from "../safety-policy.js";
+import { CommandClassSchema, CommandLocusSchema } from "../../schemas/agent.js";
 
 // The hard rule is the one thing on this page nobody can argue with, so it's pinned here rather than trusted to review:
 // a class added silently is one an owner can never decide about for themselves.

package/src/policy/{search-globs.test.ts → tests/search-globs.test.ts}

@@ -1,4 +1,4 @@
-import { includeGlobs } from "./search-globs.js";
+import { includeGlobs } from "../search-globs.js";
 
 test("an empty field scopes nothing", () => {
     expect(includeGlobs(undefined)).toEqual({ globs: [], notGlobs: [] });

package/src/policy/{secret-hosts.test.ts → tests/secret-hosts.test.ts}

@@ -1,4 +1,4 @@
-import { hostAllowed, hostMatches, normalizeHost, normalizeHostPattern, tightensHostGuard } from "./secret-hosts.js";
+import { hostAllowed, hostMatches, normalizeHost, normalizeHostPattern, tightensHostGuard } from "../secret-hosts.js";
 
 // The pattern a person writes against the host a use would reach. Every boundary a limit turns on is pinned by value:
 // the apex a wildcard leaves out, the look-alike that only shares a suffix, and which edits take hosts away.

package/src/protocol/raw-routes.ts

@@ -28,6 +28,9 @@ export const RAW_ROUTES = {
     "POST /system/ws-ticket": { beforeBoot: true, floor: "collaborator", control: "never" },
     // A WebSocket upgrade carries no Authorization header; the terminal and both browser wires check a query ticket.
     "GET /system/terminal": { auth: "door", beforeBoot: true, control: "never", front: true },
+    // The front's proof of life (vitals.ts): no credential and nothing of the workspace, readable by any origin, answered
+    // whatever state the daemon is in.
+    "GET /system/vitals": { auth: "door", beforeBoot: true, front: true },
     // Desktop sync's byte pipe, guarded again by sshd's own key check against the same enrollment.
     "GET /system/sync/ssh": { sync: "pipe", control: "never", lane: "bulk" },
     "GET /system/browser-profile": { auth: "door", beforeBoot: true, control: "never" },

package/src/protocol/vitals.test.ts

@@ -0,0 +1,46 @@
+import { RAW_ROUTES, rawRoutePath } from "./raw-routes.js";
+import { parseVitals, type SandboxVitals, VITALS_PATH } from "./vitals.js";
+
+// The JSON browser-wire's own test pins (`vitals_are_the_camel_case_json_the_editor_parses_with_null_for_what_is_unknown`):
+// what the front writes, the editor reads.
+const RUST_GOLDEN_JSON = `{"node":"restarting","lagMs":null,"restarts":2,"uptimeS":3600,"pressure":{"cpu":12.34,"memory":0.0,"io":1.5}}`;
+
+const up: SandboxVitals = { node: "up", lagMs: 12, restarts: 0, uptimeS: 60, pressure: { cpu: 0.29, memory: 0.49, io: 0.88 } };
+
+it("reads the front's own answer as it writes it", () => {
+    expect(parseVitals(JSON.parse(RUST_GOLDEN_JSON))).toEqual({
+        node: "restarting",
+        lagMs: null,
+        restarts: 2,
+        uptimeS: 3600,
+        pressure: { cpu: 12.34, memory: 0, io: 1.5 },
+    });
+    expect(parseVitals(up)).toEqual(up);
+    expect(parseVitals({ ...up, node: "starting" })?.node).toBe("starting");
+});
+
+it("reads a lag or pressure it cannot make out as unknown, and keeps the rest", () => {
+    const { lagMs: _lag, pressure: _pressure, ...bare } = up;
+    expect(parseVitals(bare)).toEqual({ ...bare, lagMs: null, pressure: null });
+    expect(parseVitals({ ...up, lagMs: -1, pressure: { cpu: 1 } })).toEqual({ ...up, lagMs: null, pressure: null });
+    // A later front's extra fields are not this reader's business.
+    expect(parseVitals({ ...up, since: "later" })).toEqual(up);
+});
+
+it("is undefined for anything that is not the front's answer", () => {
+    // An older sandbox forwards the path to Node, which answers 404 as JSON, or a preview's HTML page.
+    expect(parseVitals({ error: "Not Found" })).toBeUndefined();
+    expect(parseVitals("<!doctype html><title>Not found</title>")).toBeUndefined();
+    expect(parseVitals(null)).toBeUndefined();
+    expect(parseVitals(42)).toBeUndefined();
+    expect(parseVitals([up])).toBeUndefined();
+    expect(parseVitals({ ...up, node: "crashed" })).toBeUndefined();
+    expect(parseVitals({ ...up, restarts: -1 })).toBeUndefined();
+    expect(parseVitals({ ...up, uptimeS: 1.5 })).toBeUndefined();
+    expect(parseVitals({ ...up, restarts: "2" })).toBeUndefined();
+});
+
+it("is a route the front serves itself, with no credential, before the daemon boots", () => {
+    expect(rawRoutePath("GET /system/vitals")).toBe(VITALS_PATH);
+    expect(RAW_ROUTES["GET /system/vitals"]).toEqual({ auth: "door", beforeBoot: true, front: true });
+});

package/src/protocol/vitals.ts

@@ -0,0 +1,38 @@
+// The sandbox's proof of life, which intentic-front answers itself on the daemon's own address and never forwards to
+// Node: whether Node is up, how long its event loop takes to answer the front's ping, how often the front restarted it,
+// how long the container has run, and its pressure stall. The daemon's heartbeat on /events rides Node's event loop,
+// so a busy sandbox and a dead one look alike from there; this route tells them apart. The Rust crate `browser-wire`
+// is the definition (SandboxVitals), and wire-manifests.test.ts holds the path here to the manifest it writes.
+
+import { z } from "zod";
+import type { NodeLink, Pressure, SandboxVitals } from "../front/generated/browser-wire.js";
+
+export type { NodeLink, Pressure, SandboxVitals };
+
+// A plain GET any origin may read, answered by the front whatever state Node is in. The route is registered as
+// `front: true` in raw-routes.ts, so the daemon serves none.
+export const VITALS_PATH = "/system/vitals";
+
+// Every state, so a new one in the Rust enum fails this file's typecheck until it is read here too.
+const NODE_LINKS = { starting: "starting", up: "up", restarting: "restarting" } as const satisfies { readonly [K in NodeLink]: K };
+
+const PressureSchema = z.object({ cpu: z.number(), memory: z.number(), io: z.number() });
+
+// Lenient where a figure is only a detail: a lag or a pressure it cannot read is unknown, and the rest still stands.
+const VitalsSchema = z.object({
+    node: z.enum(NODE_LINKS),
+    lagMs: z.number().nonnegative().nullable().catch(null),
+    restarts: z.number().int().nonnegative(),
+    uptimeS: z.number().int().nonnegative(),
+    pressure: PressureSchema.nullable().catch(null),
+});
+
+// A response body as `Response.json()` hands it over: any JSON value, not yet known to be the front's answer.
+type JsonBody = string | number | boolean | null | readonly JsonBody[] | { readonly [key: string]: JsonBody };
+
+// The front's answer, or undefined for anything else: an older sandbox forwards the path to Node, which answers 404 or
+// an HTML page, and an edge in between may answer for a box that is not there.
+export const parseVitals = (body: JsonBody): SandboxVitals | undefined => {
+    const parsed = VitalsSchema.safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+};

package/src/schemas/agent.ts

@@ -304,6 +304,16 @@ const AgentTurnFieldsSchema = z.object({
     editorContext: EditorContextSchema.optional().describe(
         'What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.',
     ),
+    // The composer's scheduled send: a person who knows the account is spent books the message for its reopen instead of
+    // sending it into a refusal. Held in the conversation's queue, never started early; the queue's `until` is this.
+    sendAt: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+            "Hold this message until then (epoch milliseconds) instead of starting a turn now, for an allowance you know is spent. It waits in the conversation's queue, where it can be sent early, reworded or removed, and goes by itself at that instant. Ignored when already past, or when a turn is running.",
+        ),
 });
 export const AgentTurnSchema = AgentTurnFieldsSchema
     // An attachment-only send (no text) is legal; an entirely empty turn is not.
@@ -473,7 +483,7 @@ export const QueuedMessageSchema = z.object({
 });
 export type QueuedMessage = z.infer<typeof QueuedMessageSchema>;
 // Why a queue holds its messages rather than letting them go when the conversation is free.
-export const QueuePauseSchema = z.enum(["stopped", "refused"]);
+export const QueuePauseSchema = z.enum(["stopped", "refused", "scheduled"]);
 export type QueuePause = z.infer<typeof QueuePauseSchema>;
 // What waits for a conversation's next turn: messages that arrived while a turn that could not take them ran, and
 // held ones. Conversation state, the same for every window and kept across a restart.
@@ -481,8 +491,12 @@ export const ConversationQueueSchema = z.object({
     items: z.array(QueuedMessageSchema).describe("What waits, in the order it goes out."),
     revision: z.number().int().nonnegative().describe("Moves with every change to the queue, so of two copies the higher is the newer."),
     paused: QueuePauseSchema.optional().describe(
-        "Why nothing goes out by itself: somebody stopped the turn, or the turn these messages started was refused before it ran. Resuming, or sending another message, lets them go.",
+        "Why nothing goes out by itself: somebody stopped the turn, the turn these messages started was refused before it ran, or they were scheduled for later. Resuming lets them go, and so does sending another message unless they are scheduled.",
     ),
+    until: z
+        .number()
+        .optional()
+        .describe("When scheduled messages go out by themselves, in milliseconds. Only on a queue paused as `scheduled`."),
 });
 export type ConversationQueue = z.infer<typeof ConversationQueueSchema>;
 // What resuming a queue did: started a turn with what waited, when nothing else ran.

package/src/schemas/devices.ts

@@ -103,6 +103,10 @@ export const DeviceSandboxOpSchema = z.enum([
     "stop",
     "restart",
     "prepare",
+    // `prepare` under the unattended rules (`ic sandbox prepare --auto`): nobody pressed anything, so low disk is "not
+    // now" and a pinned sandbox or the version it went back from is left alone. What the update card sends by itself
+    // when it opens; sent only to an agent advertising `background-prepare`.
+    "prepare-background",
     "update",
     "rebuild",
     "rollback",

package/src/schemas/git/git.ts

@@ -447,11 +447,21 @@ export const AgentChangesSchema = z.object({
                     .string()
                     .optional()
                     .describe("The branch its copy is standing on. Absent where it stands on no branch at all, which is a state git allows."),
+                carried: z
+                    .boolean()
+                    .optional()
+                    .describe(
+                        "Whether everything the conversation committed there has also been copied onto its own branch, so what is listed here and what a merge brings include it. False where a commit would not copy over cleanly. Absent from a sandbox too old to copy it, which never did.",
+                    ),
+                uncommitted: z
+                    .boolean()
+                    .optional()
+                    .describe("Whether its copy there holds uncommitted changes to tracked files, which no merge brings until they are committed there."),
             }),
         )
         .optional()
         .describe(
-            "Repositories whose copy the conversation left standing on a different branch of its own. What is listed for them is this conversation's branch as it was last left, not what its copy holds now, and anything it has written since went to the other branch.",
+            "Repositories whose copy the conversation left standing on a different branch of its own. What is listed for them is this conversation's own branch, onto which each turn copies what it committed on the other branch unless `carried` says it could not.",
         ),
     // Read off the live copy, so a retired one has none: its scratch went with it.
     scratch: z

package/src/schemas/hosts.ts

@@ -72,12 +72,16 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 //   previous one; advertised only when the agent's `ic sandbox rollback` takes `--to`.
 // - `loopback-catch`: the `catchLoopback` procedure, a sign-in's loopback redirect caught on this machine
 //   (loopback-catch.ts); an agent without it rejects the call as an unknown procedure.
-export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape", "rollback-to", "loopback-catch"]);
+// - `background-prepare`: the `prepare-background` op, the next update downloaded under the unattended rules of the
+//   agent's own timer (`ic sandbox prepare --auto`), which the update card sends when it opens; advertised only when
+//   the agent's `ic sandbox prepare` takes `--auto`.
+export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape", "rollback-to", "loopback-catch", "background-prepare"]);
 export type DeviceFeature = z.infer<typeof DeviceFeatureSchema>;
 export const DEVICE_FEATURE_RESHAPE_LATER: DeviceFeature = "reshape-later";
 export const DEVICE_FEATURE_SET_SHAPE: DeviceFeature = "set-shape";
 export const DEVICE_FEATURE_ROLLBACK_TO: DeviceFeature = "rollback-to";
 export const DEVICE_FEATURE_LOOPBACK_CATCH: DeviceFeature = "loopback-catch";
+export const DEVICE_FEATURE_BACKGROUND_PREPARE: DeviceFeature = "background-prepare";
 // The features an agent advertised that this build knows; an unknown one is a newer agent's and means nothing here.
 export const deviceFeatures = (facts: Pick<DeviceFacts, "features"> | undefined): DeviceFeature[] =>
     (facts?.features ?? []).flatMap((feature) => {

package/src/schemas/settings-history.ts

@@ -85,6 +85,7 @@ export const SETTINGS_HISTORY = [
         "quickModel",
         "resumeAfterLimit",
         "resumeAfterOutage",
+        "sidecars",
         "terseHoldout",
         "terseOutput",
         "testFaultDetection",

package/src/schemas/settings.ts

@@ -372,13 +372,6 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "What share of conversations to run without the brief, so the two can be compared. Whole conversations rather than individual turns, because the brief sits in the prompt for the whole session and withholding it from one turn would not take it back.",
         ),
-    // Only the eager background pass; the `fileq` CLI itself is always on PATH regardless, gated only by its own skill.
-    sidecars: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep an up-to-date markdown rendering of every document, image and audio file in the workspace, made in the background as files land, so the agent reads a pre-derived text instead of paying to parse the file mid-task. Costs background CPU on a document-heavy workspace, so it is a switch rather than a default.",
-        ),
     outputCleaners: z
         .string()
         .default("")
@@ -630,6 +623,7 @@ export const InputSavingsSchema = z.object({
 });
 export type InputSavings = z.infer<typeof InputSavingsSchema>;
 // One arm of a turn-level experiment; mean is per turn, since the two arms never hold the same count.
+// `mean` is over samples capped at both arms' pooled 95th percentile, so one runaway conversation cannot carry an arm.
 export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() });
 // One metric's reading of a turn-level experiment (the two arms, plus the arithmetic over them). `metric` says what
 // `mean`/`deltaPct` count:

package/src/schemas/system.ts

@@ -39,6 +39,26 @@ export const StagedUpdateSchema = z.object({
         .describe("What the downloaded build's first boot would convert in this sandbox's stored files. Absent when no plan could be had, which says nothing either way."),
 });
 export type StagedUpdate = z.infer<typeof StagedUpdateSchema>;
+// A download of the next update running on the machine right now, with how far it has got. `ic sandbox prepare` writes
+// it onto /history while it works (update-preparing.json), refreshing `at` every few seconds, and removes it when it
+// ends, whichever way. Advisory like the staged marker: the daemon passes it on only while `at` is fresh, so a download
+// whose ic was killed is never drawn as one still running.
+// It names no version: only the finished image can say which it is, and asking it costs a container; the card already
+// knows the release it is downloading as `latest`.
+export const PreparingUpdateSchema = z.object({
+    channel: z.string().describe("Which channel it is being taken from."),
+    startedAt: z.number().describe("When the download began, in milliseconds."),
+    at: z.number().describe("When the machine last said it is still working on it, in milliseconds."),
+    // A string rather than an enum, as UpdateOutcome's `verb` is: a newer ic's step must not make an older daemon drop
+    // the whole marker. `download`, `build` and `check` are the ones this build names.
+    phase: z
+        .string()
+        .describe(
+            "What it is doing: download (pulling the new image), build (building this sandbox's environment on it), or check (checking this sandbox's stored files against it).",
+        ),
+    percent: z.number().min(0).max(100).optional().describe("How far through the download it is, from 0 to 100. Absent for a step with no measure of its own."),
+});
+export type PreparingUpdate = z.infer<typeof PreparingUpdateSchema>;
 export const InfoSchema = z.object({
     name: z.string().optional().describe("What this sandbox is called."),
     image: z.string().optional().describe("The image it is running."),
@@ -83,6 +103,11 @@ export const InfoSchema = z.object({
     staged: StagedUpdateSchema.optional().describe(
         "An update already downloaded and built on the machine running this container, waiting only for the restart that applies it. That restart is seconds, where an unprepared update is minutes, which is a different decision entirely. Absent when nothing is waiting.",
     ),
+    // A download running on the host right now (update-preparing.json, written by ic while it prepares); absent when
+    // none is, and when the host stopped refreshing it (PREPARING_FRESH_MS in the daemon).
+    preparing: PreparingUpdateSchema.optional().describe(
+        "A download of the next update running on the machine right now, and how far it has got. Absent when nothing is downloading, or when the machine stopped saying it is.",
+    ),
     // What the host last did about this sandbox's version (update-outcome.json on /history, written by ic); absent
     // when no host has said, which is every hosted sandbox and every host older than the file.
     lastUpdate: UpdateOutcomeSchema.optional().describe(

package/src/schemas/turn-break.ts

@@ -13,6 +13,15 @@ import { z } from "zod";
 export const TurnBreakSchema = z.enum(["limit", "outage", "stopped"]);
 export type TurnBreak = z.infer<typeof TurnBreakSchema>;
 
+// Every ending that leaves a held turn behind: the three above, plus the provider's safety classifier stopping a turn
+// partway. That one has no standing answer and never re-runs by itself: the person picks, each time, between the same
+// model again and another one (2026-09-30, the owner's call over an automatic model switch).
+export const HeldEndingSchema = z.enum([...TurnBreakSchema.options, "flagged"]);
+export type HeldEnding = z.infer<typeof HeldEndingSchema>;
+
+/** Whether this ending takes a standing answer (turn-break policy), which `flagged` never does. */
+export const isTurnBreak = (ending: HeldEnding): ending is TurnBreak => ending !== "flagged";
+
 // `move` implies `resend`: an account with room is tried at once, and the reset appointment stands as its fallback.
 // There is deliberately no "move, else hold" — a reader willing to spend a second account is willing to wait.
 export const LimitPolicySchema = z.enum(["wait", "resend", "move"]);

package/src/schemas/workspace/workspace-tree.ts

@@ -210,29 +210,14 @@ export const WorkspaceDerivedQuerySchema = z.object({
         .min(1)
         .describe("The file you want the text of, as a workspace path. The real file, not its shadow: where the text is kept is this route's business."),
 });
-// Where the background pass stands, workspace-wide. Nothing about a file on disk can say this, and without it an
-// unrendered file and a file queued behind forty others look identical to a reader.
-export const SidecarStatusSchema = z.object({
-    enabled: z.boolean().describe("Whether the background pass is on (the `sidecars` setting). Off means a shadow exists only where someone asked for one."),
-    queued: z.number().describe("Files waiting for a shadow, not counting the batch being rendered right now."),
-    deriving: z
-        .array(z.string())
-        .describe("The files being rendered at this moment, as workspace paths. One batch at a time, because derivation shares the box with the agent it serves."),
-    sweeping: z.boolean().describe("Whether a whole-tree pass is running, which is what a freshly enabled setting or an unlistably large batch triggers."),
-    broken: z.boolean().describe("Whether the `fileq` binary is missing, in which case nothing renders in the background until this sandbox restarts."),
-    shadows: z.number().optional().describe("How many shadows the last whole-tree pass counted. Absent until one has run in this daemon's lifetime."),
-    sweptAt: z.string().optional().describe("When that pass finished, as an ISO timestamp."),
-});
-export type SidecarStatus = z.infer<typeof SidecarStatusSchema>;
-// Where one file stands with that pass, which is the question a reader looking at a missing or stale shadow is
-// actually asking. `idle` means the pass is on and this file is not waiting for anything: what it has is what it gets.
-export const DerivedStateSchema = z.enum(["off", "queued", "deriving", "idle", "broken", "undeliverable"]);
+// Where one file stands, which is the question a reader looking at a missing or stale rendering is actually asking.
+// Nothing renders in the background: a file has text once someone asks for it, and fileq keeps it until the file changes.
+export const DerivedStateSchema = z.enum(["deriving", "idle", "broken", "undeliverable"]);
 export type DerivedState = z.infer<typeof DerivedStateSchema>;
 const DerivedStandingShape = {
     state: DerivedStateSchema.describe(
-        "Where this file stands with the background pass: switched off, waiting its turn, being read right now, settled, or unreachable because the renderer is missing. `undeliverable` is a format nothing here reads.",
+        "Where this file stands: being read right now, settled (what it has is what it gets until someone asks), or unreachable because the renderer is missing. `undeliverable` is a format nothing here reads.",
     ),
-    queue: SidecarStatusSchema.describe("How the background pass as a whole is doing, so a wait can be reported as a queue rather than as nothing happening."),
 };
 export const WorkspaceDerivedPresentSchema = z.object({
     ...DerivedStandingShape,
@@ -257,7 +242,7 @@ export const WorkspaceDerivedPresentSchema = z.object({
 });
 export const WorkspaceDerivedAbsentSchema = z.object({
     ...DerivedStandingShape,
-    present: z.literal(false).describe("There is no derived text for that file. Read `state` before saying so to anyone: absent and queued are different answers."),
+    present: z.literal(false).describe("There is no derived text for that file. Read `state` before saying so to anyone: absent and being read are different answers."),
     path: z.string().describe("The file, as asked for."),
     derivable: z
         .boolean()

package/src/state/history-state.ts

@@ -82,6 +82,8 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "engines/", portability: "derived" },
     // An update the host downloaded and built for this sandbox (`ic sandbox prepare`); about this machine only.
     { path: "update-staged.json", portability: "derived" },
+    // A download the host is running for this sandbox right now (ic rewrites it every few seconds, removes it when done).
+    { path: "update-preparing.json", portability: "derived" },
     // What the host last did about this sandbox's version (ic writes it), the owner's skipped release, and why the
     // last boot could not start (the daemon writes it, the host's probation reads it): all rebuilt by whoever next says.
     { path: "update-outcome.json", portability: "derived" },