@intentic/sandbox-contract 1.330.0 → 1.332.0

package/src/schemas/git/git-scope.ts

@@ -0,0 +1,71 @@
+import { type GitChange, type GitDiffSide, type GitScope, UNATTRIBUTED_ORIGIN } from "./git.js";
+
+// What a scope names, resolved against a repository's own status. One definition, read by the daemon when it acts on a
+// scope and by the Changes panel when it asks the owner about one, so the question and the action cannot disagree.
+// Sides are the verb's, not the scope's: staging reads the two not yet in the index; a scope narrows, never widens.
+
+export interface ChangedSides {
+    readonly conflicted: readonly GitChange[];
+    readonly staged: readonly GitChange[];
+    readonly unstaged: readonly GitChange[];
+}
+
+// Who landed each path, newest first, as `RepoChanges.origins` ships it; a rename's old path is keyed too.
+export type ChangeOrigins = Readonly<Record<string, readonly string[]>>;
+
+// What each verb can move; `git add` on an unmerged path settles a merge, so conflicts are stageable too.
+export const STAGEABLE_SIDES: readonly GitDiffSide[] = ["unstaged", "conflicted"];
+export const UNSTAGEABLE_SIDES: readonly GitDiffSide[] = ["staged"];
+// Discard rewrites the worktree, which every side has one of.
+export const DISCARDABLE_SIDES: readonly GitDiffSide[] = ["conflicted", "staged", "unstaged"];
+
+// The paths one row stands for on disk: a rename is two, and no verb acts on half a move.
+export const legsOf = (change: Pick<GitChange, "path" | "from">): readonly string[] =>
+    change.from === undefined ? [change.path] : [change.path, change.from];
+
+// Every conversation that landed either leg of a row, newest first per leg, each once.
+export const originsOfChange = (change: Pick<GitChange, "path" | "from">, origins: ChangeOrigins): readonly string[] => [
+    ...new Set(legsOf(change).flatMap((path) => origins[path] ?? [])),
+];
+
+// Whether a row is that origin's work: a conversation that landed either leg of it, or for the unattributed origin a row
+// no conversation landed any leg of. A rename out of an agent's file is the agent's row, whoever renamed it, so the
+// panel counts it, the scope moves it and the discard question names it under the same chip.
+export const changeIsFrom = (change: Pick<GitChange, "path" | "from">, origin: string, origins: ChangeOrigins): boolean => {
+    const ids = originsOfChange(change, origins);
+    return origin === UNATTRIBUTED_ORIGIN ? ids.length === 0 : ids.includes(origin);
+};
+
+// Paths a scope resolves to, for a verb that moves `sides`; both legs of a rename included.
+// Deduplicated: a path staged and edited again is two rows over one file, and a rename's legs can be named twice.
+export const scopedPaths = (changed: ChangedSides, sides: readonly GitDiffSide[], scope: GitScope, origins: ChangeOrigins = {}): readonly string[] => {
+    const origin = scope.origin;
+    const reading = scope.side === undefined ? sides : sides.filter((side) => side === scope.side);
+    const rows = reading.flatMap((side) => changed[side]);
+    const named = origin === undefined ? rows : rows.filter((change) => changeIsFrom(change, origin, origins));
+    return [...new Set(named.flatMap(legsOf))];
+};
+
+// A scope that narrows nothing is the whole repository; two of the three verbs say so to git directly, unenumerated.
+export const isWholeRepo = (scope: GitScope): boolean => scope.side === undefined && scope.origin === undefined;
+
+// What discarding `paths` does to each, read off the same status: a path the last commit does not hold leaves the disk
+// (an untracked file, a staged new file, a rename's new leg), every other returns to its committed state. Mirrors the
+// daemon's discard, which unstages first and then cleans what reads untracked.
+export const discardOutcome = (changed: ChangedSides, paths: readonly string[]): { readonly deletes: readonly string[]; readonly restores: readonly string[] } => {
+    const notInHead = new Set<string>();
+    for (const change of changed.staged) {
+        if (change.status === "added" || (change.status === "renamed" && change.from !== undefined)) {
+            notInHead.add(change.path);
+        }
+    }
+    // Untracked, unless the index deleted it from the last commit: that path is in HEAD and comes back.
+    const indexDeleted = new Set(changed.staged.filter((change) => change.status === "deleted").map((change) => change.path));
+    for (const change of changed.unstaged) {
+        if (change.status === "added" && !indexDeleted.has(change.path)) {
+            notInHead.add(change.path);
+        }
+    }
+    const unique = [...new Set(paths)];
+    return { deletes: unique.filter((path) => notInHead.has(path)), restores: unique.filter((path) => !notInHead.has(path)) };
+};

