@intentic/sandbox-contract 1.345.0 → 1.346.0

package/src/state/sandbox-build.test.ts

@@ -0,0 +1,95 @@
+import { DEV_SANDBOX_IMAGE } from "../policy/overlay-lint.js";
+import { buildParity, builtFromCheckout, rebuildPending, type RunningSandbox, type SandboxBuild, sameBuild, swapVerdict } from "./sandbox-build.js";
+
+// Every "which build" question is one of these, asked of two SandboxBuild records; a surface that compares fields of its
+// own choosing is how "pending rebuild" outlived a rebuild and a runner read outdated for good (2026-10).
+
+const stable = "ghcr.io/intentic/sandbox:stable";
+const digest = (byte: string): string => `sha256:${byte.repeat(64)}`;
+
+test("a rebuild is pending exactly when the overlay wanted is not the one running", () => {
+    expect(rebuildPending("h1", "h1")).toBe(false);
+    expect(rebuildPending("h2", "h1")).toBe(true);
+    // A stock container wanting an overlay waits for it; one wanting none waits for nothing, whatever it runs.
+    expect(rebuildPending("h1", undefined)).toBe(true);
+    expect(rebuildPending(undefined, undefined)).toBe(false);
+    expect(rebuildPending(undefined, "h1")).toBe(false);
+});
+
+test("a runner on the parent's base and overlay is current, and either moving is outdated", () => {
+    const parent: SandboxBuild = { base: stable, overlay: "abc123" };
+    expect(buildParity(parent, { ...parent })).toBe("current");
+    expect(buildParity(parent, { ...parent, overlay: "def456" })).toBe("outdated");
+    expect(buildParity(parent, { ...parent, base: "ghcr.io/intentic/sandbox:2.2.0" })).toBe("outdated");
+});
+
+test("an overlay on one side only is a difference; neither side having one is not", () => {
+    expect(buildParity({ base: stable }, { base: stable })).toBe("current");
+    expect(buildParity({ base: stable, overlay: "abc" }, { base: stable })).toBe("outdated");
+    expect(buildParity({ base: stable }, { base: stable, overlay: "abc" })).toBe("outdated");
+});
+
+// One tag is one name for whatever the registry held when each machine pulled it; the digest is the build.
+test("the base is compared by digest when both sides read one, and by its reference otherwise", () => {
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: stable, baseDigest: digest("b") })).toBe("outdated");
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: "ghcr.io/intentic/sandbox:beta", baseDigest: digest("a") })).toBe("current");
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: stable })).toBe("current");
+    expect(buildParity({ base: stable, baseDigest: digest("a") }, { base: "ghcr.io/intentic/sandbox:beta" })).toBe("outdated");
+});
+
+// Each machine's `intentic-sandbox:dev` is whatever its checkout held, so the name agreeing proves nothing, and an update
+// cannot bring it level: `ic` refuses to move a checkout build onto the published image (recreate.rs).
+test("nothing to compare, or a build from a checkout on either side, reads as unknown rather than as a warning", () => {
+    const parent: SandboxBuild = { base: stable, overlay: "abc" };
+    expect(buildParity(parent, undefined)).toBe("unknown");
+    expect(buildParity(parent, { base: "" })).toBe("unknown");
+    expect(buildParity({ base: "" }, parent)).toBe("unknown");
+    expect(buildParity({ base: DEV_SANDBOX_IMAGE, overlay: "abc" }, { base: DEV_SANDBOX_IMAGE, overlay: "abc" })).toBe("unknown");
+    expect(buildParity(parent, { base: DEV_SANDBOX_IMAGE, overlay: "abc" })).toBe("unknown");
+});
+
+// A rollback pin is a local tag too, and a rolled-back sandbox rejoins its channel by updating, not by a checkout.
+test("only the dogfood base is a build from a checkout", () => {
+    expect(builtFromCheckout({ base: DEV_SANDBOX_IMAGE })).toBe(true);
+    expect(builtFromCheckout({ base: stable })).toBe(false);
+    expect(builtFromCheckout({ base: "intentic-sandbox-rollback-demo:f6e917ce9b90" })).toBe(false);
+    expect(builtFromCheckout({ base: "" })).toBe(false);
+});
+
+// A swap is told landed by what answers, never by the version: a checkout build is 0.0.0 before and after, and an update
+// of one followed by "the version moved" waited out its deadline and said the sandbox never came back (2026-10).
+const running = (build: SandboxBuild, bootedAt: number): RunningSandbox => ({ build, bootedAt });
+
+test("two builds are the same only when something can tell, and differ the moment the overlay or digest does", () => {
+    expect(sameBuild({ base: stable, baseDigest: digest("a") }, { base: stable, baseDigest: digest("a") })).toBe(true);
+    expect(sameBuild({ base: stable, baseDigest: digest("a") }, { base: stable, baseDigest: digest("b") })).toBe(false);
+    expect(sameBuild({ base: stable, overlay: "h1" }, { base: stable, overlay: "h2" })).toBe(false);
+    expect(sameBuild({ base: stable }, { base: "ghcr.io/intentic/sandbox:beta" })).toBe(false);
+    expect(sameBuild({ base: stable }, { base: stable })).toBeUndefined();
+    expect(sameBuild({ base: DEV_SANDBOX_IMAGE }, { base: DEV_SANDBOX_IMAGE })).toBeUndefined();
+});
+
+test("an update of a checkout build lands on the new boot, though every version reads 0.0.0", () => {
+    const from = running({ base: DEV_SANDBOX_IMAGE }, 1000);
+    expect(swapVerdict({ from }, from)).toBe("waiting");
+    expect(swapVerdict({ from }, running({ base: DEV_SANDBOX_IMAGE }, 2000))).toBe("landed");
+});
+
+test("an update of a release lands when the digest moves, and a new boot on the old digest came back unmoved", () => {
+    const from = running({ base: stable, baseDigest: digest("a") }, 1000);
+    expect(swapVerdict({ from }, running({ base: stable, baseDigest: digest("b") }, 2000))).toBe("landed");
+    expect(swapVerdict({ from }, running({ base: stable, baseDigest: digest("a") }, 2000))).toBe("unmoved");
+    expect(swapVerdict({ from }, from)).toBe("waiting");
+    // A rollback names another tag: moved, digest or not.
+    expect(swapVerdict({ from: running({ base: stable }, 1000) }, running({ base: "ghcr.io/intentic/sandbox:0.9.0" }, 1000))).toBe("landed");
+});
+
+test("a rebuild lands on its overlay, and a new boot on any other overlay came back without it", () => {
+    const from = running({ base: stable, overlay: "old" }, 1000);
+    expect(swapVerdict({ from, overlay: "new" }, running({ base: stable, overlay: "new" }, 2000))).toBe("landed");
+    expect(swapVerdict({ from, overlay: "new" }, running({ base: stable, overlay: "old" }, 2000))).toBe("unmoved");
+    expect(swapVerdict({ from, overlay: "new" }, from)).toBe("waiting");
+    // Pressed with nothing read: only the overlay can say.
+    expect(swapVerdict({ from: undefined, overlay: "new" }, running({ base: stable, overlay: "new" }, 2000))).toBe("landed");
+    expect(swapVerdict({ from: undefined }, running({ base: stable }, 2000))).toBe("waiting");
+});

