@intentic/sandbox-contract 1.311.0 → 1.313.0

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

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

package/src/schemas/settings-history.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { dropAll, fold, isJsonObject, mapValue, retype } from "../documents/conversions.js";
+import type { KeepWarmSettings, RuleSchema } from "./settings.js";
+
+// The conversions the settings shape has had, oldest first: what brings any earlier release's settings to
+// SandboxSettingsSchema. Two documents carry this shape, the daemon's settings.json and a sandbox.toml's [settings]
+// table, and both read through this one list; it sits beside the schema so that neither reader has to reach into the
+// other for it. A name retired here stays retired: no later setting may take it to mean something else.
+
+// Rules at a moment or with an action a later version withdrew (the `push.starting` moment, `instruct` actions, three
+// built-in checks) can never run, and one of them made the whole file unreadable, every setting in it with it.
+const RETIRED_MOMENTS: ReadonlySet<unknown> = new Set(["push.starting"]);
+const RETIRED_ACTIONS: ReadonlySet<unknown> = new Set(["instruct"]);
+const RETIRED_BUILTINS: ReadonlySet<unknown> = new Set(["verify-edits", "verify-removals", "verify-tests"]);
+
+const isRetiredRule = (rule: unknown): boolean => {
+    if (!isJsonObject(rule)) {
+        return false;
+    }
+    const action = isJsonObject(rule["action"]) ? rule["action"] : {};
+    return RETIRED_MOMENTS.has(rule["moment"]) || RETIRED_ACTIONS.has(action["kind"]) || (action["kind"] === "builtin" && RETIRED_BUILTINS.has(action["name"]));
+};
+
+const holdsRetiredRule = (value: unknown): value is readonly unknown[] => Array.isArray(value) && value.some(isRetiredRule);
+
+// A rule at the `turn.ending` moment reads and runs nothing since nothing checks inside a turn (its moment and the
+// `verify-ui-edits` built-in stay in the read schema so a file written before reads); dropped, so it stops showing as a
+// rule the owner has and stops travelling with the settings.
+const isInertRule = (rule: unknown): boolean =>
+    isJsonObject(rule) &&
+    (rule["moment"] === "turn.ending" || (isJsonObject(rule["action"]) && rule["action"]["kind"] === "builtin" && rule["action"]["name"] === "verify-ui-edits"));
+
+const holdsInertRule = (value: unknown): value is readonly unknown[] => Array.isArray(value) && value.some(isInertRule);
+
+// keep-warm's four top-level settings (2026-09-26), folded into the one `keepWarm` object; a value of the wrong type is
+// left out, for the schema's own default to fill.
+const KEEP_WARM_FLAT = ["keepWarm", "keepWarmHours", "keepWarmMinTokens", "keepWarmReserve"] as const;
+const FlatSwitch = z.boolean();
+const FlatNumber = z.number();
+const keepWarmObject = fold("folds keepWarm, keepWarmHours, keepWarmMinTokens and keepWarmReserve into one keepWarm object", {
+    from: KEEP_WARM_FLAT,
+    into: "keepWarm",
+    applies: (settings) => FlatSwitch.safeParse(settings["keepWarm"]).success || KEEP_WARM_FLAT.slice(1).some((key) => Object.hasOwn(settings, key)),
+    convert: ({ keepWarm, keepWarmHours, keepWarmMinTokens, keepWarmReserve }): Partial<KeepWarmSettings> => {
+        const folded: Partial<KeepWarmSettings> = {};
+        const auto = FlatSwitch.safeParse(keepWarm);
+        const hours = FlatNumber.safeParse(keepWarmHours);
+        const minTokens = FlatNumber.safeParse(keepWarmMinTokens);
+        const reserve = FlatNumber.safeParse(keepWarmReserve);
+        if (auto.success) {
+            folded.auto = auto.data;
+        }
+        if (hours.success) {
+            folded.hours = hours.data;
+        }
+        if (minTokens.success) {
+            folded.minTokens = minTokens.data;
+        }
+        if (reserve.success) {
+            folded.reserve = reserve.data;
+        }
+        return folded;
+    },
+});
+
+export const SETTINGS_HISTORY = [
+    // Every setting a release since 2026-08-10 had and this one does not (read off the contract lock's history):
+    // retired, so passthrough stops carrying them, a definition naming one still applies, and no later setting may
+    // take one of these names to mean something else.
+    ...dropAll([
+        "agentRunEffort",
+        "agentRunModel",
+        "agentRunModels",
+        "autoFastModels",
+        "autoTier",
+        "autoTierEagerness",
+        "commandJudgeModels",
+        "commandRules",
+        "contextShelf",
+        "dependencyFreshness",
+        "explainCommands",
+        "iqContext",
+        "iqContextHoldout",
+        "moveAfterLimit",
+        "quickModel",
+        "resumeAfterLimit",
+        "resumeAfterOutage",
+        "terseHoldout",
+        "terseOutput",
+        "testFaultDetection",
+    ]),
+    retype(
+        "rules",
+        holdsRetiredRule,
+        // What survives the filter is every rule this version can read; the parse after the chain says so.
+        (rules) => rules.filter((rule) => !isRetiredRule(rule)) as z.input<typeof RuleSchema>[],
+        "drops rules at a withdrawn moment or with a withdrawn action (push.starting, instruct, three built-in checks)",
+    ),
+    // suggest, the old default, becomes the new default: routing on.
+    mapValue("personaRouting", { off: false, suggest: true, auto: true }),
+    retype(
+        "rules",
+        holdsInertRule,
+        (rules) => rules.filter((rule) => !isInertRule(rule)) as z.input<typeof RuleSchema>[],
+        "drops rules at the retired turn.ending moment (and the verify-ui-edits built-in), which run nothing",
+    ),
+    keepWarmObject,
+] as const;

