@intentic/sandbox-contract 1.331.0 → 1.333.0

package/src/schemas/settings.test.ts

@@ -1,4 +1,6 @@
 import { convertDocument } from "../documents/conversions.js";
+import type { ModelRole } from "../models/model-roles.js";
+import { rolePins } from "../models/model-setups.js";
 import { SETTINGS_HISTORY } from "./settings-history.js";
 import { RepoChecksFileSchema, RuleSchema, SandboxSettingsSchema, SandboxSettingsWriteSchema } from "./settings.js";
 
@@ -112,6 +114,20 @@ describe(`the folded keep-warm settings`, () => {
     });
 });
 
+// Tool-result clearing lost its A/B and was removed (2026-10-12); a file that still switches it on reads, without it.
+test(`a stored tool-result clearing switch is dropped, and the rest of the file kept`, () => {
+    const converted = convertDocument(SETTINGS_HISTORY, `object`, { iqSearch: true, toolResultClearing: true, toolResultClearingHoldout: 0.5 }, true);
+    expect(converted.value).toEqual({ iqSearch: true });
+    expect(SandboxSettingsSchema.parse(converted.value).iqSearch).toBe(true);
+});
+
+// What a job runs on, read the way every reader reads it, over a sandbox with nothing connected: the setups a stored
+// file converts into are judged by what they make each job run on, not by their shape.
+const runsOn = (stored: unknown, role: ModelRole): readonly unknown[] => {
+    const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
+    return rolePins(SandboxSettingsSchema.parse(converted.value), role, []);
+};
+
 // The pre-push fix's model list went with the fix a refused push used to offer (2026-09-28). A settings file that still
 // names it must read, since an unknown role refuses the whole file, and every other job's list stays as its owner set it.
 describe(`the retired pre-push fix role`, () => {
@@ -119,14 +135,8 @@ describe(`the retired pre-push fix role`, () => {
 
     test(`is dropped from a stored file, leaving every other job's list, and the file reads`, () => {
         const stored = { modelRoles: { "pipeline-fix": [pin], "pre-push-fix": [pin] } };
-        expect(SandboxSettingsSchema.safeParse(stored).success).toBe(false);
-        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
-        expect(converted.value).toEqual({ modelRoles: { "pipeline-fix": [pin] } });
-        expect(SandboxSettingsSchema.parse(converted.value).modelRoles).toEqual({ "pipeline-fix": [pin] });
-    });
-
-    test(`leaves a file without it alone`, () => {
-        expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "pipeline-fix": [pin] } }, true).changes).toEqual([]);
+        expect(SandboxSettingsSchema.safeParse({ roleSetups: { "pre-push-fix": `high` } }).success).toBe(false);
+        expect(runsOn(stored, `pipeline-fix`)).toEqual([pin]);
     });
 });
 