package/src/state/sandbox-build.ts

@@ -0,0 +1,96 @@
+import { DEV_SANDBOX_IMAGE } from "../policy/overlay-lint.js";
+
+// WHICH BUILD A SANDBOX IS, as one record, and every comparison made between two of them. A build is the base image it
+// sits on and the environment overlay built on that base, each by content: the base by its registry digest when the
+// runner read one, the overlay by the hash of the recipe built. A sandbox holds two at any moment, the build it runs
+// (stamped on its container) and the overlay it wants (composed from its approvals now); a parent and its runner hold
+// one each. "Rebuild pending" and runner parity are asked here and nowhere else. Each fix that once picked its own field
+// (an image tag for parity, a cached file for pending) stayed local while the next surface kept its own (2026-10).
+
+export interface SandboxBuild {
+    // The base image as the runner named it (SANDBOX_BASE_IMAGE, else the image itself); empty when no runner said.
+    readonly base: string;
+    // The base's registry digest (`sha256:…`) when the runner could read one: what makes `base` one exact image.
+    readonly baseDigest?: string | undefined;
+    // sha256 of the environment overlay built on the base; absent on a stock image.
+    readonly overlay?: string | undefined;
+}
+
+// Built on a base compiled from a checkout, which names whatever that machine's checkout held when it was built: it is
+// compared with nothing, and a newer build of it comes from the checkout rather than the registry.
+export const builtFromCheckout = (build: Pick<SandboxBuild, "base">): boolean => build.base === DEV_SANDBOX_IMAGE;
+
+// The overlay a sandbox wants is not the one it runs. Wanting none is nothing to rebuild; a container built with an
+// overlay whose every input has since gone still wants the bare one composed for it, which has a hash of its own.
+export const rebuildPending = (desired: string | undefined, running: string | undefined): boolean => desired !== undefined && desired !== (running ?? "");
+
+// Whether two sandboxes run the same code and environment: the base by digest when both sides read one (one tag pulled
+// on two machines at two moments is two builds), else by its reference, and the overlay by hash, none on both sides
+// agreeing. Unknown when either side named no base or was built from a checkout: nothing an update could bring level.
+export const buildParity = (parent: SandboxBuild, other: SandboxBuild | undefined): "current" | "outdated" | "unknown" => {
+    if (other === undefined || parent.base === "" || other.base === "" || builtFromCheckout(parent) || builtFromCheckout(other)) {
+        return "unknown";
+    }
+    const sameBase =
+        parent.baseDigest !== undefined && other.baseDigest !== undefined ? parent.baseDigest === other.baseDigest : parent.base === other.base;
+    return sameBase && (parent.overlay ?? "") === (other.overlay ?? "") ? "current" : "outdated";
+};
+
+// WHAT ANSWERS: the build a daemon runs and the moment it started, as /info reports it (`running`). A swap (a rebuild, an
+// update, a rollback) replaces the container, so the sandbox answering afterwards is a different boot; whether it is the
+// build the swap aimed at is the build's to say. A daemon's version cannot: every build from a checkout is 0.0.0, so a
+// swap told by "the version moved" never landed for one (2026-10).
+export interface RunningSandbox {
+    readonly build: SandboxBuild;
+    // Epoch ms this daemon started: a container swapped in is a new boot even where its build reads the same.
+    readonly bootedAt: number;
+}
+
+// Whether two builds are the same image and overlay: false when either differs, true when both bases carry a digest and
+// they and the overlays agree, undefined when nothing can tell (a checkout build, or one tag with no digest read on
+// either side, which two pulls a release apart both are).
+export const sameBuild = (a: SandboxBuild, b: SandboxBuild): boolean | undefined => {
+    if ((a.overlay ?? "") !== (b.overlay ?? "")) {
+        return false;
+    }
+    if (builtFromCheckout(a) || builtFromCheckout(b)) {
+        return undefined;
+    }
+    if (a.baseDigest !== undefined && b.baseDigest !== undefined) {
+        return a.baseDigest === b.baseDigest;
+    }
+    return a.base === b.base ? undefined : false;
+};
+
+// What a swap is aiming at, read when it was pressed: the sandbox answering then, and for a rebuild the overlay it builds.
+export interface SwapAim {
+    readonly from: RunningSandbox | undefined;
+    readonly overlay?: string | undefined;
+}
+
+// Where a swap stands by what answers now. `landed`: the sandbox runs what it aimed at (the overlay a rebuild built; for
+// an update or a rollback, a build other than the one pressed on, or a new boot where the builds cannot tell). `unmoved`:
+// a new boot answers on the very build it was pressed on, so the swap came back without taking. `waiting`: the sandbox
+// pressed on still answers, or nothing here can tell yet.
+export type SwapVerdict = "landed" | "unmoved" | "waiting";
+
+export const swapVerdict = (aim: SwapAim, now: RunningSandbox): SwapVerdict => {
+    const rebooted = aim.from !== undefined && now.bootedAt !== aim.from.bootedAt;
+    if (aim.overlay !== undefined) {
+        if (now.build.overlay === aim.overlay) {
+            return "landed";
+        }
+        return rebooted ? "unmoved" : "waiting";
+    }
+    if (aim.from === undefined) {
+        return "waiting";
+    }
+    const same = sameBuild(aim.from.build, now.build);
+    if (same === false) {
+        return "landed";
+    }
+    if (!rebooted) {
+        return "waiting";
+    }
+    return same === true ? "unmoved" : "landed";
+};