package/src/schemas/git/git.ts

@@ -78,9 +78,23 @@ export const DiscardSchema = RepoParamSchema.extend(GitTargetSchema.shape)
     .refine(oneTarget, ONE_TARGET);
 // Index-only moves; nothing on disk changes, so neither needs a checkpoint. An empty target means the whole repository
 // (`git add -A`, or the entire index).
+// `chip` is the reversible form of an origin's move (the Changes panel's origin chips): staging records what the index
+// held at every path it moves, and unstaging the same chip writes exactly that back, so a partial `git add -p` or a
+// merge's clean result survives one on/off. It names its own target, so it goes alone.
+const oneIndexMove = (move: GitTarget & { readonly chip?: string | undefined }): boolean =>
+    oneTarget(move) && (move.chip === undefined || (move.paths === undefined && move.scope === undefined));
 export const GitIndexMoveSchema = RepoParamSchema.extend(GitTargetSchema.shape)
+    .extend({
+        chip: z
+            .string()
+            .min(1)
+            .optional()
+            .describe(
+                `Stage one origin's unstaged files (a conversation id, or "${UNATTRIBUTED_ORIGIN}" for the files none landed) so the move can be taken back exactly: unstaging with the same value later restores what the index held at each of those paths before, partial staging included, and leaves alone any path staged differently since or a commit that already took them. Goes without paths or a scope.`,
+            ),
+    })
     .describe("What to move across the index. Nothing on disk changes either way.")