package/src/schemas/settings.test.ts

@@ -1,4 +1,6 @@
-import { RepoChecksFileSchema, RuleSchema, SandboxSettingsSchema } from "./settings.js";
+import { convertDocument } from "../documents/conversions.js";
+import { SETTINGS_HISTORY } from "./settings-history.js";
+import { RepoChecksFileSchema, RuleSchema, SandboxSettingsSchema, SandboxSettingsWriteSchema } from "./settings.js";
 
 // A rule that saves cleanly and silently does nothing is the failure this schema exists to refuse: an action, and a
 // built-in's name, are checked against the moment they are written at.
@@ -57,3 +59,54 @@ describe(`where a command lives`, () => {
         expect(file([{ when: `land`, run: `pnpm verify`, paths: [`src/**`] }])).toBe(false);
     });
 });
+
+// Nothing runs when a turn ends any more. A file written before still reads, its conversion drops the inert rule, and no
+// save may stand a new one there.
+describe(`the retired turn.ending moment`, () => {
+    const look = { id: `verify-ui-edits`, label: `Look at what changed`, moment: `turn.ending`, action: { kind: `builtin`, name: `verify-ui-edits` } };
+    const land = { id: `auto-land`, label: `land`, moment: `agent.finished`, action: { kind: `verdict`, verdict: `allow` } };
+
+    test(`still reads, so an older file parses`, () => {
+        expect(SandboxSettingsSchema.safeParse({ rules: [look, land] }).success).toBe(true);
+    });
+
+    test(`is refused on a save`, () => {
+        const saved = SandboxSettingsWriteSchema.safeParse(SandboxSettingsSchema.parse({ rules: [look, land] }));
+        expect(saved.error?.issues.map(({ message, path }) => ({ message, path }))).toEqual([
+            { message: `turn.ending is retired: nothing runs when a turn ends any more, so a rule cannot stand there`, path: [`rules`] },
+        ]);
+        expect(SandboxSettingsWriteSchema.safeParse(SandboxSettingsSchema.parse({ rules: [land] })).success).toBe(true);
+    });
+
+    test(`is dropped from a stored file by its conversion, which leaves every other rule and settles`, () => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { rules: [look, land] }, true);
+        expect(converted.value).toEqual({ rules: [land] });
+        expect(converted.changes.map(({ conversion }) => conversion)).toEqual([
+            `drops rules at the retired turn.ending moment (and the verify-ui-edits built-in), which run nothing`,
+        ]);
+    });
+});
+
+// keep-warm's four top-level settings became one object on 2026-09-26; a stored file keeps what its owner picked.
+describe(`the folded keep-warm settings`, () => {
+    test(`fold into one object, keeping each value and the key's place`, () => {
+        const stored = { timezone: `Europe/Warsaw`, keepWarm: true, keepWarmHours: 6, keepWarmMinTokens: 50_000, keepWarmReserve: 20, iqSearch: true };
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, stored, true);
+        expect(converted.value).toEqual({ timezone: `Europe/Warsaw`, keepWarm: { auto: true, hours: 6, minTokens: 50_000, reserve: 20 }, iqSearch: true });
+        expect(JSON.stringify(converted.value)).toBe(
+            `{"timezone":"Europe/Warsaw","keepWarm":{"auto":true,"hours":6,"minTokens":50000,"reserve":20},"iqSearch":true}`,
+        );
+        expect(SandboxSettingsSchema.parse(converted.value).keepWarm).toEqual({ auto: true, hours: 6, minTokens: 50_000, reserve: 20 });
+    });
+
+    test(`fold a file that set only some, leaving the rest to the defaults`, () => {
+        const converted = convertDocument(SETTINGS_HISTORY, `object`, { keepWarmReserve: 30 }, true);
+        expect(converted.value).toEqual({ keepWarm: { reserve: 30 } });
+        expect(SandboxSettingsSchema.parse(converted.value).keepWarm).toEqual({ auto: false, hours: 4, minTokens: 100_000, reserve: 30 });
+    });
+
+    test(`leave a file already in the new shape alone`, () => {
+        const current = { keepWarm: { auto: true, hours: 2 } };
+        expect(convertDocument(SETTINGS_HISTORY, `object`, current, true).changes).toEqual([]);
+    });
+});