package/src/state/ways-back.test.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { DeviceFeatureSchema } from "../schemas/hosts.js";
+import { waysBack } from "./ways-back.js";
+
+// What `ic features --json` answers (_sandbox/ic/src/features.rs holds the same list to this golden).
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const IC_FEATURES = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "ic-features.json"), "utf8")) as { readonly features: readonly string[] };
+
+const pruned = (image: string, version: string) => ({ image, version, download: true });
+const kept = (image: string, version: string) => ({ image, version });
+
+test("every feature ic says it has is one the contract knows, the reachable listing among them", () => {
+    for (const feature of IC_FEATURES.features) {
+        expect(DeviceFeatureSchema.safeParse(feature).success).toBe(true);
+    }
+    expect(IC_FEATURES.features).toContain("reachable-ways-back");
+});
+
+test("a current ic's ways back are offered as it lists them, each image once", () => {
+    const current = { features: [...IC_FEATURES.features] };
+    const pin = kept("pin:a", "1.2.0");
+    const release = pruned("ghcr.io/intentic/sandbox:1.1.0", "1.1.0");
+    expect(waysBack(current, [pin, pin, release])).toEqual([pin, release]);
+});
+
+// 2026-10-19: an ic from before then listed pruned dev builds, rows of 0.0.0 no download can bring back.
+test("an older ic's rows it could never reach are left out, and only those", () => {
+    const older = { features: ["rollback-to", "sleep"] };
+    const dev = kept("pin:dev", "0.0.0");
+    const release = pruned("pin:gone", "1.1.0");
+    const rows = [dev, pruned("pin:gone-dev", "0.0.0"), release, { image: "pin:nameless", download: true }];
+    expect(waysBack(older, rows)).toEqual([dev, release]);
+    expect(waysBack(undefined, rows)).toEqual([dev, release]);
+});