@@ -138,19 +148,62 @@ describe(`the new Refactors job`, () => {
 
     test(`takes the Maintenance chores list in a file from before it, and every other list stays`, () => {
         const stored = { modelRoles: { "maintenance-chore": [opus, sol], "pipeline-fix": [sol] } };
-        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
-        expect(converted.value).toEqual({ modelRoles: { "maintenance-chore": [opus, sol], "pipeline-fix": [sol], "refactor-run": [opus, sol] } });
-        expect(SandboxSettingsSchema.parse(converted.value).modelRoles[`refactor-run`]).toEqual([opus, sol]);
-    });
-
-    test(`leaves a list the owner set, even an emptied one, and a file with no chores list`, () => {
-        for (const modelRoles of [
-            { "maintenance-chore": [opus], "refactor-run": [sol] },
-            { "maintenance-chore": [opus], "refactor-run": [] },
-            { "pipeline-fix": [opus] },
-            { "maintenance-chore": [] },
-        ]) {
-            expect(convertDocument(SETTINGS_HISTORY, `object`, { modelRoles }, true).changes).toEqual([]);
+        expect(runsOn(stored, `refactor-run`)).toEqual([opus, sol]);
+        expect(runsOn(stored, `pipeline-fix`)).toEqual([sol]);
+    });
+
+    test(`leaves a list the owner set, even an emptied one`, () => {
+        expect(runsOn({ modelRoles: { "maintenance-chore": [opus], "refactor-run": [sol] } }, `refactor-run`)).toEqual([sol]);
+        expect(runsOn({ modelRoles: { "maintenance-chore": [opus], "refactor-run": [] } }, `refactor-run`)).toEqual([]);
+    });
+});
+
+// Setups (2026-10-12): per-job lists and the default list become named setups that jobs share.
+describe(`per-job model lists`, () => {
+    const opus = { provider: `claude`, model: `claude-opus-5-5`, effort: `high` };
+    const haiku = { provider: `claude`, model: `claude-haiku-4-5` };
+    const sol = { provider: `codex`, model: `gpt-sol-6.1` };
+
+    test(`become setups that every job runs exactly as before on`, () => {
+        const cases = [
+            [`commit-message`, [haiku]],
+            [`session-title`, [haiku]],
+            [`pipeline-fix`, [opus, sol]],
+            [`refactor-run`, [opus, sol]],
+            [`handoff-summary`, [sol, haiku]],
+            [`safety-judge`, []],
+        ] as const satisfies readonly (readonly [ModelRole, readonly unknown[]])[];
+        for (const [role, pins] of cases) {
+            expect(runsOn({ modelRoles: Object.fromEntries(cases) }, role)).toEqual(pins);
         }
     });
+
+    test(`share a setup where they held one list, which becomes the preset most of them suit`, () => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: { "commit-message": [haiku], "session-title": [haiku], "pipeline-fix": [opus], "handoff-summary": [sol] } }, true);
+        expect(converted.value).toEqual({
+            modelSetups: [
+                { id: `low`, pins: [haiku] },
+                { id: `setup-1`, name: `Setup 1`, pins: [sol] },
+                { id: `high`, pins: [opus] },
+            ],
+            roleSetups: { "commit-message": `low`, "session-title": `low`, "handoff-summary": `setup-1`, "pipeline-fix": `high` },
+        });
+    });
+
+    test(`carry the default list to every job that had none of its own`, () => {
+        const stored = { modelDefault: [sol], modelRoles: { "pipeline-fix": [opus] } };
+        expect(runsOn(stored, `commit-message`)).toEqual([sol]);
+        expect(runsOn(stored, `loop-iteration`)).toEqual([sol]);
+        expect(runsOn(stored, `pipeline-fix`)).toEqual([opus]);
+    });
+
+    test(`leave a job that never had a list on none, running exactly as before`, () => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { modelRoles: {} }, true);
+        expect(converted.value).toEqual({ modelSetups: [], roleSetups: {} });
+        expect(runsOn({ modelRoles: {} }, `safety-judge`)).toEqual([]);
+    });
+
+    test(`read once, and a file already in setups is left alone`, () => {
+        expect(convertDocument(SETTINGS_HISTORY, `object`, { modelSetups: [{ id: `low`, pins: [haiku] }], roleSetups: {} }, true).changes).toEqual([]);
+    });
 });

package/src/schemas/settings.ts

@@ -4,9 +4,13 @@ import { STATE_DIR } from "@intentic/constants";
 import { z } from "zod";
 import { CommandJudgeModeSchema, ProjectInstallModeSchema } from "../policy/safety-policy.js";
 import { ModelRoleSchema } from "../models/model-roles.js";
-import { AdmissionPolicySchema, AdmissionRuleSchema, ModelPinSchema } from "./agent.js";
+import { MODEL_SETUP_ID, ModelSetupSchema } from "../models/model-setups.js";
+import { AdmissionPolicySchema, AdmissionRuleSchema } from "./agent.js";
+import { LimitHandoffSchema } from "./providers/handoff.js";
+import { SessionsPlacementSchema } from "./offload.js";
 import { LimitPolicySchema, RetryPolicySchema, RoomPolicySchema } from "./turn-break.js";
 import { ZoneSchema } from "../time/zone.js";
+import { VoiceSettingsSchema } from "./voice.js";
 // Which prompt base the agent runs before this turn composes anything on top: Intentic's own (default), Claude Code's
 // preset, or the owner's text. Declared out here since both the daemon and the browser branch on it.
 // Kept in the daemon's auth root, never in SandboxSettings: an agent cannot edit its execution boundary.
@@ -316,23 +320,6 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
         ),
-    // Measured by the `clearing` experiment: the gateway in front of a native Claude turn replaces old tool results with
-    // a placeholder, a chunk at a time, so the cached prompt breaks once per chunk rather than on every call
-    // (privacy/gateway/tool-result-clearing.ts). Off by default until that experiment says it pays.
-    toolResultClearing: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Replace old tool results from a Claude conversation once it grows long, a large chunk at a time, keeping the most recent ones whole. The agent sees a short placeholder where each one was and can run the tool again. Smaller prompts cost less and answer sooner, at the risk of the agent re-reading what it already saw.",
-        ),
-    toolResultClearingHoldout: z
-        .number()
-        .min(0)
-        .max(1)
-        .default(0.5)
-        .describe(
-            "What share of conversations keep every tool result, so the two can be compared. Whole conversations rather than individual turns, because what was dropped stays dropped for the rest of the session.",
-        ),
     iqSearch: z
         .boolean()
         .default(false)
