@intentic/sandbox-contract 1.332.0 → 1.333.0

package/src/schemas/system.ts

@@ -193,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."),
@@ -206,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."),
@@ -233,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()) });
@@ -319,6 +330,26 @@ export interface AuthenticationOptionsJSON {
     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({
@@ -359,6 +390,9 @@ export const DaemonHealthSchema = z.object({
     // 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>;
 
@@ -376,5 +410,10 @@ export const DaemonHealthReadingSchema = z.object({
     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>;

package/src/schemas/voice.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+// Speaking a reply aloud: which voices a sandbox can speak with, which one speaks a language, and the live wire the
+// editor plays speech over. The daemon's engine is src/speech/voice; the editor's half is
+// _editor/web/src/features/chat/voice. Dictation, the other direction, is schemas/speech.ts.
+
+// Where a voice is made. `kokoro` and `piper` run on this sandbox's own CPU (sherpa-onnx, the runtime dictation already
+// loads), so nothing leaves it; the rest are providers the owner connected with an API key of their own.
+export const VoiceEngineSchema = z.enum(["kokoro", "piper", "elevenlabs", "cartesia", "deepgram"]);
+export type VoiceEngine = z.infer<typeof VoiceEngineSchema>;
+
+export const CloudVoiceProviderSchema = z.enum(["elevenlabs", "cartesia", "deepgram"]);
+export type CloudVoiceProvider = z.infer<typeof CloudVoiceProviderSchema>;
+
+export const isCloudVoiceEngine = (engine: VoiceEngine): engine is CloudVoiceProvider => CloudVoiceProviderSchema.safeParse(engine).success;
+
+// A voice, as `<engine>/<name>`: `kokoro/af_heart`, `piper/pl_PL-gosia-medium`, `elevenlabs/<voice id>`. One string so a
+// setting, a preview and a log line all name a voice the same way.
+export const VOICE_ID = /^(kokoro|piper|elevenlabs|cartesia|deepgram)\/[\w.-]+$/u;
+export const VoiceIdSchema = z.string().regex(VOICE_ID);
+export type VoiceId = z.infer<typeof VoiceIdSchema>;
+
+export const voiceEngineOf = (id: VoiceId): VoiceEngine => VoiceEngineSchema.parse(id.slice(0, id.indexOf("/")));
+export const voiceNameOf = (id: VoiceId): string => id.slice(id.indexOf("/") + 1);
+
+// A language as an ISO 639-1 primary subtag, lowercased: `en`, `pl`. Regional voices (British English, Brazilian
+// Portuguese) are voices of the one language, chosen like any other.
+export const VoiceLanguageSchema = z.string().regex(/^[a-z]{2,3}$/u);
+
+// A provider the owner connected for speaking: its key stays in the sandbox's secrets, named here.
+export const CloudVoiceSchema = z.object({
+    provider: CloudVoiceProviderSchema.describe("Which provider speaks."),
+    secret: z.string().min(1).describe("The stored secret holding its API key, by name, as the Secrets page lists it."),
+    model: z.string().default("").describe("Which of its models speaks. Empty takes its fast default, the one made for conversation."),
+    voice: z.string().default("").describe("Which of its voices, by the provider's own voice id. Empty takes a default that speaks the language."),
+});
+export type CloudVoice = z.infer<typeof CloudVoiceSchema>;
+
+// The sandbox's speaking choices (SandboxSettings.voice).
+export const VoiceSettingsSchema = z.object({
+    replies: z
+        .boolean()
+        .default(true)
+        .describe(
+            "When you talk to the agent hands-free, have it answer out loud: a few spoken sentences saying what it did and what it needs from you, while the full reply stays on screen.",
+        ),
+    interrupt: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Stop speaking the moment you start talking over it. Off, the microphone rests while a reply is spoken, which is the safe choice on speakers: a voice the browser fails to cancel would otherwise be heard as yours.",
+        ),
+    speed: z.number().min(0.5).max(2).default(1).describe("How fast it speaks, 1 being the voice's own pace."),
+    voices: z
+        .record(VoiceLanguageSchema, VoiceIdSchema)
+        .default({})
+        .describe(
+            "Which voice speaks each language, where you picked one. A language left out is spoken by the connected provider when there is one, and otherwise by its default on this sandbox: Kokoro for the eight languages it speaks, Piper for the rest.",
+        ),
+    cloud: CloudVoiceSchema.optional().describe(
+        "A speech provider of your own, used for every language it speaks unless you picked a voice on this sandbox for it. Its key is a stored secret; text it speaks leaves the sandbox for that provider.",
+    ),
+});
+export type VoiceSettings = z.infer<typeof VoiceSettingsSchema>;
+
+// One voice the sandbox can speak with, as the settings page lists it.
+export const VoiceInfoSchema = z.object({
+    id: VoiceIdSchema,
+    label: z.string().describe("Its name as a person would say it."),
+    languages: z.array(VoiceLanguageSchema).describe("What it speaks; a regional voice lists its language."),
+    accent: z.string().optional().describe("The region it sounds from, where the language has several (US, GB, BR)."),
+    gender: z.enum(["female", "male"]).optional(),
+    // The download a local voice's model costs, the first time anything asks it to speak; shared by every voice of
+    // one model (Kokoro's 54 voices are one download).
+    model: z.string().optional().describe("The model a local voice lives in."),
+    bytes: z.number().optional().describe("How much that model downloads, the first time it speaks."),
+    installed: z.boolean().optional().describe("Its model is on this sandbox already."),
+});
+export type VoiceInfo = z.infer<typeof VoiceInfoSchema>;
+
+// GET /speech/voices: everything the settings page needs to choose.
+export const VoicesViewSchema = z.object({
+    voices: z.array(VoiceInfoSchema),
+    // The local default for every language a local voice speaks; what speaks a language nobody chose for.
+    defaults: z.record(VoiceLanguageSchema, VoiceIdSchema),
+    cloud: z
+        .object({
+            provider: CloudVoiceProviderSchema,
+            ready: z.boolean().describe("Its secret resolves, so it can be asked."),
+            languages: z.array(VoiceLanguageSchema).describe("What it speaks; any other language falls back to this sandbox's voices."),
+        })
+        .optional(),
+    provisioned: z.boolean().describe("This sandbox can run speech synthesis at all."),
+});
+export type VoicesView = z.infer<typeof VoicesViewSchema>;
+
+// Where the voice that speaks a phrase stands: its model on disk, still on its way, or a provider's.
+export const VoiceStatusSchema = z.object({
+    voice: VoiceIdSchema,
+    model: z.enum(["ready", "downloading", "absent", "failed", "cloud"]),
+    received: z.number().optional().describe("Bytes of the model fetched so far, while it downloads."),
+    total: z.number().optional().describe("The model's whole download, while it downloads."),
+    error: z.string().optional(),
+});
+export type VoiceStatus = z.infer<typeof VoiceStatusSchema>;
+
+// What a text is, so the daemon knows how to say it:
+// - `plain`: words to say as they are (a preview, a question card read out, Discord).
+// - `read`: a written reply read aloud whole: code is announced rather than spelled, tables and links shortened.
+// - `reply`: a written reply turned into a few spoken sentences first (the `spoken-reply` job, or its first lines when
+//   no model is set for it); the words chosen come back as `spoken` before they are heard.
+export const SpeakAsSchema = z.enum(["plain", "read", "reply"]);
+export type SpeakAs = z.infer<typeof SpeakAsSchema>;
+
+// The longest text one utterance takes: a long reply read whole, with headroom.
+export const MAX_SPOKEN_TEXT = 40_000;
+
+// GET /speech/say, a WebSocket (one per player, many utterances): `say` opens utterance `id`, `stop` ends it (and the
+// audio still queued for it is dropped). The daemon answers, per utterance, `status` while its voice's model is on
+// its way, `spoken` with the words chosen (always for `reply`, so they can be shown), then pairs of `audio` (a JSON
+// header) and one binary frame of that many mono s16le samples, then `done`. Utterances are spoken one at a time, in
+// the order they were asked.
+export const VoiceClientMessageSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("say"),
+        id: z.number(),
+        text: z.string().min(1).max(MAX_SPOKEN_TEXT),
+        as: SpeakAsSchema.default("plain"),
+        lang: z.string().optional().describe("The reader's language, a hint: the text's own language decides when it can be told."),
+        voice: VoiceIdSchema.optional().describe("Speak with this voice whatever the settings say: a preview."),
+        asked: z.string().max(4000).optional().describe("For `reply`: what the person asked, so the spoken answer can be in their language."),
+        conversationId: z.string().optional().describe("For `reply`: the conversation it answers, for the providers allowed to read it."),
+    }),
+    z.object({ type: z.literal("stop"), id: z.number() }),
+]);
+export type VoiceClientMessage = z.infer<typeof VoiceClientMessageSchema>;
+
+export const VoiceServerMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("status"), id: z.number(), status: VoiceStatusSchema }),
+    z.object({
+        type: z.literal("spoken"),
+        id: z.number(),
+        text: z.string().describe("The words about to be said."),
+        lang: VoiceLanguageSchema,
+        voice: VoiceIdSchema,
+    }),
+    z.object({
+        type: z.literal("audio"),
+        id: z.number(),
+        sampleRate: z.number(),
+        samples: z.number().describe("How many mono s16le samples the binary frame right after this one holds."),
+    }),
+    z.object({ type: z.literal("done"), id: z.number() }),
+    z.object({
+        type: z.literal("notice"),
+        id: z.number(),
+        message: z.string().describe("Something worth saying that did not stop it: a provider that failed, so this sandbox's voice spoke instead."),
+    }),
+    z.object({ type: z.literal("error"), id: z.number().optional(), message: z.string() }),
+]);
+export type VoiceServerMessage = z.infer<typeof VoiceServerMessageSchema>;