package/src/state/ways-back.ts

@@ -0,0 +1,19 @@
+import { DEVICE_FEATURE_REACHABLE_WAYS_BACK, type DeviceFacts, deviceSupports } from "../schemas/hosts.js";
+import type { RollbackTarget } from "../schemas/updates.js";
+import { DEV_VERSION } from "./versions.js";
+
+// THE WAYS BACK A SANDBOX ROW OFFERS, as the device's ic means them (2026-10-20). An ic from 2026-10-19 on lists only the
+// ways back a rollback can reach (versions.rs `ways_back`) and says so in the device's features (`reachable-ways-back`,
+// ic's own `ic features`): its rows are offered as they are. An older ic also listed every pin pruned outside it, each as
+// a download of its version, and a dev build's version is 0.0.0, which no registry publishes: three rows of "0.0.0", none
+// of which could be had. Only for such a host are the rows an older ic could not reach left out, by that ic's own rule
+// (a download needs a published version), rather than every host's rows being filtered on a guess. Either way each image
+// is offered once.
+
+// A release the registry publishes an image under: a dotted version, and not the one every dev build says.
+const published = (version: string | undefined): boolean => version !== undefined && /^v?\d+\.\d+\.\d+$/u.test(version) && version.replace(/^v/u, "") !== DEV_VERSION;
+
+export const waysBack = <T extends Pick<RollbackTarget, "image" | "version" | "download">>(facts: Pick<DeviceFacts, "features"> | undefined, targets: readonly T[]): T[] => {
+    const once = [...new Map(targets.map((target) => [target.image, target])).values()];
+    return deviceSupports(facts, DEVICE_FEATURE_REACHABLE_WAYS_BACK) ? once : once.filter((target) => target.download !== true || published(target.version));
+};

package/src/state/workspace-state.ts