-    .refine(oneTarget, ONE_TARGET);
+    .refine(oneIndexMove, { message: "name paths, a scope or a chip, not more than one" });
 // No separate "set upstream" flag: the daemon runs `push -u` exactly when the branch has none yet, which is never
 // destructive.
 export const PushSchema = RepoParamSchema.extend({

package/src/schemas/hosts.ts

@@ -76,6 +76,13 @@ export const DeviceFactsSchema = z.object({
     // 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(),
+    // How the agent before this one ended, as one sentence (watchdog kill, crash, update, reboot), so a device that
+    // dropped off says why once it is back. Absent on a first start, and from an agent older than the field.
+    previousExit: z.string().optional(),
+    // Which ic answers on this machine and what steers it: an old ic.exe installed from a leftover IC_URL looked like
+    // a daemon bug for an afternoon. Override values are the agent's own redaction (secret-looking ones by length).
+    ic: z.object({ path: z.string(), version: z.string(), modified: z.string().optional() }).optional(),
+    icOverrides: z.array(z.string()).optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 

package/src/schemas/keep-warm.ts

@@ -88,7 +88,8 @@ export const PromptCacheOpeningSchema = z.object({
 });
 export type PromptCacheOpening = z.infer<typeof PromptCacheOpeningSchema>;
 
-const tokensLabel = (tokens: number): string => (tokens >= 1_000 ? `${Math.round(tokens / 1_000)}k` : String(tokens));
+/** A token count as the transcript words it: "305k", or the bare count under a thousand. */
+export const tokensLabel = (tokens: number): string => (tokens >= 1_000 ? `${Math.round(tokens / 1_000)}k` : String(tokens));
 
 const spanLabel = (ms: number): string => {
     const minutes = Math.max(1, Math.round(ms / 60_000));

package/src/schemas/logs.ts

@@ -52,10 +52,35 @@ export const ClientDiagnosticSchema = z.object({
         .describe("Whatever else was worth keeping."),
 });
 export type ClientDiagnostic = z.infer<typeof ClientDiagnosticSchema>;
+// Which page a batch came from, said once per batch rather than on every event. Without it two tabs' reports read as
+// one stream, and an agent spent dozens of calls learning a page was the owner's own dev server rather than the build
+// it had just changed.
+export const ClientPageSchema = z.object({
+    pageId: z.string().min(1).max(64).describe("This page load's own id: every report from one load shares it, and a reload gets a new one."),
+    tabId: z.string().max(64).optional().describe("The browser tab's id, which a reload of the same tab keeps."),
+    userAgent: z.string().max(300).optional().describe("The browser's own description of itself."),
+    viewport: z.string().max(40).optional().describe("The window's size in CSS pixels and its pixel ratio, e.g. 390x844@3."),
+    // The join key into PostHog's session replay: absent where analytics is off (dev, self-hosted) or not loaded yet.
+    replay: z.string().max(100).optional().describe("The PostHog session id, whose replay shows what the person did."),
+    origin: z.string().max(200).optional().describe("The address the page was loaded from."),
+    served: z
+        .string()
+        .max(300)
+        .optional()
+        .describe("How the page was served: `dev` (a Vite dev server, with the checkout, branch and who started it), `desktop` (the installed app, with its version), `local` (a window on a folder) or `hosted`."),
+    commit: z
+        .string()
+        .max(40)
+        .optional()
+        .describe("The short commit the page's build was made from (a dev server's: the one it started on). Absent where the build could not read it."),
+});
+export type ClientPage = z.infer<typeof ClientPageSchema>;
 // Capped batch: the client already coalesces and drops its own side, and an unbounded array here is a way to fill a
 // disk with one request.
 export const ClientDiagnosticsReportSchema = z.object({
     events: z.array(ClientDiagnosticSchema).min(1).max(50).describe("What the browser has to report, oldest first."),
+    // Optional: a page from before it sends none.
+    page: ClientPageSchema.optional().describe("Which page load sent the batch."),
 });
 export type ClientDiagnosticsReport = z.infer<typeof ClientDiagnosticsReportSchema>;
 export const ClientDiagnosticsAcceptedSchema = z.object({

package/src/schemas/metrics.test.ts

@@ -0,0 +1,80 @@
+import { type SandboxMetrics, SandboxMetricsSchema } from "./metrics.js";
+
+// A daemon payload from before memoryBreakdown and the other optional accounting fields existed.
+const legacyMetrics = {
+    at: 1_000_000,
+    sandbox: {
+        cores: 2,
+        memoryBytes: 7 * 2 ** 30,
+        memoryLimitBytes: 16 * 2 ** 30,
+        loadAverage: [1.5, 1.25, 1],
+        processes: 3,
+    },
+    daemon: { rssBytes: 300 * 2 ** 20, heapUsedBytes: 120 * 2 ** 20 },
+    sessions: { "conv-a": { processes: 2, rssBytes: 400 * 2 ** 20 } },
+    roles: {
+        agentRuntime: { processes: 1, rssBytes: 300 * 2 ** 20 },
+        terminal: { processes: 1, rssBytes: 100 * 2 ** 20 },
+    },
+} satisfies SandboxMetrics;
+
+describe("the metrics memory accounting contract", () => {
+    test("an older payload parses unchanged without the optional breakdown or its categories", () => {
+        const parsed = SandboxMetricsSchema.parse(legacyMetrics);
+        expect(parsed).toEqual(legacyMetrics);
+        expect(Object.hasOwn(parsed.sandbox, "memoryBreakdown")).toBe(false);
+    });
+
+    test("a partial new breakdown preserves zero and leaves unmeasured categories absent", () => {
+        const payload = {
+            ...legacyMetrics,
+            sandbox: {
+                ...legacyMetrics.sandbox,
+                memoryBreakdown: { anonymousBytes: 0, inactiveFileCacheBytes: 3 * 2 ** 30 },
+            },
+        };
+        expect(SandboxMetricsSchema.parse(payload)).toEqual(payload);
+    });
+
+    test("each category is independently optional, with no zero defaults for the others", () => {
+        for (const memoryBreakdown of [
+            {},
+            { anonymousBytes: 0 },
+            { countedFileCacheBytes: 0 },
+            { kernelBytes: 0 },
+            { inactiveFileCacheBytes: 0 },
+        ]) {
+            const payload = { ...legacyMetrics, sandbox: { ...legacyMetrics.sandbox, memoryBreakdown } };
+            expect(SandboxMetricsSchema.parse(payload)).toEqual(payload);
+        }
+    });
+
+    test("measured resident categories remain separate from a headline that also counts full swap", () => {
+        const payload = {
+            ...legacyMetrics,
+            sandbox: {
+                ...legacyMetrics.sandbox,
+                memoryBytes: 16.5 * 2 ** 30,
+                swapBytes: 9.5 * 2 ** 30,
+                swapLimitBytes: 10 * 2 ** 30,
+                swapFull: true,
+                memoryBreakdown: {
+                    anonymousBytes: 5 * 2 ** 30,
+                    countedFileCacheBytes: 2 ** 30,
+                    kernelBytes: 2 ** 30,
+                    inactiveFileCacheBytes: 3 * 2 ** 30,
+                },
+            },
+        };
+        expect(SandboxMetricsSchema.parse(payload)).toEqual(payload);
+    });
+
+    test("present categories must be byte numbers, not numeric strings or non-finite values", () => {
+        for (const field of ["anonymousBytes", "countedFileCacheBytes", "kernelBytes", "inactiveFileCacheBytes"]) {
+            for (const invalid of ["0", null, Number.NaN, Number.POSITIVE_INFINITY]) {
+                const payload = { ...legacyMetrics, sandbox: { ...legacyMetrics.sandbox, memoryBreakdown: { [field]: invalid } } };
+                expect(SandboxMetricsSchema.safeParse(payload).success).toBe(false);
+            }
+        }
+    });
+});

package/src/schemas/metrics.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 // What the sandbox is using right now, measured only when asked (GET /system/metrics). CPU percentages are of ONE core
-// unless the field says otherwise; memory is resident bytes.
+// unless the field says otherwise; memory is in bytes, with admission accounting and process RSS distinguished below.
 
 // The kinds of process a sandbox runs, as the daemon classifies them by command line.
 export const PROCESS_ROLES = [
@@ -30,7 +30,7 @@ export const ProcessGroupMetricsSchema = z.object({
     rssBytes: z
         .number()
         .describe(
-            "Their resident memory added up, in bytes. Memory two processes share is counted in each, so this can exceed what they cost together.",
+            "Their process resident memory (RSS) added up, in bytes, including file mappings and shared pages counted once per process. This can exceed what they cost together. It excludes unmapped file cache, kernel memory and swapped-out pages.",
         ),
 });
 export type ProcessGroupMetrics = z.infer<typeof ProcessGroupMetricsSchema>;
@@ -84,24 +84,46 @@ export const SandboxUsageSchema = z.object({
     memoryBytes: z
         .number()
         .describe(
-            "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.",
+            "Memory counted against the limit, as the daemon admits work by it: the cgroup's resident charge, including the daemon, kernel memory and file cache except inactive_file, plus swapped bytes only when swap is nearly full (`swapFull`). Falls back to the machine's used memory when the budget cannot measure it.",
         ),
     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.",
         ),
+    memoryBreakdown: z
+        .object({
+            anonymousBytes: z.number().optional().describe("Anonymous resident memory charged to the cgroup (memory.stat anon), in bytes."),
+            countedFileCacheBytes: z
+                .number()
+                .optional()
+                .describe("File cache counted in resident usage (memory.stat file less inactive_file), in bytes. Absent unless both counters are valid."),
+            kernelBytes: z
+                .number()
+                .optional()
+                .describe("Kernel memory charged to the cgroup (memory.stat kernel), in bytes. Absent on kernels without that aggregate."),
+            inactiveFileCacheBytes: z
+                .number()
+                .optional()
+                .describe("Inactive file cache (memory.stat inactive_file), in bytes, excluded from memoryBytes."),
+        })
+        .optional()
+        .describe(
+            "Approximate measured memory.stat categories, not an RSS subtraction or an exact sum of memoryBytes: admission is sampled separately and may also count swap. Missing or invalid categories are omitted, not zero. Absent without cgroup memory, on machine-memory fallback, when no category is valid, and from older daemons.",
+        ),
     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.",
+            "What was pushed out to swap, counted in `memoryBytes` only when swap is nearly full under admission policy. 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."),
+        .describe(
+            "Swap has reached the admission policy's nearly-full threshold against `swapLimitBytes`, so swapped bytes count against the memory limit too, even if swap space remains.",
+        ),
     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."),
@@ -114,7 +136,7 @@ export const SandboxUsageSchema = z.object({
         .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."),
+    processes: z.number().describe("How many processes are running in the sandbox, including the daemon."),
     pressure: PressureMetricsSchema.optional().describe(
         "How much work waited on CPU, memory or disk lately. Absent where the kernel does not report it.",
     ),
@@ -140,12 +162,12 @@ export const SandboxMetricsSchema = z.object({
         .number()
         .optional()
         .describe("How long the CPU figures were measured over, in milliseconds. Absent on a first reading, and then so is every CPU figure."),
-    sandbox: SandboxUsageSchema.describe("The sandbox as a whole."),
-    daemon: DaemonUsageSchema.describe("The daemon that runs it, which none of the other figures include."),
+    sandbox: SandboxUsageSchema.describe("The sandbox as a whole, including the daemon."),
+    daemon: DaemonUsageSchema.describe("The daemon's own usage, included in the sandbox total and process count but excluded from roles and session sums."),
     sessions: z
         .record(z.string(), SessionMetricsSchema)
         .describe(
-            "What each conversation's processes use, by conversation id: the agent's own process and everything it started. Only conversations with processes running, and only those the caller may see.",
+            "What each conversation's processes use, by conversation id: the agent's own process and everything it started, excluding the daemon. These group many of the same process readings as roles, not additional memory. Only conversations with processes running, and only those the caller may see.",
         ),
     roles: z
         .partialRecord(ProcessRoleSchema, ProcessGroupMetricsSchema)

package/src/schemas/needs.ts

@@ -57,6 +57,13 @@ export type CapabilityNeed = z.infer<typeof CapabilityNeedSchema>;
 // The alphabet a `{{secret:NAME}}` reference resolves; a pasted value is stored under exactly this name.
 export const SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 
+// A `{{secret:name}}` reference wherever it stands in text, capturing the name. Wider than SECRET_NAME, since a
+// reference also names the other stores' entries (`<capability>/<field>`). Not global, so a shared instance carries no
+// `lastIndex` between callers: a site that replaces or spans every one derives its own /g copy from it. The terminal
+// filter (@intentic/output-cleaners, builtins only) keeps a copy, pinned to this one by the daemon's
+// src/secrets/terminal-masking-parity.test.ts.
+export const SECRET_REFERENCE = /\{\{secret:([A-Za-z0-9_./-]+)\}\}/;
+
 export const SecretNeedSchema = z.object({
     kind: z.literal("secret"),
     name: z.string().regex(SECRET_NAME).describe("The name it is stored under, and what `{{secret:NAME}}` will resolve."),
@@ -283,6 +290,16 @@ export const AgentNeedSchema = z.object({
 });
 export type AgentNeed = z.infer<typeof AgentNeedSchema>;
 
+// A credential gateway card's "Allow requests like this with <name> in this conversation": the `ask` rule it answered
+// stops asking that conversation, until somebody takes it back. Kept by the rule's own content, so editing the rule
+// asks again.
+export const BrokerRulePassSchema = z.object({
+    capability: z.string().describe("The capability whose rule asked, by id."),
+    rule: z.string().describe("The rule's own identity (its content), so an edited rule is a different one and asks again."),
+    said: z.string().describe('The request in a person\'s words, as the card put it: "GET api.github.com/repos/x with GitHub".'),
+});
+export type BrokerRulePass = z.infer<typeof BrokerRulePassSchema>;
+
 // What a person allowed one conversation beyond its persona and area, from a grant need's card
 // (personas/conversation-grants.ts). Honoured from that conversation's next turn on, and revocable on the Grants page.
 export const ConversationGrantSchema = z.object({
@@ -306,6 +323,11 @@ export const ConversationGrantSchema = z.object({
         .boolean()
         .default(false)
         .describe("Whether every request an allow-once could settle is allowed without asking, until somebody takes it back."),
+    // Answered on a credential gateway card, read live by the gateway as each request its rules would ask about arrives.
+    rules: z
+        .array(BrokerRulePassSchema)
+        .default([])
+        .describe("Credential gateway rules that no longer ask before its requests, each with the words a person allowed it in."),
     updatedAt: z.number().describe("When it last changed, in milliseconds."),
     by: z.string().optional().describe("Who last allowed something here."),
 });
@@ -323,6 +345,7 @@ export const StandingGrantsSchema = z.object({
             installs: z.boolean().default(false).describe("Whether its own dependency installs run without asking."),
             secrets: z.array(z.string()).default([]).describe("Secrets it may send past their host guard without asking."),
             everything: z.boolean().default(false).describe("Whether every request an allow-once could settle is allowed without asking."),
+            rules: z.array(BrokerRulePassSchema).default([]).describe("Credential gateway rules that no longer ask before its requests."),
             by: z.string().optional().describe("Who last allowed one of those."),
             updatedAt: z.number().optional().describe("When one of those last changed, in milliseconds."),
             releases: z
@@ -336,11 +359,14 @@ export type StandingGrants = z.infer<typeof StandingGrantsSchema>;
 export const GrantRevokeSchema = z.object({
     conversationId: z.string(),
     kind: z
-        .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything"])
+        .enum(["capability", "folder", "shelf", "release", "install", "secret", "everything", "rule"])
         .describe(
-            "Which kind of yes: a grant past the persona or area, a credential's release, letting its installs run unasked, a secret sent past its host guard, or allowing everything.",
+            "Which kind of yes: a grant past the persona or area, a credential's release, letting its installs run unasked, a secret sent past its host guard, allowing everything, or a credential gateway rule that stopped asking.",
         ),
-    what: z.string().describe("The capability id, folder, shelf, released credential or secret it named; empty for installs and everything."),
+    what: z
+        .string()
+        .describe("The capability id, folder, shelf, released credential or secret it named, or the rule's identity; empty for installs and everything."),
+    capability: z.string().optional().describe("For a rule, the capability whose rule it is; a rule's identity alone does not say."),
 });
 export type GrantRevoke = z.infer<typeof GrantRevokeSchema>;
 

package/src/schemas/offload.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { RunnerCommandFrameSchema, RunnerCommandSchema } from "../protocol/doors/runner-protocol.js";
+import { AgentHarnessSchema, AgentProviderSchema } from "./agent.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.
@@ -42,3 +43,78 @@ export type OffloadRecord = z.infer<typeof OffloadRecordSchema>;
 // `offload.commands` keys it) and the pattern that sorts a line into it.
 export const OffloadKindSchema = z.object({ id: z.string().min(1), pattern: z.string() });
 export type OffloadKind = z.infer<typeof OffloadKindSchema>;
+
+// NEW SESSIONS ACROSS THE OWNER'S MACHINES (settings `offload.sessions`, GET /offload/placement). One measure for every
+// machine, this sandbox and each runner alike, and one judgement over it (runners/fleet-advice.ts), so the composer's
+// suggestion, the placement menu and an automatic placement can never disagree about which machine has room.
+
+// What happens to a new session while this machine is busy and another has room: `suggest` says so above the
+// composer, `auto` starts it there unless the person keeps it here, `off` says nothing.
+export const SessionsPlacementSchema = z.enum(["suggest", "auto", "off"]);
+export type SessionsPlacement = z.infer<typeof SessionsPlacementSchema>;
+
+// `calm` takes another agent without anyone noticing; `busy` takes one at a cost to the agents already running; `full`
+// would hold or warn a person's next turn (the turn door's own figure).
+export const MachineStandingSchema = z.enum(["calm", "busy", "full"]);
+export type MachineStanding = z.infer<typeof MachineStandingSchema>;
+
+// What made a machine busy or full: memory short of what an agent needs, memory stalling, CPUs saturated, or as many
+// agents running as it has slots for.
+export const MachineStrainSchema = z.enum(["memory", "memory-stall", "cpu", "agents"]);
+export type MachineStrain = z.infer<typeof MachineStrainSchema>;
+
+export const MachineLoadSchema = z.object({
+    standing: MachineStandingSchema,
+    // Why it is not calm, strongest first; empty when it is.
+    strain: z.array(MachineStrainSchema),
+    cpus: z.number().int().positive(),
+    // The one-minute load average over the cores: 1 is every core busy.
+    load: z.number().nonnegative(),
+    // What its resource budget has free, and the limit that is measured against; absent where nothing measures it.
+    memoryFreeMb: z.number().int().nonnegative().optional(),
+    memoryLimitMb: z.number().int().positive().optional(),
+    // Conversations running a turn there now, and how many it holds at once (the fan-out scheduler's own slots).
+    agents: z.number().int().nonnegative(),
+    slots: z.number().int().positive(),
+    // The share of the machine still free by its tightest measure (slots, memory, CPU), so two machines of different
+    // sizes compare: 0 is none, 1 is idle.
+    headroom: z.number().min(0).max(1),
+});
+export type MachineLoad = z.infer<typeof MachineLoadSchema>;
+
+// Why a new session could not start on a runner right now: the machine is asleep, it has never said how big it is, the
+// draft's model signs in with a credential that does not travel, the privacy shield keeps it here, or the person is
+// limited to areas a runner cannot fence.
+export const FleetUnfitSchema = z.enum(["offline", "unmeasured", "credentials", "privacy", "areas"]);
+export type FleetUnfit = z.infer<typeof FleetUnfitSchema>;
+
+export const FleetMachineSchema = z.object({
+    runner: z.string().min(1),
+    // The machine the runner sits on, the word the owner knows it by.
+    name: z.string().min(1),
+    online: z.boolean(),
+    // Absent while it is offline or has never been measured.
+    load: MachineLoadSchema.optional(),
+    // Absent when a new session could start there now.
+    unfit: FleetUnfitSchema.optional(),
+});
+export type FleetMachine = z.infer<typeof FleetMachineSchema>;
+
+export const FleetAdviceInputSchema = z.object({
+    // The draft's provider and harness, which decide whether its credential can reach a runner; absent reads as the
+    // sandbox's defaults.
+    agent: AgentProviderSchema.optional(),
+    harness: AgentHarnessSchema.optional(),
+    // The draft's conversation, which the privacy shield may trust on its own.
+    conversationId: z.string().min(1).optional(),
+});
+export type FleetAdviceInput = z.infer<typeof FleetAdviceInputSchema>;
+
+export const FleetAdviceSchema = z.object({
+    mode: SessionsPlacementSchema,
+    here: MachineLoadSchema,
+    machines: z.array(FleetMachineSchema),
+    // Where a new session should start instead of here: absent while here is calm, or when no machine is better off.
+    suggestion: z.object({ runner: z.string().min(1), name: z.string().min(1) }).optional(),
+});
+export type FleetAdvice = z.infer<typeof FleetAdviceSchema>;

package/src/schemas/privacy.ts

@@ -87,7 +87,8 @@ export const trustedInConversation = (
     policy: Pick<PrivacyShieldPolicy, "conversations">,
     provider: string,
     conversationId: string | undefined,
-): boolean => conversationId !== undefined && policy.conversations.some((entry) => entry.conversationId === conversationId && entry.provider === provider);
+): boolean =>
+    conversationId !== undefined && policy.conversations.some((entry) => entry.conversationId === conversationId && entry.provider === provider);
 
 // The policy with that grant made or taken back. A full list drops its oldest grant to make room, since the newest is
 // the one somebody is waiting on.
@@ -104,7 +105,11 @@ export const DEFAULT_PRIVACY_SHIELD: PrivacyShieldPolicy = PrivacyShieldPolicySc
 export const PrivacyProviderSchema = z.object({
     id: z.string().describe("Provider id, as the trusted list names it."),
     label: z.string(),
-    shieldable: z.boolean().describe("The shield can read what its runtime sends by content (through the gateway or the runtime's hooks); one it cannot is refused while the shield is on, unless trusted."),
+    shieldable: z
+        .boolean()
+        .describe(
+            "The shield can read what its runtime sends by content (through the gateway or the runtime's hooks); one it cannot is refused while the shield is on, unless trusted.",
+        ),
     local: z.boolean().describe("It runs on this machine, so it is trusted whatever the list says."),
 });
 export type PrivacyProvider = z.infer<typeof PrivacyProviderSchema>;
@@ -140,6 +145,10 @@ export const PrivacyReplacementSchema = z.object({
         .string()
         .describe("The masked text around the token as it left this machine (watching: as it would have). Tokens only, never a value."),
     image: z.boolean().optional().describe("Found in an image's text, so the token was painted over the picture rather than written."),
+    imageId: z
+        .string()
+        .optional()
+        .describe("The image it was painted over, as privacy.image reads it back: the picture before and after masking, while it is still kept."),
 });
 export type PrivacyReplacement = z.infer<typeof PrivacyReplacementSchema>;
 
@@ -162,6 +171,17 @@ export const PrivacyLedgerEntrySchema = z.object({
 });
 export type PrivacyLedgerEntry = z.infer<typeof PrivacyLedgerEntrySchema>;
 
+// One image the shield painted over, as it was and as it left: the owner peeking at what the provider saw. The picture
+// before holds the personal data, so it is kept beside the vault, off the workspace, and only the owner may read it.
+export const PRIVACY_IMAGE_ID = /^[A-Za-z0-9_-]{16,64}$/u;
+export const PrivacyImageSchema = z.object({ mediaType: z.string(), data: z.string().describe("Base64.") });
+export const PrivacyImagePairSchema = z.object({
+    at: z.string().describe("When it was first painted, as an ISO timestamp."),
+    before: PrivacyImageSchema,
+    after: PrivacyImageSchema,
+});
+export type PrivacyImagePair = z.infer<typeof PrivacyImagePairSchema>;
+
 // Tokens read back to their values, for the owner checking what the shield masked; a token this vault never gave out is
 // left out of the answer.
 export const PRIVACY_REVEAL_MAX = 100;
@@ -205,7 +225,11 @@ export const PrivacyNameWordSchema = z.object({
     firstName: z.boolean().describe("A listed first name, in this form or as an inflection of one."),
     surname: z.boolean().describe("A listed surname, in this form or as an inflection of one."),
     surnameForm: z.boolean().describe("Shaped like a Polish surname (-ski, -cki, -wicz…), listed or not."),
-    ambiguous: z.boolean().describe("Also an ordinary word in some language, so found only beside other evidence (a title, a name field) and no surname to pair a first name with."),
+    ambiguous: z
+        .boolean()
+        .describe(
+            "Also an ordinary word in some language, so found only beside other evidence (a title, a name field) and no surname to pair a first name with.",
+        ),
     never: z.boolean().describe("Never taken as part of a name (a title, an institution, a function word)."),
 });
 export type PrivacyNameWord = z.infer<typeof PrivacyNameWordSchema>;

package/src/schemas/project-bring-back.test.ts

@@ -0,0 +1,15 @@
+import { type ProjectAnswer, ProjectAnswerSchema } from "./project-bring-back.js";
+
+test("reads the agent's change listing as the desktop app relays it", () => {
+    const detail: ProjectAnswer = {
+        kind: "changes",
+        result: { ok: true, pairing: "p1", direction: "to-sandbox", changes: [{ path: "a.ts", kind: "modified", size: 3, conflict: true }], truncated: true },
+    };
+    expect(ProjectAnswerSchema.parse(detail)).toEqual(detail);
+});
+
+test("a restore's skipped entries are held to their shape, and a failure carries the agent's sentence", () => {
+    expect(ProjectAnswerSchema.parse({ kind: "restored", result: { ok: true, restored: 2, skipped: [{ path: "x", reason: "changed" }] } })).toMatchObject({ result: { restored: 2 } });
+    expect(ProjectAnswerSchema.parse({ kind: "brought-back", result: { ok: false, error: "conflict" } })).toEqual({ kind: "brought-back", result: { ok: false, error: "conflict" } });
+    expect(ProjectAnswerSchema.safeParse({ kind: "changes", result: { note: "x" } }).success).toBe(false);
+});