package/src/schemas/settings.ts

@@ -13,13 +13,15 @@ export const SystemPromptModeSchema = z.enum(["intentic", "claude", "custom"]);
 export type SystemPromptMode = z.infer<typeof SystemPromptModeSchema>;
 // Excludes "custom": there is nothing to fetch, it's whatever the owner already typed into the settings field.
 export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"]) });
-// Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version) and switch the
-// daemon's built-in reviews; every command a moment runs is a repository's own check (`<repo>/.intentic/checks.json`),
-// compiled into this same table by the daemon, so no command lives in settings.
+// Rules: "at this moment, if this is true, do this". The owner's rules decide (land, hold, version); every command a
+// moment runs is a repository's own check (`<repo>/.intentic/checks.json`), compiled into this same table by the daemon,
+// so no command lives in settings. Nothing verifies inside a turn: the whole-tree check runs after work lands and never
+// holds anything (schemas/workspace/mainline.ts).
 export const RuleMomentSchema = z.enum([
     // A command here runs on the just-written file (`{file}` is its path); the cheapest moment to catch a defect.
     "file.edited",
-    // The assistant is about to stop. A rule here can send it back to work, which is the only moment that can.
+    // Retired: the assistant stopping. Nothing runs here any more and nothing sends a turn back to work; the value stays
+    // so settings written before it went still read, and a rule standing here is inert.
     "turn.ending",
     // An agent's turn is over and its delta is sitting on its branch. A rule here decides whether it lands.
     "agent.finished",
@@ -30,7 +32,8 @@ export type RuleMoment = z.infer<typeof RuleMomentSchema>;
 // command: a repository's check; its exit code is the verdict.
 // verdict: allows or holds what is about to happen.
 // builtin: a daemon behaviour that reads a record only the daemon keeps.
-// verify-ui-edits: rendered surfaces a turn changed, against whether it ever looked at one.
+// verify-ui-edits: retired with `turn.ending`, read only so older settings parse; whether a turn looked at the surfaces it
+// changed is recorded on its card instead (AgentSummary.proof), never asked of the model.
 // version-landed: commits what a land brought, in the main tree, under the subject drafted for it, and the tree's own
 // remainder before the next isolated turn starts; the only way a person who never commits keeps every agent seeing
 // the latest tree, since worktrees are cut from HEAD.
@@ -47,8 +50,8 @@ export const RuleActionSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("builtin"), name: RuleBuiltinSchema }),
 ]);
 export type RuleAction = z.infer<typeof RuleActionSchema>;
