@intentic/sandbox-contract 1.312.0 → 1.314.0

package/src/schemas/hosts.ts

@@ -9,9 +9,22 @@ import { z } from "zod";
 export const WslEnvironmentSchema = z.object({ distro: z.string() });
 export type WslEnvironment = z.infer<typeof WslEnvironmentSchema>;
 
+// WHICH PHYSICAL COMPUTER A DOOR IS ON. The machine agent mints this once, at install, and keeps it in its own state
+// (`~/.intentic/machine/machine-id`); a WSL distro's agent is handed its Windows side's, since a distro is an
+// environment of the PC, not a second computer. It is what an enrollment, a sync enrollment and a device row are
+// joined on — never a hostname, which WSL shares between a PC and its distros and a user can rename.
+export const MachineIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/);
+// An id the daemon stands in for a machine that has not said its own yet (an enrollment made before agents reported
+// one): named after the card, so every environment of that card shares it until each reports the real id. Never
+// sent by an agent, and never the join key of two different cards.
+export const derivedMachineId = (card: string): string => `card:${card}`;
+export const isDerivedMachineId = (machineId: string): boolean => machineId.startsWith("card:");
+
 // What a machine reports once at connect (`host.describe`), cached until it reconnects: the skill pack says how to
 // drive Windows, this says which Windows it is.
 export const DeviceFactsSchema = z.object({
+    // The computer this environment is on (MachineIdSchema). Absent from an agent older than the field.
+    machineId: MachineIdSchema.optional(),
     // The OS's own name for itself, e.g. "Windows 11 Pro 24H2".
     os: z.string(),
     arch: z.string(),
@@ -24,8 +37,7 @@ export const DeviceFactsSchema = z.object({
     // Docker engine's size (WSL guest on Windows, Desktop VM on macOS, host on Linux); the ceiling a sandbox's share is
     // bounded by.
     engine: z.object({ memoryBytes: z.number(), cpus: z.number() }).optional(),
-    // OS hostname: the key that joins the doors of one physical machine. Reported by every agent that also reports
-    // `wsl`, so a hostname with no `wsl` beside it is a native install; absent from an agent older than both.
+    // OS hostname, for the owner to read. Not a join key: `machineId` is.
     hostname: z.string().optional(),
     // Present only inside a WSL distro.
     wsl: WslEnvironmentSchema.optional(),
@@ -35,16 +47,38 @@ export const DeviceFactsSchema = z.object({
     // the rest are other sandboxes' addresses, and a sandbox has no business learning its siblings'. Absent from an
     // agent older than this field, which is why "none unreachable" is not the same value as "did not say".
     links: z.object({ total: z.number(), unreachable: z.number(), unreachableSince: z.number().optional() }).optional(),
-    // What this agent understands beyond the ops every agent has, so a caller can refuse up front rather than send a
-    // field an older agent drops without a word. Absent from an agent older than this field: it supports none of them.
+    // Which of the optional ops this agent AND the `ic` it drives implement (DeviceFeatureSchema), for a page to offer
+    // only what works and for the daemon to refuse an op before sending it. Strings on the wire, so a newer agent's
+    // feature never fails an older daemon's read; `deviceFeatures` keeps the ones this build knows. Nothing is
+    // detected by a field's presence any more: the device RPC inputs are strict, and an agent rejects a field it does
+    // not know rather than dropping it.
     features: z.array(z.string()).optional(),
+    // Why the `ic` this agent drives is older than the agent, as one sentence, when fetching the current one failed:
+    // what explains `features` missing what this agent's release has (a stale ic has no logs verb and no `--set`).
+    // Absent when ic is current, and from an agent older than the field.
+    icOutOfDate: z.string().optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 
-// `reshape` with `later`: save the change for the next restart. An agent without it strips `later` from the request and
-// reshapes NOW, restarting the sandbox and interrupting everyone in it, which is why a later-reshape is never sent to one.
-export const DEVICE_FEATURE_RESHAPE_LATER = "reshape-later";
-export const deviceSupports = (facts: Pick<DeviceFacts, "features"> | undefined, feature: string): boolean => facts?.features?.includes(feature) === true;
+// The optional device ops, by what enables them:
+// - `reshape-later`: the old `reshape` op with `later`, saving the change for the next restart. An agent from before it
+//   strips `later` and reshapes NOW, which is why a later-reshape is never sent to one. Redundant with `set-shape`'s
+//   `when` for every current page; kept only for pages and daemons from before `set-shape` (v1.312.0 and older),
+//   which check it. REMOVE IN v1.314.0, with the old `reshape` op it gates.
+// - `set-shape`: the `set-shape`/`forget-shape` ops, and `start`/`restart` applying a saved shape, all through an `ic`
+//   whose `ic sandbox shape` takes the contract's own shape (`--set`); advertised only when the agent's `ic` does.
+//   Both features ride that verb, so an agent advertises both or neither.
+export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape"]);
+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";
+// 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) => {
+        const known = DeviceFeatureSchema.safeParse(feature);
+        return known.success ? [known.data] : [];
+    });
+export const deviceSupports = (facts: Pick<DeviceFacts, "features"> | undefined, feature: DeviceFeature): boolean => deviceFeatures(facts).includes(feature);
 
 // Docker Desktop's own distros: `wsl -l -q` lists them like any other, and none ever runs an agent or holds a checkout.
 export const WSL_SYSTEM_DISTROS: ReadonlySet<string> = new Set(["docker-desktop", "docker-desktop-data"]);
@@ -64,11 +98,7 @@ export const windowsPathOf = (distro: string, linuxPath: string): string => `\\\
 // ONE CARD IS ONE COMPUTER, AND EACH OS INSTALL ON IT IS A CONNECTION OF THAT CARD. A PC's Windows side and every WSL
 // distro on it hold their own agent — mutagen has to watch the filesystem it syncs, and a distro's login shell is its
 // own — but the owner connected a computer, not a shell, so the grant, the row and the tools are the machine's.
-// The native environment's connection key IS the card id, by definition rather than as a fallback: a machine with one
-// OS install has one connection named after itself, and a sibling hangs off it as `<card>::wsl:<distro>`. `::` cannot
-// collide with the single colon in an environment key.
 export const HOST_NATIVE_ENVIRONMENT = "native";
-const ENVIRONMENT_SEPARATOR = "::";
 
 // Which environment a machine is describing when it connects: the distro by the name WSL registered (what `wsl -l -q`
 // prints and `in: "wsl:<name>"` takes), or the metal. Facts arrive at connect and no scope withholds them, so this is
@@ -76,14 +106,27 @@ const ENVIRONMENT_SEPARATOR = "::";
 export const environmentKeyOf = (facts: Pick<DeviceFacts, "wsl">): string =>
     facts.wsl === undefined ? HOST_NATIVE_ENVIRONMENT : `wsl:${facts.wsl.distro}`;
 
-export const hostConnectionKey = (entry: string, environment: string): string =>
-    environment === HOST_NATIVE_ENVIRONMENT ? entry : `${entry}${ENVIRONMENT_SEPARATOR}${environment}`;
+// A CONNECTION'S KEY, spelled and read in exactly one place. The key is what the hub, a device RPC and a page's row
+// address a connection by: the native environment's key IS the card id, and a sibling hangs off it as
+// `<card>::wsl:<distro>` (`::` cannot collide with the single colon in an environment key). What a connection IS —
+// its card, its environment, its computer — is the enrollment's own record (a host enrollment says all three, and a
+// device row carries `card`), so the parser is only for a key with nothing beside it: the key the owner asks to pair,
+// an enrollment written before records said, a row from a daemon older than `card`. A rename relabels the record and
+// the key follows from the label; the live connection is held under the new key without being cut (PeerHub.rekey).
+export interface HostConnection {
+    readonly card: string;
+    readonly environment: string;
+}
+const ENVIRONMENT_SEPARATOR = "::";
 
-export const hostEntryOf = (connection: string): string => connection.split(ENVIRONMENT_SEPARATOR)[0] ?? connection;
+export const hostConnectionKey = (card: string, environment: string): string =>
+    environment === HOST_NATIVE_ENVIRONMENT ? card : `${card}${ENVIRONMENT_SEPARATOR}${environment}`;
 
-export const hostEnvironmentOf = (connection: string): string => {
-    const at = connection.indexOf(ENVIRONMENT_SEPARATOR);
-    return at === -1 ? HOST_NATIVE_ENVIRONMENT : connection.slice(at + ENVIRONMENT_SEPARATOR.length);
+export const parseHostConnection = (key: string): HostConnection => {
+    const at = key.indexOf(ENVIRONMENT_SEPARATOR);
+    return at === -1
+        ? { card: key, environment: HOST_NATIVE_ENVIRONMENT }
+        : { card: key.slice(0, at), environment: key.slice(at + ENVIRONMENT_SEPARATOR.length) };
 };
 
 // One OS install of a machine, as its card knows it. `key` is the environment (`native`, `wsl:archlinux`); everything
@@ -91,6 +134,9 @@ export const hostEnvironmentOf = (connection: string): string => {
 // version — one side can be asleep, or running a build behind.
 export const HostEnvironmentSchema = z.object({
     key: z.string().min(1),
+    // The computer this environment's enrollment is on, once its agent has said (never a derived id): what joins it to
+    // a sync enrollment and to the other environments of that computer, whether or not it is connected right now.
+    machineId: MachineIdSchema.optional(),
     online: z.boolean(),
     version: z.string().optional(),
     lastSeen: z.number().optional(),
@@ -99,8 +145,11 @@ export const HostEnvironmentSchema = z.object({
 export type HostEnvironment = z.infer<typeof HostEnvironmentSchema>;
 
 export const HostSummarySchema = z.object({
-    // The capability id, the machine's name, and the prefix of its tools (mcp__<id>__run_command).
+    // The capability id, the machine's name, and the prefix of its tools (mcp__<id>__run_command). On a per-connection
+    // row (`hostConnections`) it is that connection's key instead, and `card` names the machine.
     id: z.string(),
+    // The card a per-connection row is a connection of: a label on the row, read rather than parsed out of `id`.
+    card: z.string().optional(),
     platform: z.string().min(1),
     // Every environment of this machine, native first: what the page draws a row per, and what a command picks from.
     // Never empty — a card that has never connected still has its native environment, offline.

package/src/schemas/ic-shape-args.test.ts

@@ -0,0 +1,64 @@
+import { DeviceSandboxFlowSchema, icForgetShapeArgs, icPowerArgs, icShapeArgs, SandboxShapeSchema } from "./devices.js";
+
+// The one spelling of ic's shape and power verbs outside ic: the machine agent runs these and the Devices view prints them for a
+// person to type, so a drift here is a command that fails on the machine, or one that does something else there.
+
+test("a whole shape is one `--set` per field, in the contract's own names and values", () => {
+    expect(icShapeArgs("work", { memoryGib: 20, cpus: null, privileged: false, gpu: true }, "nextRestart")).toEqual([
+        "sandbox",
+        "shape",
+        "work",
+        "--set",
+        "memoryGib=20",
+        "--set",
+        "cpus=null",
+        "--set",
+        "privileged=false",
+        "--set",
+        "gpu=true",
+        "--when",
+        "nextRestart",
+    ]);
+    expect(icShapeArgs("work", { memoryGib: null, cpus: 4, privileged: true, gpu: false }, "now").slice(3)).toEqual([
+        "--set",
+        "memoryGib=null",
+        "--set",
+        "cpus=4",
+        "--set",
+        "privileged=true",
+        "--set",
+        "gpu=false",
+        "--when",
+        "now",
+    ]);
+});
+
+test("a field left out is left to ic, which keeps what it has for it", () => {
+    expect(icShapeArgs("work", { memoryGib: 12, gpu: undefined }, "now")).toEqual(["sandbox", "shape", "work", "--set", "memoryGib=12", "--when", "now"]);
+});
+
+test("forgetting and power name only the sandbox", () => {
+    expect(icForgetShapeArgs("work")).toEqual(["sandbox", "shape", "work", "--forget"]);
+    expect(icPowerArgs("restart", "work")).toEqual(["sandbox", "restart", "work"]);
+});
+
+// A shape is whole: a delta would put the merge back into every reader, which is what this schema exists to end.
+test("a shape missing a field is not a shape", () => {
+    expect(SandboxShapeSchema.safeParse({ memoryGib: 20, cpus: null, privileged: false }).success).toBe(false);
+    expect(SandboxShapeSchema.safeParse({ memoryGib: 0, cpus: null, privileged: false, gpu: false }).success).toBe(false);
+    expect(SandboxShapeSchema.safeParse({ memoryGib: null, cpus: null, privileged: false, gpu: false }).success).toBe(true);
+});
+
+// Every device input is strict, the shape nested in one included: an agent that dropped a field it did not know would
+// carry out a different order than the one sent.
+test("a device order refuses a shape or delta field it does not know", () => {
+    const whole = { memoryGib: 20, cpus: null, privileged: false, gpu: false };
+    // As the order arrives off the wire, where the nested object is only ever JSON.
+    const accepted = (fields: object): boolean =>
+        DeviceSandboxFlowSchema.safeParse(JSON.parse(`{"op":"set-shape","slug":"work","when":"now","shape":${JSON.stringify(fields)}}`)).success;
+    expect(accepted(whole)).toBe(true);
+    expect(accepted({ ...whole, swapGib: 4 })).toBe(false);
+    expect(DeviceSandboxFlowSchema.safeParse({ op: "reshape", slug: "work", resources: { memoryGib: 20, swapGib: 4 } }).success).toBe(false);
+    // A report is read leniently: a newer ic's extra field must not fail an older reader.
+    expect(SandboxShapeSchema.safeParse({ ...whole, swapGib: 4 }).success).toBe(true);
+});

package/src/schemas/keep-warm.test.ts

@@ -5,7 +5,6 @@ import {
     keepWarmDueAt,
     keepWarmHorizon,
     keepWarmLeadMs,
-    keepWarmMaxRefreshes,
     keepWarmRefreshes,
     keptWarmLine,
 } from "./keep-warm.js";
@@ -13,20 +12,13 @@ import {
 const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
 
-// The arithmetic both the daemon and every press read, so the price shown before a press is the price the daemon keeps.
+// The clock both the daemon and every press read, so the refreshes shown before a press are the ones the daemon sends.
 describe("keep-warm economics", () => {
     test("refreshes a fifth of an entry's life early, never under a minute or over ten", () => {
         expect(keepWarmLeadMs(HOUR)).toBe(10 * MINUTE);
         expect(keepWarmLeadMs(5 * MINUTE)).toBe(MINUTE);
     });
 
-    test("spends at most half of what a cold resume would rewrite", () => {
-        // A 1h rewrite costs 2x base input and a read 0.1x: nineteen reads break even, so nine.
-        expect(keepWarmMaxRefreshes(HOUR)).toBe(9);
-        // A 5m rewrite costs 1.25x: eleven reads break even, so five.
-        expect(keepWarmMaxRefreshes(5 * MINUTE)).toBe(5);
-    });
-
     test("counts the refreshes that keep an entry alive through the deadline", () => {
         const cache = { at: 0, ttlMs: HOUR };
         expect(keepWarmRefreshes(cache, HOUR)).toBe(0);
@@ -34,11 +26,12 @@ describe("keep-warm economics", () => {
         expect(keepWarmDueAt(cache)).toBe(50 * MINUTE);
     });
 
-    test("reaches no further than the horizon, or the date change when that comes first", () => {
+    test("reaches no further than the refreshes left carry it, or the date change when that comes first", () => {
         const cache = { at: 0, ttlMs: HOUR };
-        expect(keepWarmHorizon(cache)).toBe(HOUR + 9 * 50 * MINUTE);
-        expect(keepWarmCap(cache, 3 * HOUR)).toBe(3 * HOUR);
-        expect(keepWarmCap({ at: 0, ttlMs: 5 * MINUTE }, undefined)).toBe(5 * MINUTE + 5 * 4 * MINUTE);
+        expect(keepWarmHorizon(cache, 9)).toBe(HOUR + 9 * 50 * MINUTE);
+        expect(keepWarmHorizon(cache, -2)).toBe(HOUR);
+        expect(keepWarmCap(cache, 3 * HOUR, 9)).toBe(3 * HOUR);
+        expect(keepWarmCap({ at: 0, ttlMs: 5 * MINUTE }, undefined, 5)).toBe(5 * MINUTE + 5 * 4 * MINUTE);
     });
 
     test("names the parts two fingerprints disagree on", () => {

package/src/schemas/keep-warm.ts

@@ -1,13 +1,8 @@
-// keep-warm: holding an idle conversation's prompt cache open by re-reading it shortly before it expires.
+// keep-warm: holding an idle conversation's prompt cache open by re-reading it shortly before it expires. Only the
+// clock lives here; how many refreshes a hold may spend is priced by the provider that serves it (runtimes/claude).
 
 import { z } from "zod";
 
-const HOUR_MS = 3_600_000;
-
-// Anthropic's price multipliers on base input: a read costs 0.1x, a write 2x under the 1h TTL and 1.25x under 5m.
-const READ_COST = 0.1;
-const writeCost = (ttlMs: number): number => (ttlMs >= HOUR_MS ? 2 : 1.25);
-
 // A cache clock as the daemon publishes it: the last request that touched the entry, and the entry's lifetime.
 export interface CacheClock {
     readonly at: number;
@@ -17,28 +12,26 @@ export interface CacheClock {
 /** How long before expiry a refresh starts: a fifth of the entry's life, never under a minute or over ten. */
 export const keepWarmLeadMs = (ttlMs: number): number => Math.min(10 * 60_000, Math.max(60_000, Math.round(ttlMs / 5)));
 
-/** Refreshes one hold may spend: half of what a cold resume rewrites, the other half left for each refresh's own tail. */
-export const keepWarmMaxRefreshes = (ttlMs: number): number => Math.floor((writeCost(ttlMs) - READ_COST) / READ_COST / 2);
-
 /** How many refreshes keep an entry alive through `until`. */
 export const keepWarmRefreshes = (cache: CacheClock, until: number): number => {
     const beyond = until - (cache.at + cache.ttlMs);
     return beyond <= 0 ? 0 : Math.ceil(beyond / (cache.ttlMs - keepWarmLeadMs(cache.ttlMs)));
 };
 
-/** The latest instant a hold may reach, given the refreshes it already spent: past it, refreshing costs more than the cold resume it saves. */
-export const keepWarmHorizon = (cache: CacheClock, spent = 0): number =>
-    cache.at + cache.ttlMs + Math.max(0, keepWarmMaxRefreshes(cache.ttlMs) - spent) * (cache.ttlMs - keepWarmLeadMs(cache.ttlMs));
+/** The latest instant `left` more refreshes can carry an entry to: past it, refreshing costs more than the cold resume it saves. */
+export const keepWarmHorizon = (cache: CacheClock, left: number): number =>
+    cache.at + cache.ttlMs + Math.max(0, left) * (cache.ttlMs - keepWarmLeadMs(cache.ttlMs));
 
 /** When the next refresh is due for an entry last touched at `cache.at`. */
 export const keepWarmDueAt = (cache: CacheClock): number => cache.at + cache.ttlMs - keepWarmLeadMs(cache.ttlMs);
 
 /** The furthest `until` a hold can honestly promise: the economic horizon, or the date change, whichever comes first. */
-export const keepWarmCap = (cache: CacheClock, rollsAt: number | undefined, spent = 0): number =>
-    rollsAt === undefined ? keepWarmHorizon(cache, spent) : Math.min(keepWarmHorizon(cache, spent), rollsAt);
+export const keepWarmCap = (cache: CacheClock, rollsAt: number | undefined, left: number): number =>
+    rollsAt === undefined ? keepWarmHorizon(cache, left) : Math.min(keepWarmHorizon(cache, left), rollsAt);
 
-// Why a hold ended before anyone picked the conversation up. `elapsed` is the one ending that is not a problem.
-export const KeepWarmEndSchema = z.enum(["elapsed", "allowance", "limited", "changed", "rewrote", "cold", "failed", "midnight", "moved"]);
+// Why a hold ended before anyone picked the conversation up, one per thing a person would do about it; `detail` carries
+// the specifics. `elapsed` is the one ending that is not a problem.
+export const KeepWarmEndSchema = z.enum(["elapsed", "allowance", "changed", "cold", "failed"]);
 export type KeepWarmEnd = z.infer<typeof KeepWarmEndSchema>;
 
 export const KeepWarmSchema = z.object({
@@ -48,7 +41,6 @@ export const KeepWarmSchema = z.object({
         .describe(
             "When it stops by itself, in milliseconds: the time asked for, shortened to what the sandbox can honestly keep, which is never past the point where refreshing costs more than re-reading, nor past the date change that rewrites the prompt.",
         ),
-    auto: z.boolean().optional().describe("Started by the sandbox-wide setting after a turn, rather than by a press on this conversation."),
     refreshes: z.number().int().min(0).describe("Refreshes sent so far."),
     readTokens: z
         .number()
@@ -58,9 +50,12 @@ export const KeepWarmSchema = z.object({
         .object({
             at: z.number().describe("When it stopped, in milliseconds."),
             reason: KeepWarmEndSchema.describe(
-                "Why: `elapsed` the time asked for ran out; `allowance` the account reached the reserve kept for real work; `limited` the provider refused a refresh; `changed` what the next turn would send no longer matches the cache; `rewrote` a refresh found the cache already gone; `cold` it expired before a refresh could run; `failed` a refresh failed; `midnight` the date in the prompt changed; `moved` the conversation's session or account changed.",
+                "Why: `elapsed` the time asked for ran out; `allowance` the account reached the reserve kept for real work, or the provider refused a refresh for its limit; `changed` what the next turn would send no longer matches the cache (a part of the prompt, the date in it, or the conversation's session or account); `cold` the cache was gone, expired before a refresh could run or found missing by one; `failed` a refresh failed.",
             ),
-            detail: z.string().optional().describe("The specifics, when there are any: which parts of the prompt changed, or the failure's own words."),
+            detail: z
+                .string()
+                .optional()
+                .describe("The specifics, when there are any: which parts of the prompt changed, how full the account was, or the failure's own words."),
         })
         .optional()
         .describe("Why keeping it warm stopped before anyone picked the conversation up. Absent while it is still being kept."),

package/src/schemas/metrics.ts

@@ -53,20 +53,49 @@ export const PressureMetricsSchema = z.object({
 });
 export type PressureMetrics = z.infer<typeof PressureMetricsSchema>;
 
+// The memory figures the daemon admits work by (its resource budget), so a gauge built on them warns exactly when a turn
+// would be held.
+export const MemoryRoomSchema = z.object({
+    freeBytes: z
+        .number()
+        .optional()
+        .describe("The limit less what is used and what work admitted in the last minute and a half still holds. Absent where nothing measures it."),
+    reservedBytes: z.number().describe("What work admitted in the last minute and a half holds before it shows in `memoryBytes`."),
+    personNeedBytes: z.number().describe("What a person's turn needs free to start without a warning: below it, the sandbox is short."),
+    stallPercent: z.number().describe("Percent of the last ten seconds in which everything in the sandbox waited on memory (pressure `full`)."),
+    stallLimitPercent: z.number().describe("The stall at or past which the sandbox counts as short of memory, whatever `freeBytes` says."),
+});
+export type MemoryRoom = z.infer<typeof MemoryRoomSchema>;
+
 export const SandboxUsageSchema = z.object({
     cpuPercent: z
         .number()
         .optional()
         .describe("CPU the whole sandbox used over the window, as a percentage of all it may use (`cores`). Absent on a first reading."),
     cores: z.number().describe("How many cores the sandbox may use: its CPU quota, or every core it is allowed to run on when it has none."),
-    memoryBytes: z.number().describe("Memory in use, less the file cache the kernel takes back on demand: the figure that runs into the limit."),
-    memoryLimitBytes: z.number().describe("The memory limit: the container's own, or the machine's memory when the container has none."),
-    swapBytes: z.number().optional().describe("Memory pushed out to swap. Absent where the sandbox cannot see its own swap."),
+    memoryBytes: z
+        .number()
+        .describe(
+            "Memory in use as the daemon admits work by it: resident memory less the file cache the kernel takes back on demand, plus what was pushed to swap.",
+        ),
+    memoryLimitBytes: z
+        .number()
+        .describe(
+            "The memory limit work is admitted against: where the kernel starts throttling the container (memory.high), else its hard limit, else the machine's memory.",
+        ),
+    swapBytes: z.number().optional().describe("Of `memoryBytes`, what was pushed out to swap. Absent where the sandbox cannot see its own memory."),
+    memoryRoom: MemoryRoomSchema.optional().describe("What admission reads off the same reading. Absent from a daemon that predates it."),
     diskBytes: z.number().optional().describe("Space used on the volume the workspace lives on. Absent when the volume would not say."),
     diskTotalBytes: z.number().optional().describe("That volume's size. Absent when the volume would not say."),
     loadAverage: z
         .tuple([z.number(), z.number(), z.number()])
         .describe("The load average over 1, 5 and 15 minutes. It is the machine's, so other sandboxes on it count too."),
+    machineCores: z
+        .number()
+        .optional()
+        .describe(
+            "Cores the machine's load average reads against: every core the sandbox may be scheduled on, before any quota. Absent from a daemon that predates it.",
+        ),
     processes: z.number().describe("How many processes are running in the sandbox."),
     pressure: PressureMetricsSchema.optional().describe(
         "How much work waited on CPU, memory or disk lately. Absent where the kernel does not report it.",

package/src/schemas/personas.ts

@@ -42,6 +42,21 @@ export const PersonaPowersSchema = z.object({
     connectors: z.array(entryId).max(100).optional(),
     devices: z.array(entryId).max(50).optional(),
     mcp: z.array(entryId).max(50).optional(),
+    // By extension id (`publisher.name`, or a git install's card id), the same tri-state. A card an extension serves
+    // rides `connectors`; this is what the extension brings of its own.
+    extensions: z
+        .array(
+            z
+                .string()
+                .min(1)
+                .max(121)
+                .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/),
+        )
+        .max(100)
+        .optional()
+        .describe(
+            "Which extensions' own agent tools and agent plugin (skills, commands, subagents) it gets, by extension id. Absent means every enabled one; empty means none. The tools an extension serves for a connected card follow the connectors list instead.",
+        ),
 });
 export type PersonaPowers = z.infer<typeof PersonaPowersSchema>;
 // `folders` only refuses file-tool calls outside it; it stops a misread instruction, not a shell. The container is the

package/src/schemas/providers/plan-limits.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ChildRunSchema } from "../../events/requests.js";
 import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../../models/provider-specs.js";
 import { AgentHarnessSchema, AgentProviderSchema, EditorContextSchema } from "../agent.js";
 import { MENTION_LIMIT } from "../../text/mentions.js";
@@ -44,6 +45,38 @@ export const AccountUsageSchema = z.object({
     ),
 });
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
+// Who has to act for a blocked account, which is the only thing a surface chooses its instruction by: the reason is the
+// words for a person, never a key.
+export const AccountFixSchema = z.enum(["reconnect", "admin", "wait"]);
+export type AccountFix = z.infer<typeof AccountFixSchema>;
+// Whether an account can serve a turn, decided once by the daemon (models/plan-pools.ts `serviceState`) from every fact
+// it holds about it: a revoked sign-in, a lost seat, a translator bench, a refusal still standing, and its plan limits.
+// Every picker (an unnamed turn, a limit move, a keep-warm refresh) and every surface reads this one verdict.
+export const AccountStateSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("ready"),
+        room: z
+            .number()
+            .describe("How much of the fullest pool that gates the turn is left, in percent (above 0, up to 100). Pickers take the most room."),
+    }),
+    z.object({
+        kind: z.literal("spent"),
+        reopensAt: z
+            .number()
+            .optional()
+            .describe("When every full pool has reopened, in epoch seconds, where the plan publishes it. Absent means unknown, never now."),
+    }),
+    z.object({
+        kind: z.literal("blocked"),
+        fix: AccountFixSchema.describe(
+            "Who can make it serve again: `reconnect` (sign in again on this sandbox), `admin` (an organisation admin hands the seat back), or `wait` (it lifts by itself, at `until` where known).",
+        ),
+        reason: z.string().describe("Why, in words a person can act on: the provider's own sentence where it gave one."),
+        until: z.number().optional().describe("When waiting lifts it, in epoch seconds, for `wait` only."),
+    }),
+    z.object({ kind: z.literal("unknown").describe("Nothing blocks it and nothing has been measured: usable, never read as room.") }),
+]);
+export type AccountState = z.infer<typeof AccountStateSchema>;
 // Anthropic's once-a-week reset of the session window only; the weekly allowance is untouched. The answer is entirely
 // the provider's — never infer `available` from a 100% window. `reason` is its own word, carried verbatim.
 export const LimitResetStatusSchema = z.object({
@@ -120,6 +153,9 @@ export const TranslatorAccountSchema = z.object({
             reason: z.string().optional(),
         })
         .optional(),
+    state: AccountStateSchema.optional().describe(
+        "Whether it can serve a turn now, judged from everything above plus the provider's last refusal. Absent from a daemon older than this field.",
+    ),
 });
 export type TranslatorAccount = z.infer<typeof TranslatorAccountSchema>;
 // A list per provider, not a flag: CLIProxyAPI holds several auth files per provider and balances across them. Built
@@ -167,6 +203,10 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .enum(["once", "always", "deny"])
             .describe("Once allows this call alone; always allows that whole tool for the rest of the conversation; no blocks it."),
         feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
+        // Whole, not a patch: effort or an account named for one model means nothing on another.
+        child: ChildRunSchema.optional().describe(
+            "For a request to start a child agent: what to start it on instead of what the agent asked for. It replaces the whole run (model, account, effort and the rest), not only the fields it names. Ignored with a no, and on any other request.",
+        ),
     }),
     z.object({
         kind: z
@@ -221,6 +261,11 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
     }),
 ]);
 export type AgentReply = z.infer<typeof AgentReplySchema>;
+// Every card a turn can park on its person with, one per reply kind, so a new card reaches every park reader at once.
+export type ParkKind = AgentReply["kind"];
+export const PARK_KINDS: readonly ParkKind[] = AgentReplySchema.options.map((option) => option.shape.kind.value);
+const PARKING = new Set<string>(PARK_KINDS);
+export const isParkKind = (kind: string): kind is ParkKind => PARKING.has(kind);
 // A message injected into a running turn between tool calls; NOT_FOUND when none is steerable, and the client queues it
 // as the next turn instead. Carries everything a fresh prompt can (files, editor context).
 export const SteerSchema = z
@@ -295,7 +340,12 @@ export type StopResult = z.infer<typeof StopResultSchema>;
 export const ResumeRoutingSchema = z.object({
     agent: AgentProviderSchema.describe("Which provider serves the re-run."),
     harness: AgentHarnessSchema.describe("Which agentic loop runs it."),
-    account: z.string().optional().describe("Which of that provider's accounts pays for it. Leave it out for the first one."),
+    account: z
+        .string()
+        .optional()
+        .describe(
+            "Which of that provider's accounts pays for it. Leave it out to keep the account the conversation runs on, or, on another provider, to take whichever of its accounts can serve with the most room. Moving to another account of the same provider is `switchAccount`'s job; naming one here still works.",
+        ),
     // A client whose catalog hasn't loaded has nothing to send; the turn's own model is the better fallback.
     model: z.string().optional().describe("Which model. Leave it out to keep the one the refused turn named."),
     // A session is a file the daemon keeps; a credential is an env var. That's what lets a same-provider account switch
@@ -339,3 +389,23 @@ export const QueueResumeSchema = z.object({
     ),
 });
 export type QueueResume = z.infer<typeof QueueResumeSchema>;
+// Moves a conversation to another account of the provider it runs on: the one command that changes who pays, so the
+// account a conversation runs on is always the daemon's record and never a window's guess.
+export const SwitchAccountSchema = z.object({
+    conversationId: z.string().min(1).describe("Which conversation to move."),
+    account: z.string().min(1).describe("Which of the conversation's provider's connected accounts pays for its turns from now on."),
+    carry: z
+        .boolean()
+        .optional()
+        .describe(
+            "Keep the provider session across the move (the model keeps everything, and re-reads all of it once on the other account) rather than opening a fresh one seeded from the record.",
+        ),
+});
+export type SwitchAccount = z.infer<typeof SwitchAccountSchema>;
+export const AccountSwitchedSchema = z.object({
+    run: z
+        .string()
+        .optional()
+        .describe("The run that re-ran a held turn on the new account, when one was waiting: attach to it. Absent when nothing was held."),
+});
+export type AccountSwitched = z.infer<typeof AccountSwitchedSchema>;

package/src/schemas/providers/provider-oauth.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AccountUsageSchema } from "./plan-limits.js";
+import { AccountStateSchema, AccountUsageSchema } from "./plan-limits.js";
 import { KeyedProviderSchema } from "./provider-subscriptions.js";
 // Claude uses PKCE paste-back (start → exchange); Codex uses OpenAI's device-code flow (start → poll). A sandbox can
 // hold several accounts per provider; `id` is the store key, `label` the display name. Tokens never ride this shape —
@@ -15,6 +15,12 @@ export const OauthAccountSchema = z.object({
             "Who it signs in as, in the provider's own words. Kept beside the label rather than folded into it, so a renamed account can still say whose it is. Absent when the provider says nothing, which is exactly when renaming is the only answer.",
         ),
     organization: z.string().optional().describe("Which organisation it belongs to, where the provider says."),
+    variant: z
+        .string()
+        .optional()
+        .describe(
+            "Which of the provider's estates it signs in to, for a provider selling more than one (Z.ai's international or mainland plan). With the email and organisation, it is who the account is: a sign-in matching all three lands on this account again, same id.",
+        ),
     scope: z.string().optional().describe("What the credential is permitted to do, in the provider's terms."),
     connectedAt: z.number().describe("When it was connected, in milliseconds."),
     needsReauth: z
@@ -31,6 +37,9 @@ export const OauthAccountSchema = z.object({
     usage: AccountUsageSchema.optional().describe(
         "How full its plan limits were when last measured, so a picker can show what is left before committing work to it. Absent until a reading exists, which reads as unknown rather than as nothing left.",
     ),
+    state: AccountStateSchema.optional().describe(
+        "Whether it can serve a turn now, judged once from the sign-in, the seat, the provider's last refusal and the plan limits: the verdict every picker in the sandbox uses. Read this rather than the fields it was judged from. Absent from a daemon older than this field.",
+    ),
 });
 export type OauthAccount = z.infer<typeof OauthAccountSchema>;
 export const OauthAccountListSchema = z.object({

package/src/schemas/settings-history.ts

@@ -1,6 +1,6 @@
-import type { z } from "zod";
-import { dropAll, isJsonObject, mapValue, retype } from "../documents/conversions.js";
-import type { RuleSchema } from "./settings.js";
+import { z } from "zod";
+import { dropAll, fold, isJsonObject, mapValue, retype } from "../documents/conversions.js";
+import type { KeepWarmSettings, RuleSchema } from "./settings.js";
 
 // The conversions the settings shape has had, oldest first: what brings any earlier release's settings to
 // SandboxSettingsSchema. Two documents carry this shape, the daemon's settings.json and a sandbox.toml's [settings]
@@ -23,6 +23,46 @@ const isRetiredRule = (rule: unknown): boolean => {
 
 const holdsRetiredRule = (value: unknown): value is readonly unknown[] => Array.isArray(value) && value.some(isRetiredRule);
 
+// A rule at the `turn.ending` moment reads and runs nothing since nothing checks inside a turn (its moment and the
+// `verify-ui-edits` built-in stay in the read schema so a file written before reads); dropped, so it stops showing as a
+// rule the owner has and stops travelling with the settings.
+const isInertRule = (rule: unknown): boolean =>
+    isJsonObject(rule) &&
+    (rule["moment"] === "turn.ending" || (isJsonObject(rule["action"]) && rule["action"]["kind"] === "builtin" && rule["action"]["name"] === "verify-ui-edits"));
+
+const holdsInertRule = (value: unknown): value is readonly unknown[] => Array.isArray(value) && value.some(isInertRule);
+
+// keep-warm's four top-level settings (2026-09-26), folded into the one `keepWarm` object; a value of the wrong type is
+// left out, for the schema's own default to fill.
+const KEEP_WARM_FLAT = ["keepWarm", "keepWarmHours", "keepWarmMinTokens", "keepWarmReserve"] as const;
+const FlatSwitch = z.boolean();
+const FlatNumber = z.number();
+const keepWarmObject = fold("folds keepWarm, keepWarmHours, keepWarmMinTokens and keepWarmReserve into one keepWarm object", {
+    from: KEEP_WARM_FLAT,
+    into: "keepWarm",
+    applies: (settings) => FlatSwitch.safeParse(settings["keepWarm"]).success || KEEP_WARM_FLAT.slice(1).some((key) => Object.hasOwn(settings, key)),
+    convert: ({ keepWarm, keepWarmHours, keepWarmMinTokens, keepWarmReserve }): Partial<KeepWarmSettings> => {
+        const folded: Partial<KeepWarmSettings> = {};
+        const auto = FlatSwitch.safeParse(keepWarm);
+        const hours = FlatNumber.safeParse(keepWarmHours);
+        const minTokens = FlatNumber.safeParse(keepWarmMinTokens);
+        const reserve = FlatNumber.safeParse(keepWarmReserve);
+        if (auto.success) {
+            folded.auto = auto.data;
+        }
+        if (hours.success) {
+            folded.hours = hours.data;
+        }
+        if (minTokens.success) {
+            folded.minTokens = minTokens.data;
+        }
+        if (reserve.success) {
+            folded.reserve = reserve.data;
+        }
+        return folded;
+    },
+});
+
 export const SETTINGS_HISTORY = [
     // Every setting a release since 2026-08-10 had and this one does not (read off the contract lock's history):
     // retired, so passthrough stops carrying them, a definition naming one still applies, and no later setting may
@@ -58,4 +98,11 @@ export const SETTINGS_HISTORY = [
     ),
     // suggest, the old default, becomes the new default: routing on.
     mapValue("personaRouting", { off: false, suggest: true, auto: true }),
+    retype(
+        "rules",
+        holdsInertRule,
+        (rules) => rules.filter((rule) => !isInertRule(rule)) as z.input<typeof RuleSchema>[],
+        "drops rules at the retired turn.ending moment (and the verify-ui-edits built-in), which run nothing",
+    ),
+    keepWarmObject,
 ] as const;