@@ -351,18 +338,19 @@ export const SandboxSettingsSchema = z.object({
         .boolean()
         .default(false)
         .describe(
-            "Open every conversation with a map of the project it starts in: the parts recent work touched and what each is for, the rest by name, where the agent is standing, and which folders the last three weeks of commits landed in. Worked out fresh each time from the tree and its history rather than written down anywhere, because a written layout is wrong within a fortnight. Off by default, since it spends tokens on the first message of every conversation.",
+            "Open every conversation with a map of the project it starts in: what is in it, what each part is for, and where the agent is standing. Worked out fresh each time rather than written down anywhere, because a written layout is wrong within a fortnight. Off by default, since it spends tokens on the first message of every conversation.",
         ),
     // Judged on the opening turn's own directory listings, not averaged across the conversation, or a twelve-turn
-    // conversation would divide the effect by twelve. Since 2026-10-06 the held-out share gets the full map (every area
-    // with its size) rather than none: the map-or-none comparison had settled its one effect, fewer opening listings.
+    // conversation would divide the effect by twelve. From 2026-10-06 to 10-12 the held-out share got the full map
+    // against a compact one; that changed nothing measurable, so the compact form went and the holdout opens without a
+    // map again.
     workspaceMapHoldout: z
         .number()
         .min(0)
         .max(1)
         .default(0)
         .describe(
-            "What share of conversations to open with the full map instead, every area with its size, so the two forms can be compared. Whole conversations rather than individual turns, because the map is sent once and stays in the conversation's history afterwards.",
+            "What share of conversations to open without the map, so the two can be compared. Whole conversations rather than individual turns, because the map is sent once and stays in the conversation's history afterwards.",
         ),
     // The one composed piece that is WRITTEN rather than derived: a monthly automation rewrites it off the session
     // corpus, so it carries what no scan of the tree can (which commands really work here, what the box can take, how
@@ -402,15 +390,22 @@ export const SandboxSettingsSchema = z.object({
         .max(1)
         .default(0)
         .describe("What share of commands to leave untrimmed, so the saving can be measured against a real comparison rather than estimated."),
-    // One key, not one field per role: a role catalog entry (`model-roles.ts`) makes a new job configurable without a
-    // schema change here.
+    // The model lists jobs run on, edited once for every job put there (models/model-setups.ts). The three presets need
+    // no entry: absent, each is worked out from what is connected, so a sandbox runs before anyone opens this page.
+    modelSetups: z
+        .array(ModelSetupSchema)
+        .max(20)
+        .default([])
+        .describe(
+            "The model setups jobs run on: Low, Medium and High, which every sandbox has, and any you make. Each is an ordered list of models, tried in order so one spent account does not take its jobs down. A preset left out of this list, or listed without models, is worked out from the accounts you have connected. A setup runs only the jobs put on it (`roleSetups`).",
+        ),
     // `partialRecord`, not `record`: an exhaustive one would force every settings file to list every role, and adding
-    // one would invalidate them all. Absent IS "no list".
-    modelRoles: z
-        .partialRecord(ModelRoleSchema, z.array(ModelPinSchema).max(10))
+    // one would invalidate them all. Absent IS "on no setup": nothing runs a job nobody placed.
+    roleSetups: z
+        .partialRecord(ModelRoleSchema, z.string().regex(MODEL_SETUP_ID))
         .default({})
         .describe(
-            "Which models do which job, one ordered list per job: commit messages, session titles, the safety judge, pipeline fixes, and every other place this sandbox picks a model for you. Tried in order, so one spent account does not take a job down. Nothing is chosen for you: a one-shot job with no list does not run, and a whole session with no list opens on whatever your own chat is set to.",
+            "Which setup each job runs on: commit messages, session titles, the safety judge, pipeline fixes and every other place this sandbox picks a model for you. Nothing is chosen for you: a job left out, or on a setup with no models, has none, so a one-shot job does not run and a whole session opens on whatever your own chat is set to.",
         ),
     // Folded into the router's prompt (agent/prompt/chat-router.ts), never into a turn's own. Capped small on
     // purpose: the reading runs under a 5s deadline, and this text is paid for on every chat that opens on Auto.
@@ -457,13 +452,28 @@ export const SandboxSettingsSchema = z.object({
     memoryPolicy: RoomPolicySchema.default("resend").describe(
         "What happens to a message the sandbox held because it was short of memory: nothing ran, so nothing was spent. `resend` sends it by itself once memory has stayed free for a while, one held conversation at a time. `wait` holds it until somebody presses Send anyway. The sandbox-wide default; any one conversation can say otherwise.",
     ),
+    // How a held turn continues once its cache has gone cold (schemas/providers/handoff.ts). The card asks each time and
+    // preselects this; a booked send (a move, a resend at the reset) uses it unless a person picked on the card.
+    limitHandoff: LimitHandoffSchema.default("suggested").describe(
+        "How a turn a spent usage limit held continues, on this account at the reset or on another: `carry` resumes the session as it is (the model keeps everything and re-reads all of it), `trim` resumes a copy with older tool output cleared (every message and tool call stays), `summary` opens a fresh session with a smaller model's summary and the last exchanges word for word. `suggested` picks by the conversation's size, using the two thresholds beside this. The chat's card preselects it and lets you pick another for that turn.",
+    ),
+    // Read by the `suggested` hand-off only. Kept under its old name: before 2026-10-10 it chose between carrying and a
+    // short record hand-off for a move, and a saved value still means "carry under this".
     limitMoveCarryUnder: z
         .number()
         .int()
         .min(0)
-        .default(100_000)
+        .default(150_000)
         .describe(
-            "When a spent usage limit moves a turn to another account, carry the provider session (the model keeps everything, and re-reads all of it once on the other account) while the conversation's context is under this many tokens; at or above it, start a fresh session with the sandbox's measured brief instead. Zero always starts fresh.",
+            "For the suggested hand-off: carry the session as it is while the conversation's context is under this many tokens; at or above it, trim it (or summarise it, past the next threshold). Zero never suggests carrying.",
+        ),
+    handoffSummaryOver: z
+        .number()
+        .int()
+        .min(0)
+        .default(700_000)
+        .describe(
+            "For the suggested hand-off: at or above this many tokens of context, suggest a summary rather than a trimmed session, where a model is set for hand-off summaries.",
         ),
     // Off by default: every refresh spends the account's own allowance on a conversation nobody is using yet. Before
     // 2026-09-26 these were four top-level settings (settings-history.ts folds them).
@@ -493,13 +503,17 @@ export const SandboxSettingsSchema = z.object({
     // the heavy-command rule an agent's command matched (workload/heavy-commands.ts), each naming a runner id. A
     // runner that is offline, outdated or full hands the work back here, which the command's output says. Never pushed
     // to a runner itself (definition/definition.ts), which must not pass work on again.
+    // `sessions`: what a new conversation is told when this machine is busy and a runner has room
+    // (runners/fleet-advice.ts). Suggesting is the default: it costs one line above the composer, and moving a session
+    // without being asked is the owner's choice to make.
     offload: z
         .object({
             commands: z.record(z.string().min(1), z.string().min(1)).default({}),
+            sessions: SessionsPlacementSchema.default("suggest"),
         })
-        .default({ commands: {} })
+        .default({ commands: {}, sessions: "suggest" })
         .describe(
-            "Which heavy work runs on a runner on one of your machines instead of this sandbox: agents' commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…). The code travels as it stands, uncommitted work included; the output streams back, and any file the command changed comes back with it. A machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so.",
+            "Which work runs on a runner on one of your machines instead of this sandbox. `commands`: agents' heavy commands by the kind the heavy-command rules sort them into (tests, typechecks, verify…); the code travels as it stands, uncommitted work included, the output streams back, and any file the command changed comes back with it, while a machine that is offline, outdated or busy hands the work back to this sandbox, and the output says so. `sessions`: what happens to a new conversation while this machine is busy and one of your runners has room: `suggest` offers that machine above the composer, `auto` starts it there unless you keep it here, `off` says nothing.",
         ),
     // A person answering a need is exactly the moment they want the work to go on (docs/architecture/needs.md), unlike a
     // restart nobody watched, so this one is on to begin with.
@@ -517,13 +531,15 @@ export const SandboxSettingsSchema = z.object({
         ),
     // Which repositories' own declarations (`<repo>/.intentic/checks.json`) the owner has switched on, each against the
     // fingerprint of what was declared when they did. A declaration that has since changed no longer matches its
-    // fingerprint and is held rather than run, which is what makes adoption a decision about a command rather than a
-    // permanent permission on a folder. Keyed by repo id, so `/` in the key is ordinary.
+    // fingerprint: the daemon finds the version that did in the repository's history, keeps running each check that is
+    // still word for word one of its checks, and holds every new or rewritten one, which is what makes adoption a
+    // decision about a command rather than a permanent permission on a folder, without one added check switching off
+    // all the others. Keyed by repo id, so `/` in the key is ordinary.
     adoptedChecks: z
         .record(z.string(), z.string())
         .default({})
         .describe(
-            "Which repositories may run the checks they declare for themselves, and exactly which version of those checks you agreed to. A repository's declaration does nothing until it appears here, the same rule git keeps for hooks, which are never cloned; and a declaration that changes afterwards is held until you look at it again.",
+            "Which repositories may run the checks they declare for themselves, and exactly which version of those checks you agreed to. A repository's declaration does nothing until it appears here, the same rule git keeps for hooks, which are never cloned; and a check it adds or rewrites afterwards waits until you look at it again, while the ones you agreed to keep running.",
         ),
     // The owner's alone, since a rule can hold work. A command is refused here: it belongs to the repository it checks,
     // in that repository's `.intentic/checks.json`, never in settings.
@@ -545,6 +561,11 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "How many failures in a row before an automation switches itself off. Zero means never, which is the default, because the failure is not always the automation's fault and a job disabled at three in the morning is one nobody re-enables. Only real errors count: a guard deciding there was nothing to do, or the sandbox dying mid-run, say nothing about the automation.",
         ),
+    // Speaking replies aloud (schemas/voice.ts): which voice speaks each language, and whether a hands-free turn is
+    // answered out loud. Read by the daemon's voice engine on every utterance, so a change is heard on the next one.
+    voice: VoiceSettingsSchema.prefault({}).describe(
+        "How the agent's replies are spoken aloud: whether a hands-free conversation is answered out loud, which voice speaks each language, and a speech provider of your own if you connected one.",
+    ),
     // Defaults all-allow, so a fresh sandbox behaves as it did before this floor existed.
     admission: AdmissionPolicySchema.prefault({}).describe(
         "Whether work started from outside may run, per kind of trigger: let it, hold it for approval, or refuse it. Composes with each automation's own setting, and the stricter of the two wins, so holding every visitor's message needs no edit to each automation.",
@@ -558,7 +579,7 @@ export const SandboxSettingsSchema = z.object({
         .default({})
         .describe("What an agent may do out in the world, per kind of action: go ahead, ask first, or never."),
     // Command policy itself lives at .intentic/config/safety.md (edited by the Safety page), not here; this only says
-    // whether the judge runs at all. Which model judges is the `safety-judge` role in `modelRoles`, not a field here.
+    // whether the judge runs at all. Which model judges is the `safety-judge` job's setup (`roleSetups`), not a field here.
     commandJudge: CommandJudgeModeSchema.default("on").describe(
         "Whether a model reads your safety policy before a flagged command runs. Off judges nothing and asks about nothing; Watch judges everything and records it without ever interrupting you, which is how you find out what your policy actually does before you let it stop anything; On lets the verdict decide. Wiping a disk or deleting under /history asks at every setting — that rule is typed rather than judged, and cannot be turned off.",
     ),
@@ -608,6 +629,20 @@ export const AudienceStateSchema = z.object({
 });
 export type AudienceState = z.infer<typeof AudienceStateSchema>;
 
+// What a person has said about the editor's getting-started checklist on this sandbox, kept per member like the
+// audience so it reads the same on every device. Only what the sandbox's own data cannot answer: whether a step is DONE
+// is read from that data each time (a workspace with files, an agent started, a model connected, work landed), so this
+// holds nothing but the reader's own choices. Step names are the editor's, opaque here.
+export const GettingStartedSchema = z.object({
+    hidden: z.boolean().optional().describe("Whether this person put the checklist away. Absent until they have."),
+    skipped: z
+        .array(z.string().min(1).max(40))
+        .max(20)
+        .optional()
+        .describe("The checklist steps this person passed over, by the editor's own step names."),
+});
+export type GettingStarted = z.infer<typeof GettingStartedSchema>;
+
 // A browser telling the sandbox which clock IT is on. An offer, not an instruction: see `adoptTimezone`.
 export const TimezoneOfferSchema = z.object({
     timezone: ZoneSchema.describe("The zone the offering machine is in, as an IANA name like Europe/Warsaw."),
@@ -658,13 +693,9 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
 // openingListings: directory listings a turn ran to orient itself (the project map).
 // callsBeforeTarget: how far a turn walked before touching a file it went on to edit.
 // failedCalls: tool calls that ended in error (the field notes, whose largest section is a failure taxonomy).
-// roundTrips: model calls a turn took (tool-result clearing, whose lost results could cost re-runs).
-// contextPerCall: prompt tokens per model call, cached or not (tool-result clearing, which exists to shrink it).
-// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest. Round trips are the
-// nearest a reading comes to it, and still a count of calls, not of tokens or money; the prompt a call carries is the
-// one exception, for the one mechanism that changes nothing else.
+// Never cost: each mechanism moves one small part of a turn's work, inside the noise of the rest.
 export const TurnMetricReadingSchema = z.object({
-    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget", "failedCalls", "roundTrips", "contextPerCall"]),
+    metric: z.enum(["searchCalls", "openingSearches", "openingListings", "callsBeforeTarget", "failedCalls"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
     // Additional control turns to reach a fixed target resolution, not today's delta (which inherits noise and always
@@ -727,7 +758,6 @@ export const SavingsReportSchema = z.object({
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
-    clearing: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 
@@ -793,7 +823,13 @@ export const RepoChecksSummarySchema = z.object({
     changed: z
         .boolean()
         .describe(
-            "Whether the declaration changed since it was adopted, which holds it until the owner looks again. True only for a repository that was adopted before.",
+            "Whether the declaration gained or rewrote a check since it was adopted. What changed waits until the owner looks again; the checks the owner already agreed to, word for word, keep running (`held` says which is which). True only for a repository that was adopted before.",
+        ),
+    held: z
+        .array(z.boolean())
+        .optional()
+        .describe(
+            "For a changed declaration, which of its checks wait for the owner, in the file's order: true for one that is new or rewritten since they agreed, false for one still running as agreed, or retired. Absent when nothing changed, and from a sandbox that holds a changed declaration whole.",
         ),
     error: z.string().optional().describe("Why the file could not be read, when it exists but does not parse. The checks list is empty in that case."),
 });

package/src/schemas/short-codes.ts

@@ -0,0 +1,59 @@
+// short codes: the single-use 8-character code a copy-paste command carries instead of a token. The sandbox mints one
+// beside each device, sync or server-connect token it hands out; the install script redeems it at the sandbox's public
+// POST /system/redeem/<code>, which answers `KEY=value` lines (KIND, SANDBOX_URL, then the kind's own values).
+import { z } from "zod";
+import { INVENTORY_NAME_MAX, INVENTORY_NAME_RE } from "./inventory.js";
+
+// Crockford base32 (no I, L, O, U), 8 characters: 40 bits. Redemption accepts any case and one hyphen in the middle.
+export const SHORT_CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const SHORT_CODE_LENGTH = 8;
+export const ShortCodeSchema = z.string().regex(/^[0-9A-HJKMNP-TV-Z]{8}$/);
+
+// What each kind of code redeems to, in its answer's KIND line.
+export const ShortCodeKindSchema = z.enum(["device", "sync", "server"]);
+export type ShortCodeKind = z.infer<typeof ShortCodeKindSchema>;
+
+// A value that rides one `KEY=value` line: no line breaks or other control characters.
+const lineValue = z
+    .string()
+    .min(1)
+    .max(1024)
+    .regex(/^[^\p{Cc}]+$/u);
+
+// A device or sync pairing as minted: the token (unchanged) and, additively, the code that stands for it.
+export const PairingAnswerSchema = z.object({
+    token: z.string(),
+    expiresIn: z.number().describe("Seconds until the token, and its code, expire."),
+    code: ShortCodeSchema.describe("Single-use short code a command carries instead of the token."),
+});
+export type PairingAnswer = z.infer<typeof PairingAnswerSchema>;
+
+// What POST /system/<door>/pair answers on any peer door (device, browser, phone, runner): the token, and the short code
+// only the device door mints beside it. `expiresIn` is optional on read since a reader meets daemons older than the
+// field; the editor then shows the token without a countdown.
+export const PeerPairingAnswerSchema = PairingAnswerSchema.partial({ code: true, expiresIn: true });
+export type PeerPairingAnswer = z.infer<typeof PeerPairingAnswerSchema>;
+
+// POST /system/sync/pair: the pairing with the mode the daemon granted, which may be less than the one asked for (a
+// member's "sync" comes back "mirror"), and the code that stands for it.
+export const SyncPairAnswerSchema = PeerPairingAnswerSchema.extend({ mode: z.enum(["sync", "mirror"]).optional() });
+export type SyncPairAnswer = z.infer<typeof SyncPairAnswerSchema>;
+
+// POST /system/sync/pair's optional body: the person's chosen local folder and takeover, handed out with the code.
+// It goes to their own sandbox, never the platform.
+export const SyncPairRequestSchema = z.object({
+    syncDir: lineValue.optional().describe("Local folder to sync, as the person chose it (`~` expanded on the device)."),
+    takeover: z.boolean().optional().describe("Take sync over from another machine already enrolled."),
+});
+export type SyncPairRequest = z.infer<typeof SyncPairRequestSchema>;
+
+// POST /system/enroll/code: mints a server-connect code backed by a single-use enroll token.
+export const EnrollCodeRequestSchema = z.object({
+    hostName: z.string().min(1).max(INVENTORY_NAME_MAX).regex(INVENTORY_NAME_RE).optional().describe("What the server will be called."),
+});
+export type EnrollCodeRequest = z.infer<typeof EnrollCodeRequestSchema>;
+export const EnrollCodeAnswerSchema = z.object({
+    code: ShortCodeSchema,
+    expiresIn: z.number().describe("Seconds until the code and its enroll token expire."),
+});
+export type EnrollCodeAnswer = z.infer<typeof EnrollCodeAnswerSchema>;

package/src/schemas/speech.ts

@@ -66,6 +66,10 @@ export const SpeechStatusSchema = z.object({
 });
 export type SpeechStatus = z.infer<typeof SpeechStatusSchema>;
 
+// POST /speech/transcribe: one phrase as WAV in, its words out; empty when it held none.
+export const SpeechTranscriptSchema = z.object({ text: z.string() });
+export type SpeechTranscript = z.infer<typeof SpeechTranscriptSchema>;
+
 // GET /speech/stream, a WebSocket: the composer cuts the microphone into phrases itself (its silence segmenter) and
 // streams each one as it is spoken. A text frame `begin` opens phrase `id`; binary frames that follow are its audio,
 // 16 kHz mono s16le; `end` closes it, keeping its first `keep` samples (the trailing pause trimmed off); `drop`

package/src/schemas/system.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
-import { StatePlanSchema } from "./state-plan.js";
+import { BootProgressSchema } from "../events/system-events.js";
+import { AnnounceStateSchema } from "./platform-link.js";
+import { StatePlanSchema, StateStatusSchema } from "./state-plan.js";
 import { AutoUpdateSchema, UpdateOutcomeSchema, WithdrawnReleaseSchema } from "./updates.js";
 // version is this build's baked-in version; latest/updateAvailable come from comparing it to the published stable
 // release.
@@ -191,8 +193,8 @@ export const ManifestRepairSchema = z.object({
         ),
 });
 export type ManifestRepair = z.infer<typeof ManifestRepairSchema>;
-// Steady-state browser credential (system.session), exchanged for a verified Google ID token so Google UI appears only
-// at sign-in. expiresAt is epoch ms; renew ahead of it without parsing the token.
+// Steady-state browser credential (system.session), exchanged for a verified Google ID token or the platform's identity
+// assertion, so sign-in UI appears only once. expiresAt is epoch ms; renew ahead of it without parsing the token.
 export const DaemonSessionSchema = z.object({
     token: z.string().describe("The credential every other call carries. Present it as a bearer token."),
     expiresAt: z.number().describe("When it stops working, in milliseconds, so a caller can renew ahead of it without reading the token."),
@@ -204,10 +206,18 @@ export type DaemonSession = z.infer<typeof DaemonSessionSchema>;
 // daemon is the WebAuthn relying party; these are the shapes its /system/passkeys routes and the 428 step-up carry.
 
 // How a session's identity was proven. A session carries the set it was minted from; the require-passkey policy reads
-// it on every request, so a session minted before the switch stops working on its next call.
-export const ProofMethodSchema = z.enum(["google", "ticket", "passkey", "recovery"]);
+// it on every request, so a session minted before the switch stops working on its next call. `email` is the platform's
+// signed word that the person controls the address (policy/identity-assertion.ts), accepted only where the owner opted
+// that person in, and on hosted machines.
+export const ProofMethodSchema = z.enum(["google", "ticket", "passkey", "recovery", "email"]);
 export type ProofMethod = z.infer<typeof ProofMethodSchema>;
 
+// The `reason` a daemon's refusal of an identity assertion carries beside its `error`, so the editor can say what to do:
+// a 403 for a person this sandbox has not opted in to email sign-in (the owner turns it on for them), a 401 when the
+// daemon has not yet learned the platform's identity key (it has not reached the platform; worth a retry).
+export const EMAIL_SIGN_IN_OFF = "email-sign-in-off";
+export const PLATFORM_KEY_UNKNOWN = "platform-key-unknown";
+
 export const PasskeySummarySchema = z.object({
     id: z.string().describe("The credential id the authenticator chose, base64url."),
     email: z.string().describe("Whose passkey this is; the owner's list carries every member's, a member's only their own."),
@@ -231,6 +241,9 @@ export type PasskeysList = z.infer<typeof PasskeysListSchema>;
 
 export const PasskeyPolicySchema = z.object({ required: z.boolean() });
 export type PasskeyPolicy = z.infer<typeof PasskeyPolicySchema>;
+// POST /system/passkeys/policy: switching the rule on answers with the recovery codes, off with none.
+export const PasskeyPolicyAnswerSchema = PasskeyPolicySchema.extend({ codes: z.array(z.string()).optional() });
+export type PasskeyPolicyAnswer = z.infer<typeof PasskeyPolicyAnswerSchema>;
 
 // Shown exactly once: the daemon keeps only their hashes.
 export const RecoveryCodesSchema = z.object({ codes: z.array(z.string()) });
@@ -316,3 +329,91 @@ export interface AuthenticationOptionsJSON {
     // pressing it can succeed.
     readonly available: boolean;
 }
+
+// The two interfaces above read off the wire with the one check a body needs before the browser's own parser takes it
+// (`parseCreationOptionsFromJSON` rejects the rest): an object with a challenge. Typed, not parsed field by field, since
+// only the daemon writes them.
+const WithChallengeSchema = z.object({ challenge: z.string() });
+const optionsWithChallenge = <Options extends { readonly challenge: string }>() => z.custom<Options>((value) => WithChallengeSchema.safeParse(value).success);
+export const RegistrationOptionsSchema = optionsWithChallenge<RegistrationOptionsJSON>();
+export const AuthenticationOptionsSchema = optionsWithChallenge<AuthenticationOptionsJSON>();
+
+// POST /system/passkeys/register: the passkey as listed, and the session upgraded on the spot when the bearer that
+// registered held no passkey yet (the same proof, now carrying one).
+export const PasskeyRegisteredSchema = z.object({
+    passkey: PasskeySummarySchema,
+    session: DaemonSessionSchema.optional(),
+});
+export type PasskeyRegistered = z.infer<typeof PasskeyRegisteredSchema>;
+
+// POST /system/session/recover: the session the recovery code bought, and how many codes are left unspent.
+export const SessionRecoveredSchema = DaemonSessionSchema.extend({ remaining: z.number() });
+export type SessionRecovered = z.infer<typeof SessionRecoveredSchema>;
+
+// Whether this sandbox's public address answers, probed by the box itself; the same shape as `announce` beside it, so
+// `ic sandbox doctor` and the setup wizard can name whichever link broke.
+export const ReachStateSchema = z.object({
+    // off: nothing to probe; checking: no verdict yet; reachable: its own public address answered with our id.
+    state: z.enum(["off", "checking", "reachable", "unreachable"]),
+    // Why, for "unreachable", already in the user's terms since the wizard renders it verbatim.
+    detail: z.string().optional(),
+    // False once the give-up window is spent; only a restart retries after that.
+    retrying: z.boolean().optional(),
+    at: z.number().optional(),
+});
+export type ReachState = z.infer<typeof ReachStateSchema>;
+
+// Which build answers, so "is the fix live?" is one read.
+export const BuildStampSchema = z.object({
+    version: z.string(),
+    commit: z.string().optional(),
+    builtAt: z.string().optional(),
+});
+
+// GET /health: the "is a daemon there" probe every flow uses (launch scripts, /setup, the browser's loopback probe,
+// the platform's hosted gate, the onboarding lane), served raw before any authentication. `ic` reads it too, in Rust
+// (_sandbox/ic/src/health.rs), which cannot import this and reads only `boot`, `state` and `announce` loosely.
+export const DaemonHealthSchema = z.object({
+    ok: z.literal(true),
+    // The sandbox id, so a loopback probe can confirm it reached this daemon and not an unrelated process. Absent on a
+    // daemon with no connect token.
+    sandboxId: z.string().optional(),
+    // Which posture answers (the daemon's platform/profile.ts); needed before any authenticated read.
+    profile: z.string(),
+    // Tells "not answering" from "still converging".
+    boot: BootProgressSchema,
+    // Whether an update's state conversions are still uncommitted; the host rolls the update back when they stay open.
+    state: StateStatusSchema,
+    // Whether this daemon reached the platform.
+    announce: AnnounceStateSchema,
+    reach: ReachStateSchema,
+    // How the world reaches here: a dialed tunnel, or loopback only.
+    reachedBy: z.enum(["tunnel", "loopback"]),
+    build: BuildStampSchema,
+    // Which proofs this daemon takes to open a session, read before any sign-in since the route list arrives only after
+    // one. Absent on a daemon from before email sign-in: Google, and the owner ticket on a hosted machine.
+    signIn: z.object({ proofs: z.array(ProofMethodSchema) }).optional(),
+});
+export type DaemonHealth = z.infer<typeof DaemonHealthSchema>;
+
+// The same answer as a reader outside the daemon takes it: from a daemon of any age, so every field may be missing,
+// and one of an unexpected shape reads as missing rather than failing the whole answer. A daemon older than the boot
+// report said `ready` at the top level instead.
+export const DaemonHealthReadingSchema = z.object({
+    ok: z.boolean().optional().catch(undefined),
+    ready: z.boolean().optional().catch(undefined),
+    sandboxId: z.string().optional().catch(undefined),
+    profile: z.string().optional().catch(undefined),
+    boot: z.object({ ready: z.boolean().optional().catch(undefined) }).optional().catch(undefined),
+    state: z.object({ journal: z.string().optional().catch(undefined) }).optional().catch(undefined),
+    announce: AnnounceStateSchema.optional().catch(undefined),
+    reach: ReachStateSchema.optional().catch(undefined),
+    reachedBy: z.string().optional().catch(undefined),
+    build: BuildStampSchema.optional().catch(undefined),
+    // Proof names this build may not know are kept as text, so a newer daemon's list still reads.
+    signIn: z
+        .object({ proofs: z.array(z.string()).catch([]) })
+        .optional()
+        .catch(undefined),
+});
+export type DaemonHealthReading = z.infer<typeof DaemonHealthReadingSchema>;