-// `checks-failed` is a clean turn whose `turn.ending` check went red on the tree about to land; unlike the others, it
-// defaults to HELD unless a rule explicitly allows it.
+// `checks-failed` was a clean turn whose `turn.ending` check went red. Nothing produces it now that no check runs inside a
+// turn, and a check never holds work; it stays so older rules naming it still read.
 export const RuleOutcomeSchema = z.enum(["clean", "error", "conflict", "checks-failed"]);
 export type RuleOutcome = z.infer<typeof RuleOutcomeSchema>;
 // Every key absent means the rule always matches.
@@ -57,9 +60,10 @@ export const RuleConditionSchema = z.object({
     repo: z.string().min(1).optional(),
     // Globs the change has to touch for the rule to fire. Absent/empty ⇒ any.
     paths: z.array(z.string().min(1)).max(20).optional(),
-    // How the turn ended. Absent/empty ⇒ any, except that `checks-failed` never lands by omission.
+    // How the turn ended. Absent/empty ⇒ any.
     outcome: z.array(RuleOutcomeSchema).optional(),
-    // The fraction of occasions a rule fires on, at moments that draw one (turn.ending); absent ⇒ every occasion.
+    // The fraction of occasions a rule fires on, at a moment that draws one; absent ⇒ every occasion. No moment draws
+    // now that `turn.ending` is retired, so a sampled rule fires every time.
     sample: z.number().gt(0).lt(1).optional(),
 });
 export type RuleCondition = z.infer<typeof RuleConditionSchema>;
@@ -94,6 +98,9 @@ export const RuleSchema = z
         path: ["action"],
     });
 export type Rule = z.infer<typeof RuleSchema>;
+// A rule at a retired moment or with a retired built-in: read, so an older file parses, but never written again.
+export const isRetiredMomentRule = (rule: Pick<Rule, "moment" | "action">): boolean =>
+    rule.moment === "turn.ending" || (rule.action.kind === "builtin" && rule.action.name === "verify-ui-edits");
 // Kept out of the settings object on purpose: a firing is not an edit, and writing config on every push would make
 // every run a settings save.
 export const RuleFiringsSchema = z.record(z.string(), z.number());
@@ -182,7 +189,42 @@ export type SkillSwitch = z.infer<typeof SkillSwitchSchema>;
 // Opt-in settings the /settings routes edit and streamAgent reads, defaulting off so each can be A/B tested (`skills`
 // defaults on for the baked tools worth having, since a skill file is the only thing that tells the agent a baked
 // binary exists). Every default lives in the schema, so an older settings file still parses and keeps the owner's other
