@intentic/sandbox-contract 1.331.0 → 1.332.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,7 +4,10 @@ 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";
 // Which prompt base the agent runs before this turn composes anything on top: Intentic's own (default), Claude Code's
@@ -316,23 +319,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 +337,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 +389,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 +451,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 +502,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 +530,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.
@@ -558,7 +573,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 +623,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 +687,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 +752,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 +817,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,48 @@
+// 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>;
+
+// 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/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.
@@ -316,3 +318,63 @@ export interface AuthenticationOptionsJSON {
     // pressing it can succeed.
     readonly available: boolean;
 }
+
+// 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,
+});
+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),
+});
+export type DaemonHealthReading = z.infer<typeof DaemonHealthReadingSchema>;

package/src/state/history-state.ts

@@ -31,6 +31,10 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // (settings/member-audience.ts). Carried: it is theirs, and asking again after a move would be a question already
     // answered.
     { path: "member-audience.json", portability: "carry" },
+    // Each person's own answers to the editor's getting-started checklist (put away, a step passed over), keyed by sign-in
+    // address (settings/member-getting-started.ts). Carried for the same reason: a checklist someone put away should not
+    // come back after a move.
+    { path: "member-getting-started.json", portability: "carry" },
     { path: "activity.jsonl", portability: "carry" },
     { path: "usage.jsonl", portability: "carry" },
     { path: "account-usage.json", portability: "carry" },

package/src/state/runtime-state.test.ts

@@ -36,6 +36,10 @@ describe(`staleRuntimeQueryKeys`, () => {
         // The feed is ["activity", <sandbox>] and the status ["activity-status", <sandbox>]: two keys, not one prefix.
         expect(staleRuntimeQueryKeys([`activity`])).toEqual([[`activity`], [`activity-status`]]);
     });