@@ -210,7 +210,7 @@ const STATE_FILES = [
         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
+    // (`automation-holds/`, the daemon's held-wakes-store.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/",

package/src/text/land-rows.ts

@@ -0,0 +1,111 @@
+import type { AgentEvent } from "../events/agent-events.js";
+import type { TranscriptRow } from "../events/transcript.js";
+import { noticeCode } from "../events/sandbox-notice.js";
+
+// The notices a turn's work leaves as it moves: an install starting, the branch rebased onto the workspace while it
+// waited, and where the finished work went (landed, held, conflicted, or into a parent's checkout).
+
+// Clause appended to the landed notice for a workspace dependency change, or empty when there is none. Reports the
+// install as already started, or as on its way: the daemon starts it within seconds, in the install lane, behind any
+// install already running; never as a request.
+const dependencyLine = (deps: { missing: number; started: string[]; deferred: boolean } | undefined): string => {
+    if (deps === undefined || deps.missing === 0) {
+        return ``;
+    }
+    // `missing` counts versions the turn bumped as well as names it added, so the sentence names both.
+    const what = `${deps.missing} ${deps.missing === 1 ? `dependency` : `dependencies`} it added or changed`;
+    return deps.deferred
+        ? ` ${what} ${deps.missing === 1 ? `is` : `are`} being installed in your tree: the install waits for any other install to finish, appears in Work terminals, and its outcome lands in Activity.`
+        : ` Installing ${what}; the project's checks run when that finishes, and the outcome lands in Activity.`;
+};
+
+// Said as an agent's own install starts: where it writes and what outlasts it. Names up to three projects, the workspace
+// root first; an install the gate could not place in a project says only where it writes. Coded like every sandbox
+// notice (sandbox-notice.ts `installing`), so the chat can say it in the reader's language.
+const INSTALL_NAMED = 3;
+export const installRow = (event: { readonly reach: "own-copy" | "main-tree"; readonly projects: readonly string[] }): TranscriptRow => {
+    const root = event.projects.includes(``);
+    const dirs = event.projects.filter((dir) => dir !== ``).map((dir) => `${dir}/`);
+    const shownDirs = dirs.slice(0, INSTALL_NAMED - (root ? 1 : 0));
+    const more = dirs.length - shownDirs.length;
+    const named = [...(root ? [`the workspace root`] : []), ...shownDirs].join(`, `);
+    const list = more > 0 ? `${named} and ${more} more` : named;
+    const where = list === `` ? `` : ` in ${list}`;
+    const ownCopy = event.reach === `own-copy`;
+    return {
+        role: "notice",
+        text: ownCopy
+            ? `Installing packages${where} into this conversation's own copy. The manifest and lockfile land with the work, and the review lists what it adds.`
+            : `Installing packages${where} in the main tree, one install at a time.`,
+        noticeCode: noticeCode({
+            code: "installing",
+            params: {
+                ownCopy,
+                root: root || undefined,
+                projects: shownDirs.length === 0 ? undefined : shownDirs.join(`, `),
+                more: more > 0 ? more : undefined,
+            },
+        }),
+    };
+};
+
+// One line reporting the daemon's rebase of this agent's branch onto the current workspace; `blocked` names repos it
+// couldn't rebase, where the turn ran from an older base.
+export const syncLine = (sync: { commits: number; blocked: readonly string[] }): string => {
+    const moved =
+        sync.commits > 0
+            ? `Your workspace moved on while this agent waited, its branch was rebased onto your latest ${sync.commits} commit${sync.commits === 1 ? `` : `s`}.`
+            : undefined;
+    const blocked =
+        sync.blocked.length > 0
+            ? `Couldn't rebase onto your workspace in ${sync.blocked.join(`, `)}: the turn is running from the older base, so its land may need a resolve.`
+            : undefined;
+    return [moved, blocked].filter((line) => line !== undefined).join(` `);
+};
+
+// Row for a spawned child's work gone into its parent's checkout, or held off it by a clash with the parent's edits.
+const intoParentRow = (event: Extract<AgentEvent, { kind: "landed" }>): TranscriptRow => {
+    if (event.landed) {
+        return {
+            role: "notice",
+            text: `Changes went into the parent agent's checkout, as its in-process subagents' edits do: they reach your workspace with its land.`,
+            noticeCode: noticeCode({ code: "intoParent" }),
+        };
+    }
+    const files = (event.conflicts ?? []).flatMap((conflict) => conflict.paths).length;
+    return {
+        role: "notice",
+        text: `${files} file(s) clash with the parent agent's own edits, so nothing was written into its checkout. The parent was told, and can bring the changes in to resolve.`,
+        noticeCode: noticeCode({ code: "intoParentClash", params: { files } }),
+    };
+};
+
+// Row for a finished turn: held on its branch, landed automatically, or conflicted. A landed turn that changed
+// dependencies appends dependencyLine, since the Changes diff can't show that.
+export const landedRow = (event: Extract<AgentEvent, { kind: "landed" }>): TranscriptRow => {
+    if (event.into !== undefined) {
+        return intoParentRow(event);
+    }
+    if (event.held === true) {
+        return { role: "notice", text: `Finished: the work is on this agent's branch, ready to land from its review.`, noticeCode: noticeCode({ code: "landHeld" }) };
+    }
+    if (!event.landed) {
+        // Per-file cause (your edits, a moved main line, a binary) is spelled out in the review, not named here.
+        const conflicts = event.conflicts ?? [];
+        const files = conflicts.flatMap((conflict) => conflict.paths).length;
+        const repos = conflicts.map((conflict) => conflict.repo).join(`, `);
+        return {
+            role: "notice",
+            text: `${files} file(s) couldn't land automatically in ${repos}. Open the agent's review to see what blocked them and land from there.`,
+            noticeCode: noticeCode({ code: "landConflict", params: { files, repos } }),
+        };
+    }
+    // noticeAction fires only here, right as the auto-behavior ran; an active install takes the slot instead.
+    const deps = event.deps === undefined || event.deps.missing === 0 ? undefined : event.deps;
+    return {
+        role: "notice",
+        text: `Changes landed in your workspace: review them in the Changes panel.${dependencyLine(event.deps)}`,
+        noticeAction: (event.deps?.started.length ?? 0) > 0 ? "depsInstall" : "landHold",
+        noticeCode: noticeCode({ code: "landed", params: deps === undefined ? undefined : { deps: deps.missing, queued: deps.deferred || undefined } }),
+    };
+};

package/src/text/transcript-fold.test.ts

@@ -1,5 +1,5 @@
 import { STATE_DIR } from "@intentic/constants";
-import type { AgentEvent } from "../events/agent-events.js";
+import { type AgentErrorCode, AgentErrorCodeSchema, type AgentEvent } from "../events/agent-events.js";
 import { type TranscriptPatch, type TranscriptRow, TranscriptRowSchema } from "../events/transcript.js";
 import { sandboxNoticeOf } from "../events/sandbox-notice.js";
 import { watchWakePrompt } from "../events/watch-wake.js";
@@ -306,7 +306,8 @@ describe("foldTurn", () => {
         expect(foldOf("hi", events)).toEqual([
             { role: "user", text: "hi", sentAt: SENT_AT },
             { role: "assistant", text: "I'll take a look" },
-            { role: "notice", text: refusal },
+            // A failure nobody named is still a failure: coded, the unclassified kind, never bare words.
+            { role: "notice", text: refusal, noticeCode: { code: "failed", params: { message: refusal } } },
         ]);
         const outage: AgentEvent[] = [
             {
@@ -349,11 +350,16 @@ describe("foldTurn", () => {
             noticeCode: { code: "renewalWithdrawn", params: { message: "Token refused.", error: "claude-token-refused" } },
         };
         // The live window hears the rewrite as a patch on the row it already drew, then the stop's own row.
+        const stop: TranscriptRow = {
+            role: "notice",
+            text: "Claude Code returned an error result: 401.",
+            noticeCode: { code: "failed", params: { message: "Claude Code returned an error result: 401." } },
+        };
         expect(patches).toEqual([
             { op: "replace", index: 1, row: withdrawn },
-            { op: "append", row: { role: "notice", text: "Claude Code returned an error result: 401." } },
+            { op: "append", row: stop },
         ]);
-        expect(fold.rows.slice(1)).toEqual([withdrawn, { role: "notice", text: "Claude Code returned an error result: 401." }]);
+        expect(fold.rows.slice(1)).toEqual([withdrawn, stop]);
         // A renewal armed again keeps its promise.
         const again = new TranscriptFold(openingOf("hi"));
         again.apply(refused);
@@ -1096,14 +1102,23 @@ describe(`the code beside a notice's words`, () => {
         });
     });
 
-    it(`codes a failure the sandbox names, and leaves a provider's own words to themselves`, () => {
+    it(`codes every failure, says who worded it, and names an unnamed one as unclassified`, () => {
         const busy = `This agent is already running a turn, wait for it to finish.`;
-        expect(lastOf([{ kind: `error`, code: `agent-busy`, message: busy }])).toEqual({
+        expect(lastOf([{ kind: `error`, code: `agent-busy`, message: busy, own: true }])).toEqual({
             role: `notice`,
             text: busy,
-            noticeCode: { code: `failed`, params: { message: busy, error: `agent-busy` } },
+            noticeCode: { code: `failed`, params: { message: busy, error: `agent-busy`, own: true } },
+        });
+        expect(lastOf([{ kind: `error`, message: `Overloaded.` }])).toEqual({
+            role: `notice`,
+            text: `Overloaded.`,
+            noticeCode: { code: `failed`, params: { message: `Overloaded.` } },
+        });
+        // A spent allowance is a failure like any other: it was the one code left as bare words (2026-10-20: 41 rows a week).
+        expect(lastOf([{ kind: `error`, code: `rate_limit`, message: `You've hit your usage limit.` }])?.noticeCode).toEqual({
+            code: `failed`,
+            params: { message: `You've hit your usage limit.`, error: `rate_limit` },
         });
-        expect(lastOf([{ kind: `error`, message: `Overloaded.` }])).toEqual({ role: `notice`, text: `Overloaded.` });
         expect(lastOf([{ kind: `error`, code: `claude-token-refused`, message: `Token refused.` }])).toEqual({
             role: `notice`,
             text: `Token refused. Reconnect the account to pick this conversation back up.`,
@@ -1127,10 +1142,24 @@ describe(`the code beside a notice's words`, () => {
         const rows = events.flatMap((turn) => foldTurn(openingOf(`go`), turn, `stopped`)).filter((row) => row.noticeCode !== undefined);
         expect(rows.filter((row) => sandboxNoticeOf(row) === undefined)).toEqual([]);
         expect(new Set(rows.map((row) => row.noticeCode?.code))).toEqual(
-            new Set([`synced`, `compacted`, `intoParent`, `intoParentClash`, `landHeld`, `outageWaiting`, `memoryHeld`, `kept`, `renewalWithdrawn`, `stopped`]),
+            new Set([`synced`, `compacted`, `intoParent`, `intoParentClash`, `landHeld`, `outageWaiting`, `memoryHeld`, `kept`, `renewalWithdrawn`, `failed`, `stopped`]),
         );
     });
 
+    // Every failure code the wire names, and none at all, folds to a failure row this build reads back: the class of row
+    // a reader had to recognise by its words cannot be written. A code added to the wire is held to it here.
+    it(`folds every failure, attended or not, ran or not, to a coded failure row`, () => {
+        const codes: readonly (AgentErrorCode | undefined)[] = [...AgentErrorCodeSchema.options, undefined];
+        const ran: AgentEvent = { kind: `tool_call`, id: `t1`, name: `Edit`, category: `edit`, status: `completed` };
+        for (const code of codes) {
+            const frame: AgentEvent = { kind: `error`, message: `Words.`, code };
+            for (const events of [[frame], [{ ...frame, unattended: true }], [{ ...frame, held: { ran: false } }], [ran, frame]]) {
+                const failure = foldTurn(openingOf(`go`), events, `settled`).at(-1);
+                expect({ code, coded: failure?.role === `notice` && sandboxNoticeOf(failure)?.code !== undefined }).toEqual({ code, coded: true });
+            }
+        }
+    });
+
     // A newer sandbox's code must not cost an older app the whole page: the row parses, and the reader draws its words.
     it(`reads a row whose code this build does not know, and one written before rows carried codes`, () => {
         const newer: TranscriptRow = { role: `notice`, text: `Something new happened.`, noticeCode: { code: `somethingNew`, params: { count: 2 } } };