@intentic/sandbox-contract 1.331.0 → 1.333.0

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

@@ -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" },
@@ -223,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

@@ -36,6 +36,19 @@ 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`]]);
+    });
+
+    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"]] },
 
@@ -66,6 +68,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/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/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));
+};

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

package/src/text/embed.test.ts

@@ -47,6 +47,20 @@ test("a JSON fetch answers the body or throws the refusal", async () => {
         jest.fn(async () => new Response(JSON.stringify({ error: "rate limited" }), { status: 429 })),
     );
     await expect(fetchEmbedJson("https://x/y")).rejects.toMatchObject({ message: "rate limited", status: 429 });
+    stubGlobal(
+        "fetch",
+        jest.fn(async () => new Response("<html>bad gateway</html>", { status: 502 })),
+    );
+    await expect(fetchEmbedJson("https://x/y")).rejects.toMatchObject({ message: "request failed (502)", status: 502 });
+    unstubAllGlobals();
+});
+
+test("a door that cannot be reached says so in words a visitor can read, without the URL", async () => {
+    stubGlobal(
+        "fetch",
+        jest.fn(async () => { throw new TypeError("Failed to fetch"); }),
+    );
+    await expect(fetchEmbedJson("https://x/y")).rejects.toThrow("The server could not be reached: Failed to fetch");
     unstubAllGlobals();
 });