+
+    it(`re-reads the Allowed list when a card's yes is written or taken back, which no file push carries`, () => {
+        expect(staleRuntimeQueryKeys([`grants`])).toEqual([[`grants`]]);
+    });
 });
 
 describe(`RUNTIME_DOMAIN_BINDINGS`, () => {

package/src/state/runtime-state.ts

@@ -66,6 +66,10 @@ const RUNTIME_DOMAINS = [
     // An automatic update started waiting, changed what it waits on, began counting down or handed itself to the
     // machine: what every page needs to hear before the sandbox goes quiet under it, wherever the reader is.
     { domain: "update", invalidates: [["update"]] },
+
+    // A standing yes written or taken back outside a need's answer: a permission card's pass, a release, a purge. They
+    // live under the auth root, which no file push watches, and the Allowed list must move with the card that wrote one.
+    { domain: "grants", invalidates: [["grants"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;

package/src/state/versions.test.ts

@@ -1,4 +1,4 @@
-import { DEV_VERSION, isBehind, isNewer } from "./versions.js";
+import { compareVersions, DEV_VERSION, isBehind, isNewer, parseVersion } from "./versions.js";
 
 test("isNewer compares dotted numeric versions", () => {
     expect(isNewer("1.3.0", "1.2.9")).toBe(true); // newer minor
@@ -34,3 +34,32 @@ test("a version that isn't dotted-numeric can only ever withhold the nudge", ()
 test("isBehind flags the hand-written version agents used to carry", () => {
     expect(isBehind("0.1.0", "1.183.0")).toBe(true);
 });
+
+test("compareVersions puts a release ahead of its own prereleases", () => {
+    expect(compareVersions("1.2.0", "1.2.0-rc.1")).toBe(1);
+    expect(compareVersions("1.2.0-rc.1", "1.2.0")).toBe(-1);
+    expect(compareVersions("1.2.0-rc.2", "1.2.0-rc.1")).toBe(1);
+    expect(compareVersions("1.2.0-rc.10", "1.2.0-rc.9")).toBe(1); // numeric identifiers numerically
+    expect(compareVersions("1.2.0-rc.1.1", "1.2.0-rc.1")).toBe(1); // more identifiers, equal so far, is later
+    expect(compareVersions("1.2.0-1", "1.2.0-alpha")).toBe(-1); // a number sorts below a word
+    expect(compareVersions("1.1.9", "1.2.0-rc.1")).toBe(-1); // the core decides before the prerelease
+});
+
+test("compareVersions tolerates a leading v and ignores build metadata", () => {
+    expect(compareVersions("v1.10.0", "1.9.0")).toBe(1);
+    expect(compareVersions("V2.0.0", "v2.0.0")).toBe(0);
+    expect(compareVersions("1.2.0+build.5", "1.2.0")).toBe(0);
+    expect(compareVersions("1.2", "1.2.0")).toBe(0);
+});
+
+test("compareVersions sorts anything unparseable below every version", () => {
+    expect(compareVersions("unknown", "0.0.1")).toBe(-1);
+    expect(compareVersions("1.0.0", "")).toBe(1);
+    expect(compareVersions("latest", "unknown")).toBe(0);
+    expect(["1.2.0-rc.1", "unknown", "1.10.0", "v1.2.0"].sort((a, b) => compareVersions(b, a))).toEqual(["1.10.0", "v1.2.0", "1.2.0-rc.1", "unknown"]);
+});
+
+test("parseVersion reads the parts and the prerelease", () => {
+    expect(parseVersion("v1.2.3-rc.1+abc")).toEqual({ parts: [1, 2, 3], prerelease: ["rc", "1"] });
+    expect(parseVersion("1.x")).toBe(undefined);
+});

package/src/state/versions.ts

@@ -24,3 +24,71 @@ export const DEV_VERSION = `0.0.0`;
 // A malformed version compares as not-newer only, so it can withhold a nag but never invent one.
 export const isBehind = (installed: string | undefined, latest: string | undefined): boolean =>
     installed !== undefined && latest !== undefined && installed !== DEV_VERSION && isNewer(latest, installed);
+
+// A version read as semver: a leading `v` tolerated, any number of dotted numeric parts (a missing one is 0), a
+// prerelease after `-`, and build metadata after `+`, which never orders anything.
+export interface ParsedVersion {
+    readonly parts: readonly number[];
+    // The dot-separated prerelease identifiers; empty for a release.
+    readonly prerelease: readonly string[];
+}
+
+const VERSION = /^v?(\d+(?:\.\d+)*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/i;
+
+// Undefined for anything that is not a version (`unknown`, `latest`, an empty string).
+export const parseVersion = (version: string): ParsedVersion | undefined => {
+    const match = VERSION.exec(version.trim());
+    if (match === null) {
+        return undefined;
+    }
+    return { parts: match[1]!.split(`.`).map(Number), prerelease: match[2] === undefined ? [] : match[2].split(`.`) };
+};
+
+// Semver's rule for one identifier: numbers numerically and below words, words by ASCII.
+const compareIdentifier = (left: string, right: string): number => {
+    const [leftNumeric, rightNumeric] = [/^\d+$/.test(left), /^\d+$/.test(right)];
+    if (leftNumeric && rightNumeric) {
+        return Number(left) - Number(right);
+    }
+    if (leftNumeric !== rightNumeric) {
+        return leftNumeric ? -1 : 1;
+    }
+    return left < right ? -1 : left > right ? 1 : 0;
+};
+
+const comparePrerelease = (left: readonly string[], right: readonly string[]): number => {
+    // A release outranks every prerelease of itself: 1.2.0 > 1.2.0-rc.1.
+    if (left.length === 0 || right.length === 0) {
+        return right.length - left.length;
+    }
+    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+        const [l, r] = [left[index], right[index]];
+        if (l === undefined || r === undefined) {
+            // Equal so far, so the longer set of identifiers is the later one: rc.1.1 > rc.1.
+            return l === undefined ? -1 : 1;
+        }
+        const difference = compareIdentifier(l, r);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+};
+
+// Negative when `a` is older, positive when newer, zero when the same release, as a sort comparator wants (sort
+// descending with `(a, b) => compareVersions(b, a)`). Anything that does not parse sorts below every version and
+// equal to anything else that does not parse, so "unknown" never outranks a real release. `isNewer` above stays the
+// numeric-only reading the update nag is built on, which treats a prerelease segment as uncertainty.
+export const compareVersions = (a: string, b: string): number => {
+    const [left, right] = [parseVersion(a), parseVersion(b)];
+    if (left === undefined || right === undefined) {
+        return (left === undefined ? 0 : 1) - (right === undefined ? 0 : 1);
+    }
+    for (let index = 0; index < Math.max(left.parts.length, right.parts.length); index += 1) {
+        const difference = (left.parts[index] ?? 0) - (right.parts[index] ?? 0);
+        if (difference !== 0) {
+            return Math.sign(difference);
+        }
+    }
+    return Math.sign(comparePrerelease(left.prerelease, right.prerelease));
+};