-// picks rather than failing whole.
+// picks rather than failing whole. A setting removed or reshaped here gets its conversion in settings-history.ts, which
+// also names every retired setting, none of whose names may come back.
+
+// keep-warm's knobs, one object since each only means anything beside the others (cache-keepwarm.ts).
+export const KeepWarmSettingsSchema = z.object({
+    auto: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Keep a Claude conversation's prompt cache warm after each turn a person asked for. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation.",
+        ),
+    hours: z
+        .number()
+        .min(1)
+        .max(8)
+        .default(4)
+        .describe(
+            "How long an idle conversation is kept warm after its last turn, in hours, and what a press on one offers first. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
+        ),
+    minTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe("Only conversations at least this large, in tokens, are kept warm by `auto`: a small one is cheap to re-read anyway."),
+    reserve: z
+        .number()
+        .int()
+        .min(0)
+        .max(90)
+        .default(15)
+        .describe(
+            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
+        ),
+});
+export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;
 
 export const SandboxSettingsSchema = z.object({
     // The zone every WALL-CLOCK RULE in this sandbox is meant in — an automation's cron, and anything else that says
@@ -387,46 +429,37 @@ export const SandboxSettingsSchema = z.object({
         .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.",
         ),
-    // Off by default: every refresh spends the account's own allowance on a conversation nobody is using yet.
-    keepWarm: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep a Claude conversation's prompt cache warm after each turn a person asked for, so coming back to it hours later costs a cache read instead of re-sending everything. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation. Any one conversation can be kept warm or let cool by hand either way.",
-        ),
-    keepWarmHours: z
-        .number()
-        .min(1)
-        .max(8)
-        .default(4)
-        .describe(
-            "How long an idle conversation is kept warm after its last turn, in hours. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
-        ),
-    keepWarmMinTokens: z
-        .number()
-        .int()
-        .min(0)
-        .default(100_000)
-        .describe("Only conversations at least this large, in tokens, are kept warm by themselves: a small one is cheap to re-read anyway."),
-    keepWarmReserve: z
-        .number()
-        .int()
-        .min(0)
-        .max(90)
-        .default(15)
-        .describe(
-            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
-        ),
+    // 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).
+    keepWarm: KeepWarmSettingsSchema.prefault({}).describe(
+        "Keeping an idle conversation's prompt cache warm, so coming back to it hours later costs a cache read instead of re-sending everything. Any one conversation can be kept warm or let cool by hand whatever `auto` says.",
+    ),
     // Worth it since the container is recreated on every update or environment approval — otherwise approving a
     // Dockerfile change costs the run that asked for it.
-    // What happens to breakage found after the work that caused it has left the turn: a land that turns the main tree's own
-    // check red is sent back to the conversation that landed it, and main's CI staying red on one failure gets a fix agent
-    // once pushes go quiet, with a fleet failure re-run instead. Off, both are only reported.
+    // What happens to breakage found after the work that caused it has left the turn. A land that turns the main tree's own
+    // check red waits for the lands queued behind it to be checked too, then goes back to the conversation that landed it
+    // while that one still has it in mind, or to a fresh conversation when nobody can be named or the one named has gone
+    // cold; main's CI staying red on one failure gets a fix agent once pushes go quiet, with a fleet failure re-run instead.
+    // Off, all of it is only reported.
     autoRepair: z
         .boolean()
         .default(true)
         .describe(
-            "Whether breakage found after the work left its turn is repaired without asking: a land that turns the main tree's check red goes back to the conversation that landed it, and main's CI staying red on the same failure gets a fix agent once pushes go quiet. A failure on the CI fleet itself is re-run once instead. Off, both are only reported.",
+            "Whether breakage found after the work left its turn is repaired without asking. A land that turns the main tree's check red is repaired once the work queued behind it has been checked too: by the conversation that landed it while it still has the work in mind, otherwise by a fresh conversation handed the failures and the suspects' changes. Main's CI staying red on the same failure gets a fix agent once pushes go quiet, and a failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
+        ),
+    // Where heavy work runs: a runner (the same image, on one of the owner's machines) instead of this sandbox. Keyed by
+    // the heavy-command rule an agent's command matched (system/resources/heavy-commands.ts), and one entry for the
+    // check after landing, 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 (portability/definition.ts), which must not pass
+    // work on again.
+    offload: z
+        .object({
+            commands: z.record(z.string().min(1), z.string().min(1)).default({}),
+            landCheck: z.string().min(1).optional(),
+        })
+        .default({ commands: {} })
+        .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…), and the check after landing. 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.",
         ),
     autoResumeOnRestart: z
         .boolean()
@@ -454,7 +487,7 @@ export const SandboxSettingsSchema = z.object({
             message: "a command belongs in the repository's own .intentic/checks.json, not in settings",
         })
         .describe(
-            "Standing decisions about the sandbox's own work: land or hold finished work, save a version of what landed, ask the assistant to look at an interface it changed. Empty is the default and is exactly the behaviour of a fresh sandbox, because each of those defaults is what no rule matched means at its own moment. A command to run is a repository's own check, declared in its .intentic/checks.json.",
+            "Standing decisions about the sandbox's own work: land or hold finished work, save a version of what landed. Empty is the default and is exactly the behaviour of a fresh sandbox, because each of those defaults is what no rule matched means at its own moment. A command to run is a repository's own check, declared in its .intentic/checks.json.",
         ),
     automationFailureLimit: z
         .number()