package/src/schemas/workspace/workspace-upload.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+// What the editor sends ahead of a drop so a re-drop only moves what changed: POST /workspace/upload-diff takes each
+// dropped file's destination path with its source size and mtime (ms, from File.lastModified), and answers the paths
+// already identical on disk, whose bytes then never upload.
+export const UploadManifestSchema = z.object({
+    files: z.array(z.object({ path: z.string(), size: z.number(), mtime: z.number() })),
+});
+export type UploadManifest = z.infer<typeof UploadManifestSchema>;
+export const UploadSkipSchema = z.object({ skip: z.array(z.string()) });
+export type UploadSkip = z.infer<typeof UploadSkipSchema>;

package/src/state/arrival.ts

@@ -108,6 +108,9 @@ export const ArrivalHostSchema = z.object({
 export type ArrivalHost = z.infer<typeof ArrivalHostSchema>;
 export const ArrivalHostsSchema = z.object({ hosts: z.array(ArrivalHostSchema) });
 
+// DELETE /arrivals: whether there was a held plan to put away.
+export const ArrivalAbandonedSchema = z.object({ ok: z.boolean() });
+
 // Reads a setup off a connected device instead of an upload; answers with a plan exactly like the upload door does.
 export const ArrivalScanSchema = z.object({ host: z.string().min(1) });
 export type ArrivalScan = z.infer<typeof ArrivalScanSchema>;

package/src/state/history-state.ts

@@ -227,6 +227,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
         portability: "identity",
         note: "Approve again from Approvals anything that was approved and had not run yet.",
     },
+    // The wakes automations hold for a person, one file each (the daemon's automations/held-wakes-store.ts): daemon-minted, so
+    // kept where no turn writes. They travel with the workspace as they always did; a countdown hold arrives waiting for a
+    // person, since the key that signed it stays behind.
+    { path: "automation-holds/", portability: "carry" },
+    { path: "automation-holds.key", portability: "identity", note: "A held wake that was counting down arrives waiting for your yes instead." },
     { path: "local-cert/", portability: "identity" },
 
     /* ---- the state engine's own bookkeeping (the daemon's store/evolution/state-journal.ts) ---- */

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

@@ -40,6 +40,15 @@ describe(`staleRuntimeQueryKeys`, () => {
     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`]]);
     });
+
+    it(`re-reads each paired-machine roster on its own door's push, and the sync state on a device's`, () => {
+        // The dialogs and rows that name a machine read one roster each (the editor's PAIRED_* and RUNNERS families), so a
+        // socket opening or closing, or a sync key enrolled, moves exactly the keys that show it.
+        expect(staleRuntimeQueryKeys([`hosts`])).toEqual([[`capabilities`], [`devices`], [`hosts`], [`sync-health`]]);
+        expect(staleRuntimeQueryKeys([`webext`])).toEqual([[`capabilities`], [`webext`]]);
+        expect(staleRuntimeQueryKeys([`phones`])).toEqual([[`capabilities`], [`phones`]]);
+        expect(staleRuntimeQueryKeys([`runners`])).toEqual([[`runners`]]);
+    });
 });
 
 describe(`RUNTIME_DOMAIN_BINDINGS`, () => {

package/src/state/runtime-state.ts

@@ -37,11 +37,13 @@ const RUNTIME_DOMAINS = [
     // Daemon-held; changes continuously (tokens, tool uses), so it's rate-limited rather than pushed per mutation.
     { domain: "subagents", invalidates: [["subagents"]] },
 
-    // Machines on the other end of a socket (devices, browsers, runners); "online" is the socket itself, never sampled.
-    // hosts/webext land on capabilities since a pairing card's state is literally the hub's online answer. `hosts` also
-    // carries a device reading that landed too late for the reader waiting on it (hosts/device-reports.ts).
-    { domain: "hosts", invalidates: [["capabilities"], ["devices"]] },
-    { domain: "webext", invalidates: [["capabilities"]] },
+    // Machines on the other end of a socket (devices, browsers, phones, runners); "online" is the socket itself, never
+    // sampled. hosts/webext/phones land on capabilities since a pairing card's state is literally the hub's online answer,
+    // and each on the roster its dialogs and rows read (`hosts`, `webext`, `phones`; the editor's PAIRED_* families).
+    // `hosts` also carries a device reading that landed too late for the reader waiting on it (hosts/device-reports.ts),
+    // and a desktop-sync enrollment made or revoked, which is what moves `sync-health` (GET /system/sync).
+    { domain: "hosts", invalidates: [["capabilities"], ["devices"], ["hosts"], ["sync-health"]] },
+    { domain: "webext", invalidates: [["capabilities"], ["webext"]] },
     { domain: "phones", invalidates: [["capabilities"], ["phones"]] },
     { domain: "runners", invalidates: [["runners"]] },
 

package/src/state/update-probation.test.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { CRASH_LOOP_RESTARTS, judgeProbation, type ProbationLook, probationStep, type ProbationStep, type ProbationVerdict, UPDATE_PROBATION } from "./update-probation.js";
+
+// The update probation policy and its rule, held to golden/update-probation.json: the cases hand-written from ic's Rust
+// (probation.rs), which builds every one of them too. A number or a reason that moves in one language and not the other
+// fails here or there, naming the case.
+
+interface JudgeCase {
+    readonly name: string;
+    readonly look: Partial<ProbationLook>;
+    readonly swap: { readonly at: number; readonly reach: string | null };
+    readonly now: number;
+    readonly graceMs?: number;
+    readonly verdict: ProbationVerdict;
+}
+interface StepCase {
+    readonly name: string;
+    readonly verdict: ProbationVerdict;
+    readonly strikes: number;
+    readonly over: boolean;
+    readonly step: ProbationStep;
+}
+
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "update-probation.json"), "utf8")) as {
+    readonly policy: Record<string, number>;
+    readonly base: ProbationLook;
+    readonly judge: JudgeCase[];
+    readonly steps: StepCase[];
+};
+
+test("the policy numbers are the ones the golden records for ic, to the unit", () => {
+    expect(Object.fromEntries(Object.entries(UPDATE_PROBATION))).toEqual(GOLDEN.policy);
+    expect(GOLDEN.policy).toHaveProperty("crashLoopRestarts", CRASH_LOOP_RESTARTS);
+});
+
+test.each(GOLDEN.judge)("judges: $name", ({ look, swap, now, graceMs, verdict }) => {
+    expect(judgeProbation({ ...GOLDEN.base, ...look }, swap, now, graceMs)).toEqual(verdict);
+});
+
+test.each(GOLDEN.steps)("steps: $name", ({ verdict, strikes, over, step }) => {
+    expect(probationStep(verdict, strikes, over)).toEqual(step);
+});

package/src/state/update-probation.ts

@@ -0,0 +1,169 @@
+// THE POLICY AN UPDATE IS HELD TO AFTER IT TOOK, one policy on two substrates.
+//
+// A new version of a sandbox that came up is not yet a version that works. On a machine `ic` runs, the old container stays
+// parked and ready while a watch looks at the new one (_sandbox/ic/src/sandbox/probation.rs), and puts the old one back
+// by itself if it keeps failing. On Fly the platform's api does the same job over the image the machine's row keeps as
+// its way back (_platform/api/src/sandbox/hosted/gate/hosted-probation.ts). The two cannot share code (one looks through
+// Docker, the other through Fly's exec), so they share what decides: the numbers below, and `judgeProbation` /
+// `probationStep`, the rule that turns one look at the new version into a verdict and a verdict into a step.
+//
+// `ic` owns the rule; this is its TS twin, and golden/update-probation.json holds each number and each case, hand-written
+// from the Rust: ic's test (probation.rs) and this package's test (update-probation.test.ts) both build every one, so
+// neither can drift without the other failing. A number changes here, in the golden and in ic's constant together.
+
+// Restarts that make a crash loop, whoever counts them: netd restarting a crashed daemon inside a container that stays up,
+// Docker restarting the container, Fly restarting the machine, or the editor reading a sandbox's vitals (diagnose.ts).
+// ic's health.rs CRASH_LOOP_RESTARTS and the platform's gate (daemon-health.ts) are this number too.
+export const CRASH_LOOP_RESTARTS = 3;
+
+export const UPDATE_PROBATION = {
+    // How long the version before an update is kept ready to go back to (`IC_PROBATION_SECONDS` shortens ic's, for its
+    // nightly drill), and how long the platform watches a hosted machine's new image.
+    watchMs: 24 * 60 * 60_000,
+    // How long a new version may stay not-ready, unreachable or silent before that counts against it: longer than any
+    // healthy first boot (state conversions, a cold cache), which the switch's own health wait already sat through.
+    graceMs: 10 * 60_000,
+    // An open state journal is a boot still converting; past this it is a boot that will not finish.
+    journalMs: 15 * 60_000,
+    // Consecutive failed looks that end a probation in a rollback: never one bad answer.
+    strikes: 3,
+    // Rollback targets kept BEYOND `previous`, newest first: older builds `ic sandbox rollback --to` reaches without a
+    // download (record.rs MAX_KEPT). The hosted row keeps only `previous`; see the platform's gate-row.ts.
+    keptBuilds: 2,
+    // Restarts that are a crash loop on their own, of the container and of the daemon inside it.
+    crashLoopRestarts: CRASH_LOOP_RESTARTS,
+} as const;
+
+// A tunnel that has been `checking` this much longer than the grace has not come up.
+const TUNNEL_EXTRA_MS = 5 * 60_000;
+
+// What one look at the new version found: the same facts ic gathers through Docker and the platform through Fly.
+// `null` is "not known" (a daemon too old to say), which is never held against a version.
+export interface ProbationLook {
+    // The container (the Fly machine) is running, and whether it is on its way down or up.
+    readonly running: boolean;
+    readonly restarting: boolean;
+    // How many times the container has restarted: past `crashLoopRestarts` it is a crash loop on its own.
+    readonly restarts: number;
+    // `/health` answered with a document.
+    readonly answered: boolean;
+    // `boot.ready` (or an older daemon's top-level `ready`).
+    readonly ready: boolean | null;
+    // `state.journal`: open, none, failed.
+    readonly journal: string | null;
+    // `reach.state`: off, checking, reachable, unreachable.
+    readonly reach: string | null;
+    // What the daemon wrote to /history/boot-failure.json after the swap began.
+    readonly bootFailure: string | null;
+    // How many times the watch has seen the daemon start again inside a running container.
+    readonly daemonRestarts: number;
+    // netd's own word that the daemon keeps crashing, already in words.
+    readonly crashLoop: string | null;
+    // The owner stopped it on purpose: there is nothing to judge until it runs.
+    readonly held: boolean;
+}
+
+// The facts of the swap a look is judged against: when the new version began, and how the old one's tunnel read.
+export interface ProbationSwap {
+    readonly at: number;
+    // Held only to a tunnel the old version had.
+    readonly reach: string | null;
+}
+
+export type ProbationVerdict =
+    // The strikes start over.
+    | { readonly kind: "healthy" }
+    // Too early to hold anything against it.
+    | { readonly kind: "pending" }
+    // One failed look.
+    | { readonly kind: "strike"; readonly reason: string }
+    // Nothing to wait for: go back now.
+    | { readonly kind: "fail"; readonly reason: string };
+
+const strike = (reason: string): ProbationVerdict => ({ kind: "strike", reason });
+const fail = (reason: string): ProbationVerdict => ({ kind: "fail", reason });
+const PENDING: ProbationVerdict = { kind: "pending" };
+
+// The condition a stopped-on-purpose, failed-boot, failed-conversion or crash-looping version is judged by, before the
+// slower ones. Split out so `judgeProbation` reads as the list of what it is judged on, in order.
+const failure = (look: ProbationLook): ProbationVerdict | undefined => {
+    if (look.bootFailure !== null) {
+        return fail(`the new version could not start: ${look.bootFailure}`);
+    }
+    if (look.journal === "failed") {
+        return fail("the new version could not convert this sandbox's stored files; it put them back as they were");
+    }
+    if (look.daemonRestarts >= UPDATE_PROBATION.crashLoopRestarts) {
+        return fail(`the new version's daemon kept crashing (${look.daemonRestarts} restarts)`);
+    }
+    if (look.crashLoop !== null) {
+        return fail(`the new version's daemon kept crashing: ${look.crashLoop}`);
+    }
+    return undefined;
+};
+
+// Held only to a tunnel the old version had: a sandbox reached on loopback alone has none to lose.
+const tunnel = (look: ProbationLook, swap: ProbationSwap, since: number, graceMs: number): ProbationVerdict | undefined => {
+    if (swap.reach !== "reachable") {
+        return undefined;
+    }
+    if (look.reach === "unreachable" && since >= graceMs) {
+        return strike("the new version cannot be reached through its tunnel");
+    }
+    if (look.reach === "checking" && since >= graceMs + TUNNEL_EXTRA_MS) {
+        return strike("the new version's tunnel never came up");
+    }
+    return look.reach === "unreachable" || look.reach === "checking" ? PENDING : undefined;
+};
+
+// The judgement, pure over one look, the swap and the clock: ic's `judge` (probation.rs), reason for reason.
+export const judgeProbation = (look: ProbationLook, swap: ProbationSwap, now: number, graceMs: number = UPDATE_PROBATION.graceMs): ProbationVerdict => {
+    const since = Math.max(0, now - swap.at);
+    const late = since >= graceMs;
+    // Stopped on purpose: there is nothing to judge, and going back would start a sandbox its owner stopped.
+    if (look.held && !look.running && !look.restarting) {
+        return PENDING;
+    }
+    const failed = failure(look);
+    if (failed !== undefined) {
+        return failed;
+    }
+    if (!look.running || look.restarting) {
+        return look.restarts >= UPDATE_PROBATION.crashLoopRestarts
+            ? fail(`the new version kept crashing (${look.restarts} restarts)`)
+            : strike("the new version's container is not running");
+    }
+    if (!look.answered) {
+        return late ? strike("the new version's daemon is not answering") : PENDING;
+    }
+    if (look.journal === "open") {
+        return since >= UPDATE_PROBATION.journalMs ? strike("the new version is still converting stored files after 15 minutes") : PENDING;
+    }
+    if (look.ready === false) {
+        return late ? strike("the new version never finished starting up") : PENDING;
+    }
+    return tunnel(look, swap, since, graceMs) ?? { kind: "healthy" };
+};
+
+// What the watch does with a verdict: go back, keep watching with the strikes as they now stand, or let the old version
+// go because the probation is over.
+export type ProbationStep =
+    | { readonly action: "roll-back"; readonly reason: string }
+    | { readonly action: "watch"; readonly strikes: number; readonly reason?: string }
+    | { readonly action: "keep" };
+
+// ic's judge_probation, as a decision over the verdict, the strikes so far and whether the probation is over. Pure.
+export const probationStep = (verdict: ProbationVerdict, strikes: number, over: boolean): ProbationStep => {
+    switch (verdict.kind) {
+        case "fail":
+            return { action: "roll-back", reason: verdict.reason };
+        case "strike":
+            return strikes + 1 >= UPDATE_PROBATION.strikes
+                ? { action: "roll-back", reason: verdict.reason }
+                : { action: "watch", strikes: strikes + 1, reason: verdict.reason };
+        case "healthy":
+            return over ? { action: "keep" } : { action: "watch", strikes: 0 };
+        case "pending":
+            return over ? { action: "keep" } : { action: "watch", strikes };
+    }
+};

package/src/state/workspace-state.ts

@@ -209,10 +209,13 @@ const STATE_FILES = [
         why: "A guard's own scratch file; the daemon never reads it and nothing in the browser renders it.",
         portability: "carry",
     },
+    // Where releases before 2026-10-12 kept the wakes automations held for a person. They now sit on the history volume
+    // (`automation-holds/`, history-state.ts), off the workspace every turn writes, and nothing reads this directory; a
+    // build that read it is only ever rolled back to. Declared still, since the extension that listed them binds it.
     {
         path: ".intentic/records/approvals/",
         invalidates: [],
-        why: "Declared by the intentic.approvals extension's contributes.files (the page that lists held wakes), `automation-approvals` is its query key, not core's.",
+        why: "Where releases before 2026-10-12 kept the wakes automations held for a person; they now sit on the history volume, and nothing reads this copy. The intentic.approvals extension's contributes.files still binds it, with `automation-approvals` as its query key, not core's.",
         portability: "carry",
     },
     // Bug-report inbox, one file per fingerprint (daemon's issues-store), rendered by intentic.issues. `carry`: a fact