@intentic/sandbox-contract 1.326.0 → 1.327.0

package/src/schemas/capabilities.ts

@@ -7,6 +7,7 @@ import { NetdiskConfigSchema } from "./netdisk.js";
 import { VpnConfigSchema } from "./vpn.js";
 // One-way: the browser extension bundles webext.js alone, so nothing there may reach back into this file.
 import { WebExtConfigSchema } from "./webext.js";
+import { PhoneConfigSchema } from "./phone.js";
 // Everything a user adds is a capability with an idempotent apply plus a status check; the manifest is the source of
 // truth for what's active, and `mcp`-kind entries also feed the agent's MCP servers each turn.
 
@@ -26,6 +27,7 @@ export const CapabilityKindSchema = z.enum([
     "identity",
     "device",
     "webext",
+    "phone",
     "agent",
     "endpoint",
     "localmodel",
@@ -62,7 +64,9 @@ export const PluginConfigSchema = z.object({
         .string()
         .min(1)
         .optional()
-        .describe("A branch, tag or commit to install from. Leave it out for the default branch. The install pins the commit it names at that moment."),
+        .describe(
+            "A branch, tag or commit to install from. Leave it out for the default branch. The install pins the commit it names at that moment.",
+        ),
     path: z
         .string()
         .min(1)
@@ -141,7 +145,9 @@ const STASHED_PREFIX = "__intentic_stashed__:";
 export const stashedMarker = (token: string): string => `${STASHED_PREFIX}${token}`;
 // The token a marker names; undefined for anything else (a real key, VAULTED, a blank).
 export const stashedToken = (value: unknown): string | undefined =>
-    typeof value === "string" && value.startsWith(STASHED_PREFIX) && value.length > STASHED_PREFIX.length ? value.slice(STASHED_PREFIX.length) : undefined;
+    typeof value === "string" && value.startsWith(STASHED_PREFIX) && value.length > STASHED_PREFIX.length
+        ? value.slice(STASHED_PREFIX.length)
+        : undefined;
 // What is optional about the in-sandbox Docker Engine: `gpu` is an IMAGE option (rides the Dockerfile overlay, needs a
 // rebuild), everything else is an ENGINE option (rewrites daemon.json, restarts dockerd, no rebuild but stops running
 // containers). Flat strings, not nested booleans, to match the manifest's own two-state convention.
@@ -326,7 +332,6 @@ export const localModelChoice = (id: string): LocalModelChoice | undefined => LO
 export const LOCAL_MODEL_INSTANT: LocalModelChoice = LOCAL_MODELS.find((choice) => choice.tier === "instant")!;
 export const LocalModelConfigSchema = z.object({
     model: z.string().min(1),
-    gpu: z.enum(["on", "off"]).default("off"),
     url: z.url().optional(),
     context: z.union([z.enum(LOCAL_MODEL_WINDOWS), z.literal("custom")]).default(LOCAL_MODEL_WINDOW_DEFAULT),
     // Coerced from a text field's string, like the ssh card's `port`; read only when `context` is "custom".
@@ -402,6 +407,10 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     // from `browser`, the sandbox's own Chromium profile: this one is the person's, already signed into everything,
     // only ever borrowed.
     z.object({ id: entryId, kind: z.literal("webext"), config: WebExtConfigSchema }),
+    // The user's own phone, through the app they installed on it; one capability per phone. Its own kind rather than a
+    // `device` platform: a phone has no shell and no home folder, and what it grants (screen, apps, picked folders,
+    // notifications) is a different set of switches.
+    z.object({ id: entryId, kind: z.literal("phone"), config: PhoneConfigSchema }),
     z.object({ id: entryId, kind: z.literal("agent"), config: AcpAgentConfigSchema }),
     // The id becomes `endpoint/<id>` in the chat picker, the `agent` kind's precedent, since these two are the only
     // kinds that mint providers.
@@ -444,6 +453,7 @@ export const CapabilitySummarySchema = z.object({
         .default([])
         .describe("Which credentials it holds, by name. The values are on one route only, and it is not this one."),
 });
+export type CapabilitySummary = z.infer<typeof CapabilitySummarySchema>;
 // A capability the workspace asks for but the manifest doesn't carry, derived from what's checked out under /work, not
 // from configuration; prevents illegible failures like a missing docker socket with no pointer back to the fix. Keyed
 // by catalog card, not kind, since several cards share one kind. Re-derived on every read, so it drops out once its

package/src/schemas/ci.ts

@@ -76,6 +76,16 @@ export const PipelineJobSchema = z.object({
         .describe(
             "Which jobs in this run it declared it waits on: the real shape of the pipeline. Absent means nothing could be read, which is different from an empty list, which is the claim that it waits on nothing.",
         ),
+    declaredId: z
+        .string()
+        .optional()
+        .describe(
+            "The job's id in its workflow file, with a called workflow's job under its caller as `caller.job`. Present where the workflow could be read; it is what the forge orders its own drawing of the run by.",
+        ),
+    matrix: z
+        .string()
+        .optional()
+        .describe("The matrix job this is one leg of, by that job's name. Legs of one matrix are drawn together, apart from every other job."),
     startedAt: z.number().optional().describe("When it began, in milliseconds. Absent while it is queued."),
     finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
     durationSeconds: z.number().optional().describe("How long it took."),

package/src/schemas/devices.ts

@@ -90,6 +90,17 @@ export const DeviceSandboxSchema = z.object({
     lastUpdate: UpdateOutcomeSchema.optional(),
     // Newest first: what `rollback` would return to, then the older versions kept on this machine for `rollback --to`.
     rollbackTargets: z.array(RollbackTargetSchema).optional(),
+    // The other side of this computer that keeps it (`windows`, `linux`; from 2026-10-05 `platform/env`, e.g.
+    // `linux/archlinux`, so two WSL distros are told apart). On Windows, ic on Windows and ic in WSL drive one Docker
+    // engine and each lists every sandbox on it, but only the side whose ic created a sandbox runs its background rounds
+    // (keeper, updates, backups, probation); absent for this side's own, and from an older ic.
+    keptElsewhere: z.string().optional(),
+    // How a person reads that side ("WSL (archlinux)", "Windows").
+    keptElsewhereName: z.string().optional(),
+    // The side that keeps it has gone silent (its keeper stopped writing `/history/.ic/keeper.json` for half an hour),
+    // so this side adopted it for its rounds: `keptElsewhere` is left out, and these say whose it was and since when.
+    adoptedFrom: z.string().optional(),
+    keeperSilentSince: z.number().optional(),
 });
 export type DeviceSandbox = z.infer<typeof DeviceSandboxSchema>;
 // One operation on one sandbox, streamed as lines ending in a `result` or `error` frame. `prepare` builds the pending
@@ -377,12 +388,21 @@ export const clearableOnDevice = (conflict: DeviceConflict): boolean =>
 // One paired sandbox as the local agent holds it; `localDir` is which folder on that device holds this sandbox's /work.
 export const DevicePairingSchema = z.object({
     sandboxId: z.string(),
+    // The account's name for the sandbox, stamped by the editor that reads the report (withSandboxNames), as a
+    // container's `name` is. A machine never sends one: all it knows is the folder, named once at setup.
+    name: z.string().optional(),
     mode: z.enum(["sync", "mirror"]),
     // Set only for mode "sync", and only for the sandbox being reported to.
     localDir: z.string().optional(),
     // Which sandbox folder `localDir` holds when it is not /work itself: a project pairing's `/work/<name>`, the
     // owner's own folder, which carries no state backup and no git bridge. Absent means /work.
     remoteDir: z.string().optional(),
+    // The folderless pairing that holds this machine's sync token for its own local sandbox, which project folders
+    // attach to (`intentic-machine sync attach`). Absent on every other pairing.
+    projectsHost: z.boolean().optional(),
+    // Whether landed work in this project folder is delivered to `localDir` by itself (`deliverProject`). Only a
+    // folder attached to the machine's own sandbox says "auto"; absent means Bring back by hand, as before.
+    deliver: z.enum(["auto", "off"]).optional(),
     // Machine-owned switch (agent's own `sync mirror off`); absent reads as "on", not merely unknown.
     mirroring: z.enum(["on", "off"]).optional(),
     // Mutagen's own status word, kept verbatim rather than reduced to a traffic light.
@@ -583,6 +603,10 @@ export const DeviceSchema = z.object({
     // report at all. Absent means nobody could look — a sync-only machine, a refusal, an unread device — never that
     // the machine holds none.
     sandboxes: z.array(DeviceSandboxSchema).optional(),
+    // Why `sandboxes` is absent, in the machine's own words, when it answered the listing with a refusal or a failure
+    // (a switch that is off, an `ic` too old to list). Absent when it listed, or when nothing answered at all. What a
+    // card falling back to a command says instead of "connect the computer": that computer IS connected (2026-10-07).
+    sandboxesUnread: z.string().optional(),
     gap: DeviceGapSchema.optional(),
 });
 export type Device = z.infer<typeof DeviceSchema>;

package/src/schemas/engines.ts

@@ -100,3 +100,10 @@ export const EngineAppliedSchema = z.object({
     // An in-process engine (`@cursor/sdk`) is picked up by the next turn; a running turn keeps its module.
     fromNextTurn: z.boolean().describe("Whether the change reaches turns already in flight, or only the next one."),
 });
+// What every engine write answers: what it applied, null when there was nothing to do (a second tab's Update lost the
+// race), and the whole view after it, never a patch to reconcile.
+export const EngineWriteResultSchema = z.object({
+    applied: EngineAppliedSchema.nullable(),
+    engines: EnginesViewSchema,
+});
+export type EngineWriteResult = z.infer<typeof EngineWriteResultSchema>;

package/src/schemas/extension-updates.ts

@@ -2,6 +2,7 @@
 // check found and what the owner decided to do about it.
 import { z } from "zod";
 import { ExtensionManifestSchema } from "@intentic/extension-manifest";
+import { RegistryTrustSchema } from "@intentic/registry";
 // Each extension is addressed by its capability entry id (git-installed) or its manifest's `publisher.name`
 // (image-baked, no entry), hence the dot allowed here. A rotted checkout is skipped; its capability row still shows
 // status.
@@ -26,7 +27,8 @@ export const ExtensionUpdateSchema = z.object({
     version: z.string().optional().describe("What it calls itself."),
     url: z.string().describe("Where it comes from."),
     path: z.string().optional().describe("Where inside that repository it lives."),
-    trust: z.enum(["verified", "listed"]).describe("Whether anybody vouched for it, or it is merely listed."),
+    // The registry's trust, less `blocked`: a blocked row is an advisory, never an update on offer.
+    trust: RegistryTrustSchema.exclude(["blocked"]).describe("Whether anybody vouched for it, or it is merely listed."),
     // The badge renders loud (urgent) when this is set.
     securityFix: z
         .boolean()
@@ -129,6 +131,42 @@ export const ExtensionUpdatesCheckedSchema = z.object({
     ok: z.literal(true).describe("The check ran."),
     checkedAt: z.string().describe("When, so a screen can date the answer."),
 });
+// Dev mode: an extension installed from a repository, served from a source checkout in this workspace instead of its
+// pinned clone (.intentic/local/extension-dev.json), so a change to its code is seen on reload without being landed.
+// `path` and `conversation` are kept apart rather than joined into one display string: a screen says "in conversation
+// <id>" in its own words.
+export const ExtensionDevSchema = z.object({
+    path: z
+        .string()
+        .describe(
+            "The source checkout it was pointed at, such as extensions/maintenance: relative to the workspace, or to the conversation's own copy of it when `conversation` is set.",
+        ),
+    conversation: z
+        .string()
+        .optional()
+        .describe(
+            "The conversation whose isolated copy of the workspace holds that checkout. Absent means the workspace itself. That copy goes when the conversation does, and the pinned version runs again then.",
+        ),
+    uncommitted: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("How many files in the checkout differ from its last commit, a rebuilt bundle included. Absent when git could not say."),
+    revision: z
+        .string()
+        .optional()
+        .describe(
+            "A short fingerprint of the browser bundle served from the checkout. It changes with every rebuild, which is how a screen tells the copy it loaded is behind. Absent while held, and for an extension with no browser half.",
+        ),
+    held: z
+        .string()
+        .optional()
+        .describe(
+            "Why the checkout is not what runs, as a sentence: it is gone, holds a different extension, is not built yet, or asks for powers the pinned version was never approved for. Present means the pinned version still runs.",
+        ),
+});
+export type ExtensionDev = z.infer<typeof ExtensionDevSchema>;
 export const ExtensionSummarySchema = z.object({
     id: extensionId.describe("The extension's id."),
     manifest: ExtensionManifestSchema.describe("What it declares about itself: what it contributes, what it needs, and what it may reach."),
@@ -166,9 +204,9 @@ export const ExtensionSummarySchema = z.object({
     backend: z
         .object({
             state: z
-                .enum(["running", "error", "absent", "incompatible", "starting", "stopped"])
+                .enum(["running", "degraded", "error", "absent", "incompatible", "starting", "stopped"])
                 .describe(
-                    "How its server half is doing. Absent means the code is not in this image at all; incompatible means it needs a different sandbox version.",
+                    "How its server half is doing. Degraded means it serves but says something it relies on is not working; absent means the code is not in this image at all; incompatible means it needs a different sandbox version.",
                 ),
             detail: z
                 .string()
@@ -204,8 +242,60 @@ export const ExtensionSummarySchema = z.object({
     updatePolicy: ExtensionUpdatePolicySchema.optional().describe(
         "The owner's standing answer for this one: tell me, have an agent look, or just do it.",
     ),
+    dev: ExtensionDevSchema.optional().describe(
+        "Set while an extension installed from a repository is pointed at a source checkout in this workspace, for working on the extension itself: its code is served from there instead of the pinned copy. `commit` keeps naming the pinned version, which is what updates and the registry compare against.",
+    ),
 });
 export type ExtensionSummary = z.infer<typeof ExtensionSummarySchema>;
+// The dev-mode verbs address an installed extension any of the ways a person names one.
+const devTarget = z
+    .string()
+    .min(1)
+    .describe(
+        "Which installed extension: its connection id (intentic-maintenance), its manifest id (intentic.maintenance) or its short name (maintenance).",
+    );
+export const ExtensionDevSetInputSchema = z.object({
+    id: devTarget,
+    path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+            "The checkout to run it from. From an agent in an isolated conversation, a relative or /work path reads against that conversation's own copy. Absent: the workspace repository cloned from the address it was installed from, the calling conversation's copy first.",
+        ),
+});
+export const ExtensionDevTargetSchema = z.object({ id: devTarget });
+export const ExtensionDevStateSchema = z.object({
+    id: extensionId.describe("Its connection id."),
+    name: z.string().describe("Its manifest id, publisher.name."),
+    dev: ExtensionDevSchema.describe("Where it runs from now, or why the pinned version still runs."),
+});
+export const ExtensionDevClearedSchema = z.object({
+    id: extensionId.describe("Its connection id."),
+    name: z.string().describe("Its manifest id, publisher.name."),
+    cleared: z.boolean().describe("Whether it was pointed at a checkout. False means it already ran its pinned version and nothing changed."),
+});
+export const ExtensionDevListSchema = z.object({
+    extensions: z
+        .array(
+            z.object({
+                id: extensionId.describe("Its connection id."),
+                name: z.string().describe("Its manifest id, publisher.name."),
+                commit: z.string().describe("The pinned commit, in full."),
+                dev: ExtensionDevSchema.optional().describe("Present while it is pointed at a source checkout."),
+                checkout: z
+                    .object({
+                        path: z.string().describe("Relative to the workspace, or to the conversation's copy of it when `conversation` is set."),
+                        conversation: z.string().optional().describe("Set when the calling conversation's own copy is the one found."),
+                    })
+                    .optional()
+                    .describe(
+                        "A checkout of its source repository in the workspace, which is where a change to it belongs. Absent when the workspace has none.",
+                    ),
+            }),
+        )
+        .describe("Every extension installed from a repository. Built-in and workspace extensions are not here: they already run from their source."),
+});
 // Read by both the Extensions tab and an authoring agent off GET /extensions.
 export const InvalidWorkspaceExtensionSchema = z.object({
     dir: z.string().describe("Which folder."),

package/src/schemas/git/git.ts

@@ -13,6 +13,10 @@ import { RepoParamSchema } from "../shared.js";
 export const GitDiffSideSchema = z.enum(["staged", "unstaged", "conflicted"]);
 export type GitDiffSide = z.infer<typeof GitDiffSideSchema>;
 
+// The origin that names the files no conversation landed: the owner's own edits, a terminal's, anything unattributed.
+// Not a conversation id, so no session uuid can collide with it.
+export const UNATTRIBUTED_ORIGIN = "yours";
+
 // What a bulk git action applies to, never simply a list of paths (unbounded, unlike a review's rows).
 // paths: exactly these, from a list a browser already drew.
 // scope: a description the daemon resolves against live status, so nothing here can be stale.
@@ -26,7 +30,9 @@ export const GitScopeSchema = z.object({
         .string()
         .min(1)
         .optional()
-        .describe("Narrow to the files one conversation landed. Leave it out for everyone's, including your own edits."),
+        .describe(
+            `Narrow to the files one conversation landed, or "${UNATTRIBUTED_ORIGIN}" for the files none landed. Leave it out for everyone's, including your own edits.`,
+        ),
 });
 export type GitScope = z.infer<typeof GitScopeSchema>;
 
@@ -135,15 +141,19 @@ export const RepoTargetSchema = z
     .extend(GitTargetSchema.shape)
     .refine(oneTarget, ONE_TARGET);
 export type RepoTarget = z.infer<typeof RepoTargetSchema>;
+// Git's vocabulary for what happened to a file, the one every change list, diff tab and status letter reads. Conflicted is
+// git's unmerged state (`U`), not a kind of modification.
+export const ChangeStatusSchema = z.enum(["added", "modified", "deleted", "renamed", "type-changed", "conflicted"]);
+export type ChangeStatus = z.infer<typeof ChangeStatusSchema>;
 // One change to a file: an uncommitted working-tree change, an agent worktree's delta vs its base, or a file in a
 // commit. `additions`/`deletions` are numstat counts, absent for binary or untracked files.
 export const GitChangeSchema = z.object({
     // Forward slashes; for a rename this is the new path (`from` holds the old one).
     path: z.string().describe("The path, relative to the repository root. For a rename this is the new one."),
     // Git's unmerged state (`U`): stages 2/3 hold "ours"/"theirs", no stage 0 to commit.
-    status: z
-        .enum(["added", "modified", "deleted", "renamed", "type-changed", "conflicted"])
-        .describe("What happened to it. Conflicted is not a kind of edit: nothing can be committed anywhere in the repository while one exists."),
+    status: ChangeStatusSchema.describe(
+        "What happened to it. Conflicted is not a kind of edit: nothing can be committed anywhere in the repository while one exists.",
+    ),
     from: z.string().optional().describe("Where a renamed file came from."),
     additions: z
         .number()
@@ -208,6 +218,7 @@ export const GitBranchesSchema = z.object({
         .array(GitRemoteBranchSchema)
         .describe("Branches on its remotes, as last seen. Sent together with the locals so a switcher never draws a half-filled list."),
 });
+export type GitBranches = z.infer<typeof GitBranchesSchema>;
 // Creates at `start` (sha or ref; absent means HEAD); `checkout` switches to it immediately.
 export const GitBranchCreateAtSchema = RepoParamSchema.extend({
     name: RefNameSchema.describe("The new branch's name."),

package/src/schemas/history.ts

@@ -24,6 +24,7 @@ export interface SnapshotTurn {
     readonly index: number;
 }
 export const SnapshotsListSchema = z.object({ snapshots: z.array(SnapshotSchema).describe("Every point you can go back to, newest first.") });
+export type SnapshotsList = z.infer<typeof SnapshotsListSchema>;
 // Restores the workspace to that turn's checkpoint, drops every message after it, and forgets the provider session so
 // the next turn opens fresh. `messageId` is what makes `index` safe to act on: a position is only as current as the
 // transcript it was read from.
@@ -65,6 +66,7 @@ export type SnapshotChange = z.infer<typeof SnapshotChangeSchema>;
 export const SnapshotDiffSchema = z.object({
     changes: z.array(SnapshotChangeSchema).describe("Everything that differs between this saved point and the one before it."),
 });
+export type SnapshotDiff = z.infer<typeof SnapshotDiffSchema>;
 export const SnapshotFileDiffQuerySchema = z.object({
     id: z.string().min(1).describe("Which saved point."),
     scope: z.string().min(1).describe("Which part of the workspace the path belongs to."),

package/src/schemas/hosts.ts

@@ -20,6 +20,22 @@ export const MachineIdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{7,1
 export const derivedMachineId = (card: string): string => `card:${card}`;
 export const isDerivedMachineId = (machineId: string): boolean => machineId.startsWith("card:");
 
+// How many skipped lines an agent sends in its upkeep summary at most; the counts cover the rest.
+export const UPKEEP_SKIPPED_SHOWN = 10;
+
+// What the machine agent's own upkeep found in this environment at its last pass (its device reconciler, run at start
+// and every six hours): how many leftovers of each kind it found and how many it put right, and the first
+// UPKEEP_SKIPPED_SHOWN of those it left, each with why. Kinds are the agent's words (`retired-files`, `trash`,
+// `login-entry`…), read as strings, so a kind a newer agent adds is one more key rather than a facts row that fails to
+// parse; for the same reason the cap on `skipped` is the sender's, not checked here. `at` is epoch ms.
+export const DeviceUpkeepSchema = z.object({
+    at: z.number(),
+    found: z.record(z.string(), z.number()),
+    fixed: z.record(z.string(), z.number()),
+    skipped: z.array(z.object({ kind: z.string(), what: z.string(), why: z.string() })),
+});
+export type DeviceUpkeep = z.infer<typeof DeviceUpkeepSchema>;
+
 // 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({
@@ -57,6 +73,9 @@ export const DeviceFactsSchema = z.object({
     // 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(),
+    // The agent's last upkeep pass in this environment (DeviceUpkeepSchema): whether a release brought this machine to
+    // the current shape, read rather than assumed. Absent before the first pass, and from an agent older than the field.
+    upkeep: DeviceUpkeepSchema.optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 
@@ -75,13 +94,16 @@ export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 // - `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"]);
+// - `project-delivery`: the `deliverProject` procedure, landed work written into a folder attached to this computer's
+//   sandbox (project-delivery.ts); an agent without it is never sent one, and the land waits for Bring back.
+export const DeviceFeatureSchema = z.enum(["reshape-later", "set-shape", "rollback-to", "loopback-catch", "background-prepare", "project-delivery"]);
 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";
+export const DEVICE_FEATURE_PROJECT_DELIVERY: DeviceFeature = "project-delivery";
 // 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/loopback-catch.ts

@@ -17,7 +17,8 @@ export const LoopbackCatchSchema = object({
     port: number().int().min(1).max(65535),
     // The path only, leading slash included; the query is the grant and is never matched.
     path: string().startsWith("/"),
-    // Epoch ms; a catcher stops watching by itself here even if nobody aborts the stream.
+    // Epoch ms; a catcher stops watching by itself here even if nobody aborts the stream, and never later than
+    // LOOPBACK_CATCH_LONGEST_MS after it starts, however far away this is.
     expiresAt: number(),
     // Who the page thanks once the browser lands ("Claude"), so the tab says what just happened.
     title: string().min(1),
@@ -34,6 +35,10 @@ export const LoopbackCatchEventSchema = discriminatedUnion("type", [
 ]);
 export type LoopbackCatchEvent = z.infer<typeof LoopbackCatchEventSchema>;
 
+// The longest any catcher watches, whatever `expiresAt` asks: a forgotten catch must not hold a port (a device) or a
+// tab listener (a browser) for as long as a sandbox happened to ask. Both peers apply it, through `watchQueue`.
+export const LOOPBACK_CATCH_LONGEST_MS = 30 * 60_000;
+
 // Advertised in a device's `features` and a browser's facts; only a peer that says it is asked.
 export const LOOPBACK_CATCH_FEATURE = "loopback-catch";
 

package/src/schemas/maintenance.ts

@@ -8,6 +8,13 @@ import { WorkspaceHotspotSchema, WorkspaceKeyModuleSchema } from "./codebase-hea
 export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd", "ui", "bundle", "mutation"] as const;
 export const ProbeIdSchema = z.enum(PROBE_IDS);
 export type ProbeId = z.infer<typeof ProbeIdSchema>;
+// Absent for the repo's own pnpm workspace, so every finding recorded before this field existed still reads right.
+const StandaloneSchema = z
+    .string()
+    .optional()
+    .describe(
+        "The folder that declares it, when that folder is a package the pnpm workspace leaves out and installs on its own (the iOS shell, built with npm on a Mac). The fix goes in that folder's package.json, not the workspace catalog.",
+    );
 // `kind` is the semver distance; that's why this isn't collapsed to one number.
 export const OutdatedPackageSchema = z.object({
     name: z.string().describe("The dependency."),
@@ -22,6 +29,7 @@ export const OutdatedPackageSchema = z.object({
     section: z
         .string()
         .describe("Which part of the manifest declares it. A major version behind on a build-time tool is a different risk from one that ships."),
+    standalone: StandaloneSchema,
 });
 export type OutdatedPackage = z.infer<typeof OutdatedPackageSchema>;
 export const AdvisorySchema = z.object({
@@ -39,6 +47,7 @@ export const AdvisorySchema = z.object({
             "Which versions fix it. Absent means no fix has been published, which is exactly when nothing should offer to upgrade and something should say so instead.",
         ),
     dev: z.boolean().describe("Whether it only reaches build-time tooling, which is a different problem from one that reaches what you ship."),
+    standalone: StandaloneSchema,
 });
 export type Advisory = z.infer<typeof AdvisorySchema>;
 // A stale sample could send the agent chasing files already gone; it re-runs knip live anyway.

package/src/schemas/members.ts

@@ -0,0 +1,33 @@
+// members: the daemon's shared-access roster (GET/POST/DELETE /members), who besides the owner reaches this sandbox
+import { z } from "zod";
+import { GrantedRoleSchema } from "./shared.js";
+
+// One person on the roster as the daemon answers it. `areas` fences what of the workspace they reach, and with it which
+// assistants they may talk to: absent is the whole workspace, empty is nothing.
+export const MemberSchema = z.object({
+    email: z.string().describe("Who, lowercased."),
+    role: GrantedRoleSchema.describe("The tier they were granted."),
+    areas: z.array(z.string()).optional().describe("The areas they are fenced to. Absent means the whole workspace."),
+});
+export type Member = z.infer<typeof MemberSchema>;
+
+// What every roster write answers: the roster after it.
+export const MembersListSchema = z.object({ members: z.array(MemberSchema) });
+export type MembersList = z.infer<typeof MembersListSchema>;
+
+// GET /members: the roster, plus the owner, an identity fact the roster file never holds. Absent before the first
+// sign-in, on a loopback or test daemon.
+export const MembersRosterSchema = MembersListSchema.extend({ owner: z.string().optional() });
+export type MembersRoster = z.infer<typeof MembersRosterSchema>;
+
+// POST /members: a grant is a role decision, so the role is required. Areas are optional, their absence being the whole
+// workspace; a writer and a guest are refused without them, since for those two tiers the fence is the tier.
+export const MemberGrantSchema = z.object({
+    email: z.string(),
+    role: GrantedRoleSchema,
+    areas: z.array(z.string().min(1)).max(20).optional(),
+});
+export type MemberGrant = z.infer<typeof MemberGrantSchema>;
+
+// DELETE /members: whose access to take back.
+export const MemberEmailSchema = z.object({ email: z.string() });

package/src/schemas/metrics.ts

@@ -64,6 +64,14 @@ export const MemoryRoomSchema = z.object({
     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."),
+    stallSustainedPercent: z
+        .number()
+        .optional()
+        .describe("Percent of the last minute in which everything in the sandbox waited on memory. Absent from a daemon that predates it."),
+    stallSustainedLimitPercent: z
+        .number()
+        .optional()
+        .describe("The minute's stall at or past which the sandbox counts as short of memory. Absent from a daemon that predates it."),
 });
 export type MemoryRoom = z.infer<typeof MemoryRoomSchema>;
 
@@ -76,14 +84,24 @@ export const SandboxUsageSchema = z.object({
     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.",
+            "Memory counted against the limit, as the daemon admits work by it: resident memory less the file cache the kernel takes back on demand, and once swap is full (`swapFull`) what was pushed to swap as well.",
         ),
     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."),
+    swapBytes: z
+        .number()
+        .optional()
+        .describe(
+            "What was pushed out to swap, counted in `memoryBytes` only once swap is full. Absent where the sandbox cannot see its own memory.",
+        ),
+    swapLimitBytes: z.number().optional().describe("What swap can hold. Absent where nothing bounds it, and from a daemon that predates it."),
+    swapFull: z
+        .boolean()
+        .optional()
+        .describe("Swap is nearly at `swapLimitBytes`: nothing more can be parked there, so what is swapped counts against the limit too."),
     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."),
@@ -233,7 +251,7 @@ export const StorageScanSchema = z.object({
 export type StorageScan = z.infer<typeof StorageScanSchema>;
 
 export const StorageReportSchema = z.object({
-    scan: StorageScanSchema.optional().describe("The last scan that finished. Absent until one has, and again after the daemon restarts."),
+    scan: StorageScanSchema.optional().describe("The last scan that finished, kept across restarts; its `finishedAt` says how old it is. Absent until one has."),
     scanning: z.boolean().describe("Whether a scan is running now."),
 });
 export type StorageReport = z.infer<typeof StorageReportSchema>;

package/src/schemas/needs.ts

@@ -1,12 +1,17 @@
 import { z } from "zod";
+import { AutomationSchema } from "./automations.js";
 
 // A need: something an agent cannot finish its task without that only a person can provide (a connection, a secret's
 // value, wider reach, a tool in the image). Unlike a parked card it outlives the turn that raised it: the sandbox keeps
 // it until someone answers, draws it wherever it is waiting, and wakes the conversation when it is met
 // (docs/architecture/needs.md). Every word on a need is the daemon's except `why`, the agent's own case.
 
-export const NEED_KINDS = ["capability", "secret", "grant", "release", "environment"] as const;
-export const NeedKindSchema = z.enum(NEED_KINDS).describe("What is being asked for: a connection, a secret's value, wider reach, a gated credential, or a tool in the image.");
+export const NEED_KINDS = ["capability", "secret", "grant", "release", "environment", "automation"] as const;
+export const NeedKindSchema = z
+    .enum(NEED_KINDS)
+    .describe(
+        "What is being asked for: a connection, a secret's value, wider reach, a gated credential, a tool in the image, or an automation to run unattended.",
+    );
 export type NeedKind = z.infer<typeof NeedKindSchema>;
 
 // `working` is a yes still being carried out: a connection whose form is open, an overlay approved but not yet built.
@@ -117,8 +122,33 @@ export const EnvironmentNeedSchema = z.object({
 });
 export type EnvironmentNeed = z.infer<typeof EnvironmentNeedSchema>;
 
+// What its check sees today, run once as the automation was proposed, so the person deciding reads the watch working
+// rather than a promise that it would. Absent for a guard command, which the agent ran itself before asking: run here
+// it would carry the proposed persona's credentials before anyone approved them.
+export const AutomationFirstCheckSchema = z.object({
+    pass: z.boolean().describe("Whether the check passes today, which for a watch waiting on one thing means it would fire at once."),
+    saw: z.string().describe("What it saw, or what it is still waiting for."),
+    at: z.number().describe("When it ran, in milliseconds."),
+});
+export type AutomationFirstCheck = z.infer<typeof AutomationFirstCheckSchema>;
+
+export const AutomationNeedSchema = z.object({
+    kind: z.literal("automation"),
+    automation: AutomationSchema.describe("The automation as it would be saved, switched on, the moment a person approves it."),
+    replaces: z.boolean().optional().describe("An automation of this id already exists, and approving replaces it."),
+    firstCheck: AutomationFirstCheckSchema.optional(),
+});
+export type AutomationNeed = z.infer<typeof AutomationNeedSchema>;
+
 export const NeedSubjectSchema = z
-    .discriminatedUnion("kind", [CapabilityNeedSchema, SecretNeedSchema, GrantNeedSchema, ReleaseNeedSchema, EnvironmentNeedSchema])
+    .discriminatedUnion("kind", [
+        CapabilityNeedSchema,
+        SecretNeedSchema,
+        GrantNeedSchema,
+        ReleaseNeedSchema,
+        EnvironmentNeedSchema,
+        AutomationNeedSchema,
+    ])
     .describe("What exactly is asked for.");
 export type NeedSubject = z.infer<typeof NeedSubjectSchema>;
 
@@ -164,6 +194,9 @@ export const NeedAskSchema = z.discriminatedUnion("kind", [
     }),
     z.object({ kind: z.literal("release"), subject: z.string().min(1) }),
     z.object({ kind: z.literal("environment"), tool: z.string().min(1).max(64), steps: z.string().min(1).max(20_000) }),
+    // Everything the agent proposes, switched on; the daemon checks it as the Automations page would save it, runs a
+    // source's check once for the card, and saves it only on a person's approval.
+    z.object({ kind: z.literal("automation"), automation: AutomationSchema }),
 ]);
 export type NeedAsk = z.infer<typeof NeedAskSchema>;
 

package/src/schemas/offload.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/runner-protocol.js";
+import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/doors/runner-protocol.js";
 
 // OFFLOADED WORK, as the in-sandbox `offload-run` command and the editor see it (settings `offload`): a heavy line this
 // sandbox hands a runner on one of the owner's machines instead of running it itself.

package/src/schemas/peer-enrollment.ts

@@ -0,0 +1,14 @@
+// Named imports rather than the `z` namespace: this module is bundled into the browser extension (through the
+// `./webext` entry), where the namespace keeps zod's locales. _devices/webext/scripts/size-budget.mjs holds the ceiling.
+import { object, string } from "zod";
+import type * as z from "zod";
+
+// What POST /system/<door>/enroll answers once it redeems a pairing (peers/peer-routes.ts): the id the pairing was bound
+// to and the durable token the peer presents from then on. A door may add fields of its own beside them; a reader
+// needs only these two. A 401 is the expired-or-spent pairing, a 5xx a sandbox not ready yet. The sync key's door is
+// a different route with its own answer (SyncEnrollmentAnswerSchema in devices.ts).
+export const PeerEnrollmentAnswerSchema = object({
+    id: string(),
+    token: string().min(1),
+});
+export type PeerEnrollmentAnswer = z.infer<typeof PeerEnrollmentAnswerSchema>;