@@ -496,6 +529,12 @@ export const SandboxSettingsSchema = z.object({
         .describe("How many levels deep the delegation may go, since a subagent can start subagents of its own."),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
+// What a save takes: the settings as read, less what is only read. `turn.ending` (and its `verify-ui-edits` built-in) is
+// retired; a file written before still parses (and its conversion drops such rules), but no save may stand a new one.
+export const SandboxSettingsWriteSchema = SandboxSettingsSchema.refine((settings) => !settings.rules.some(isRetiredMomentRule), {
+    message: "turn.ending is retired: nothing runs when a turn ends any more, so a rule cannot stand there",
+    path: ["rules"],
+});
 
 // A browser telling the sandbox which clock IT is on. An offer, not an instruction: see `adoptTimezone`.
 export const TimezoneOfferSchema = z.object({
@@ -626,9 +665,9 @@ export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 // spelling for the daemon that reads it, the screen that names it and the demo that mimics it.
 export const REPO_CHECKS_FILE = `${STATE_DIR}/checks.json`;
 
-// Named for the occasion as a repository would say it: `edit` is `file.edited`, `turn` is `turn.ending`, and `land` is
-// the daemon's run over the main tree after an install a land caused (rules/repo-checks.ts maps them). A push is gated by
-// the repository's own git pre-push hook, which every push runs, the app's included.
+// Named for the occasion as a repository would say it: `edit` is `file.edited`, and `land` is the daemon's run over the
+// main tree after every land (rules/repo-checks.ts maps them). `turn` is retired: nothing runs when a turn ends any more,
+// and a declaration naming it still reads but runs nothing. No check refuses a land, a commit or a push.
 // `edit` runs on one file (`{file}`) and its output rides back in the edit's own response, so a command declared there is
 // paid per edit and has to take the file.
 export const RepoCheckMomentSchema = z.enum(["edit", "turn", "land"]);
@@ -636,7 +675,7 @@ export type RepoCheckMoment = z.infer<typeof RepoCheckMomentSchema>;
 
 export const RepoCheckSchema = z.object({
     when: RepoCheckMomentSchema.describe(
-        "When to run it: `edit` on each file as it is written (`{file}` is its path), `turn` before the assistant finishes, `land` on the main tree after finished work lands (absent, the package's own verify or test script runs there).",
+        "When to run it: `edit` on each file as it is written (`{file}` is its path), `land` on the main tree after finished work lands (absent, the package's own verify or test script runs there). `turn` is retired and runs nothing: checks no longer run while a conversation works.",
     ),
     run: z.string().min(1).max(500).describe("The command, run in this repository's own directory, so it reads as it would in a terminal there."),
     label: z.string().min(1).max(80).optional().describe("What to call it on screen. Absent names it after the command."),

package/src/schemas/speaker.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import type { MessageVoice } from "./agent.js";
+import type { SessionOwner } from "./agents.js";
+
+// WHO IS SPEAKING, as the sandbox verified it: one typed value every door builds once, from which the older one-line
+// facts are derived (the message's `voice`, the turn's `actor` string, the conversation's `owner`), so no reader parses a
+// prefix to learn whether a person is at the keyboard. Shared with transcript rows that want to say who spoke. Named apart
+// from `Speaker` (agents.ts), which is only which side of a transcript a search snippet came from.
+
+export const TurnSpeakerSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("person"),
+        email: z.string().describe("The signed-in member, as the sandbox verified them."),
+        name: z.string().optional().describe("Their display name, where the sign-in carries one."),
+    }),
+    z.object({
+        kind: z.literal("program"),
+        token: z.string().describe("The label of the control token a person minted and handed to this program."),
+    }),
+    z.object({
+        kind: z.literal("agent"),
+        conversationId: z.string().describe("The conversation whose agent is speaking: a child reporting back, a peer's message."),
+    }),
+    z.object({
+        kind: z.literal("sandbox"),
+        source: z
+            .string()
+            .optional()
+            .describe("What in the sandbox spoke: an automation, a watch that fired, a job that ended, a repair. Absent when it does not say."),
+    }),
+]);
+export type TurnSpeaker = z.infer<typeof TurnSpeakerSchema>;
+
+// Prefixed so a token labelled like an email, or a conversation id, can never read as a person.
+const TOKEN_PREFIX = "token:";
+const AGENT_PREFIX = "agent:";
+
+/** The one-line attribution a turn and a queued message carry: a person's email, else the prefixed program or agent. */
+export const speakerActor = (speaker: TurnSpeaker): string | undefined => {
+    switch (speaker.kind) {
+        case "person":
+            return speaker.email;
+        case "program":
+            return `${TOKEN_PREFIX}${speaker.token}`;
+        case "agent":
+            return `${AGENT_PREFIX}${speaker.conversationId}`;
+        case "sandbox":
+            return undefined;
+    }
+};
+
+/** Whose words a message is: a program writes through a person's door, so it speaks with a person's voice. */
+export const speakerVoice = (speaker: TurnSpeaker): MessageVoice =>
+    speaker.kind === "program" ? "person" : speaker.kind === "agent" ? "agent" : speaker.kind === "sandbox" ? "sandbox" : "person";
+
+/** The member who owns what this speaker opens; a program, an agent and the sandbox own nothing, so theirs stay claimable. */
+export const speakerOwner = (speaker: TurnSpeaker): Pick<SessionOwner, "email" | "name"> | undefined => {
+    if (speaker.kind !== "person") {
+        return undefined;
+    }
+    const owner: Pick<SessionOwner, "email" | "name"> = { email: speaker.email };
+    if (speaker.name !== undefined) {
+        owner.name = speaker.name;
+    }
+    return owner;
+};
+
+/** A person, verified, at the keyboard: never a program holding a token a person minted. */
+export const spokenByPerson = (speaker: TurnSpeaker | undefined): boolean => speaker?.kind === "person";
+
+// WHAT A COMPOSED PROMPT IS FOR, when the sandbox or the app wrote it rather than whoever is named as speaking: a land's
+// breakage sent back to it, a fresh fix-up on a red main line and its later nudges, a note to a conversation still
+// working on what failed, the brief a person's press hands an agent (what a push left, main's red CI), a land conflict to
+// resolve. Carried on the turn and the row it opens, so a reader shows it as the sandbox's words, not the owner's, and
+// never has to recognise the prompt by its opening; the four openings older rows are recognised by stay what they are
+// (events/errands.ts, errandOfPrompt).
+export const TurnErrandSchema = z.enum([
+    "land-conflict",
+    "verify-nudge",
+    "land-breakage",
+    "land-fix",
+    "land-fix-nudge",
+    "land-held",
+    "push-fix",
+    "push-fix-nudge",
+    "ci-fix",
+    "ci-fix-nudge",
+]);
+export type TurnErrand = z.infer<typeof TurnErrandSchema>;

package/src/schemas/state-plan.test.ts

@@ -0,0 +1,69 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { STATE_DIR } from "@intentic/constants";
+import { packageRoot } from "@intentic/constants/node";
+import { STATE_PLAN_FORMAT, type StatePlan, StatePlanSchema, type StateStatus, StateStatusSchema } from "./state-plan.js";
+
+// The documents `ic` reads by field name, spelled once here: each golden file under golden/ is one of these examples
+// as JSON, and the Rust tests (_sandbox/ic/src/sandbox/preflight.rs, health.rs) parse the same files. A change here
+// that the committed file does not carry fails, naming the file; `INTENTIC_WRITE_GOLDEN=1` rewrites them, and the Rust
+// tests then say whether ic still reads them.
+
+const GOLDEN = join(packageRoot(import.meta.url), "golden");
+
+const clear: StatePlan = {
+    plan: STATE_PLAN_FORMAT,
+    version: "1.400.0",
+    engine: 84,
+    digest: "c8cff51cab20a2b5",
+    ok: true,
+    downgrade: false,
+    failures: [],
+    steps: [
+        { document: "conversations-db-schema", change: "upgrades the conversations database schema" },
+        { document: `${STATE_DIR}/config/personas.json`, change: `moves it from ${STATE_DIR}/identities.json` },
+    ],
+    converts: [
+        { document: `${STATE_DIR}/config/settings.json`, change: "converts personaRouting from its old values", detail: '"suggest" became true' },
+    ],
+    files: [`${STATE_DIR}/config/personas.json`],
+};
+
+const refused: StatePlan = {
+    plan: STATE_PLAN_FORMAT,
+    version: "1.400.0",
+    engine: 84,
+    digest: "c8cff51cab20a2b5",
+    ok: false,
+    downgrade: true,
+    failures: [{ document: `${STATE_DIR}/config/automations.json`, detail: 'conversion "converts numbered kinds" failed: no such kind' }],
+    steps: [],
+    converts: [],
+    files: [],
+};
+
+// The whole `/health` answer is the daemon's; ic reads only `state` out of it, so the golden carries just enough around it.
+const health: { readonly ok: true; readonly state: StateStatus } = { ok: true, state: { journal: "open", engine: 84 } };
+
+const goldens = [
+    { file: "state-plan-clear.json", value: StatePlanSchema.parse(clear) },
+    { file: "state-plan-refused.json", value: StatePlanSchema.parse(refused) },
+    { file: "health-state.json", value: { ...health, state: StateStatusSchema.parse(health.state) } },
+];
+
+test.each(goldens)("golden/$file is the contract's example, as the host reads it", ({ file, value }) => {
+    const path = join(GOLDEN, file);
+    const expected = `${JSON.stringify(value, undefined, 2)}\n`;
+    if (process.env["INTENTIC_WRITE_GOLDEN"] === "1") {
+        writeFileSync(path, expected);
+    }
+    expect(readFileSync(path, "utf8")).toBe(expected);
+});
+
+test("a marker plan an older ic wrote, with only what it kept, still reads", () => {
+    expect(StatePlanSchema.partial().extend({ ok: StatePlanSchema.shape.ok }).parse({ ok: true, downgrade: false, steps: [{ document: "a.json", change: "renames a to b" }] })).toEqual({
+        ok: true,
+        downgrade: false,
+        steps: [{ document: "a.json", change: "renames a to b" }],
+    });
+});

package/src/schemas/state-plan.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+// The daemon's state engine as the host reads it, in two documents a Rust binary (`ic`) parses by these field names:
+// the update pre-flight's one line (the target image's state-plan.ts, read by _sandbox/ic/src/sandbox/preflight.rs and
+// embedded verbatim in the staged-update marker), and the `state` of `/health` (read by _sandbox/ic/src/health.rs). The
+// golden files beside the contract (golden/) are this schema's examples, and the Rust tests assert against them.
+
+export const PlanStepSchema = z.object({
+    document: z.string().describe("The stored file, workspace-relative, or `<volume>:<path>` for one on another volume; a structural step's id."),
+    change: z.string().describe("What is done to it, in one line."),
+    detail: z.string().optional().describe("What was particular about this one: a conflict's losing value, a retired entry, a mapped value."),
+});
+export type PlanStep = z.infer<typeof PlanStepSchema>;
+
+export const PlanFailureSchema = z.object({
+    document: z.string().describe("The stored file whose conversion would fail, or the structural step that would."),
+    detail: z.string().describe("Why, in the conversion's own words."),
+});
+export type PlanFailure = z.infer<typeof PlanFailureSchema>;
+
+// The one format `ic` reads; any other is "no plan", never a guess at what its fields mean.
+export const STATE_PLAN_FORMAT = 1;
+
+export const StatePlanSchema = z.object({
+    plan: z.literal(STATE_PLAN_FORMAT).describe("The format of this line. A reader refuses any other rather than guessing at its fields."),
+    version: z.string().describe("The release of the image that planned it; 0.0.0 for a development build."),
+    engine: z.number().describe("The conversion count builds before the digest compared. Reported, never decided by."),
+    digest: z.string().describe("What identifies the planning build's conversion set: its episodes resume only under the same one."),
+    ok: z.boolean().describe("False when a conversion would fail on this sandbox's files, which refuses the update before anything is touched."),
+    downgrade: z.boolean().describe("A newer release than the planning build ran here: it opens what it cannot read read-only."),
+    failures: z.array(PlanFailureSchema).describe("Each conversion or step that would fail, and why."),
+    steps: z.array(PlanStepSchema).describe("What the first boot changes on disk: documents moved, structural steps run."),
+    converts: z
+        .array(PlanStepSchema)
+        .optional()
+        .describe("What the build's conversions change as its stores read these files, written by each store's next save. Absent from a build before it."),
+    files: z.array(z.string()).describe("Every file the first boot writes, workspace-relative where it can be."),
+});
+export type StatePlan = z.infer<typeof StatePlanSchema>;
+
+// The `state` of `/health`: whether an update's state changes are still uncommitted. The host rolls an update back when
+// the journal stays open, so this rides the same probe as the boot's progress.
+export const StateStatusSchema = z.object({
+    journal: z.enum(["open", "none"]).describe("Open from the start of a boot that changed stored files until that boot has converged."),
+    engine: z.number().describe("The running build's conversion count."),
+});
+export type StateStatus = z.infer<typeof StateStatusSchema>;