@intentic/sandbox-contract 1.312.0 → 1.314.0

package/src/schemas/settings.test.ts

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

package/src/schemas/settings.ts

@@ -98,6 +98,9 @@ export const RuleSchema = z
         path: ["action"],
     });
 export type Rule = z.infer<typeof RuleSchema>;
+// A rule at a retired moment or with a retired built-in: read, so an older file parses, but never written again.
+export const isRetiredMomentRule = (rule: Pick<Rule, "moment" | "action">): boolean =>
+    rule.moment === "turn.ending" || (rule.action.kind === "builtin" && rule.action.name === "verify-ui-edits");
 // Kept out of the settings object on purpose: a firing is not an edit, and writing config on every push would make
 // every run a settings save.
 export const RuleFiringsSchema = z.record(z.string(), z.number());
@@ -189,6 +192,40 @@ export type SkillSwitch = z.infer<typeof SkillSwitchSchema>;
 // picks rather than failing whole. A setting removed or reshaped here gets its conversion in settings-history.ts, which
 // also names every retired setting, none of whose names may come back.
 
+// keep-warm's knobs, one object since each only means anything beside the others (cache-keepwarm.ts).
+export const KeepWarmSettingsSchema = z.object({
+    auto: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Keep a Claude conversation's prompt cache warm after each turn a person asked for. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation.",
+        ),
+    hours: z
+        .number()
+        .min(1)
+        .max(8)
+        .default(4)
+        .describe(
+            "How long an idle conversation is kept warm after its last turn, in hours, and what a press on one offers first. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
+        ),
+    minTokens: z
+        .number()
+        .int()
+        .min(0)
+        .default(100_000)
+        .describe("Only conversations at least this large, in tokens, are kept warm by `auto`: a small one is cheap to re-read anyway."),
+    reserve: z
+        .number()
+        .int()
+        .min(0)
+        .max(90)
+        .default(15)
+        .describe(
+            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
+        ),
+});
+export type KeepWarmSettings = z.infer<typeof KeepWarmSettingsSchema>;
+
 export const SandboxSettingsSchema = z.object({
     // The zone every WALL-CLOCK RULE in this sandbox is meant in — an automation's cron, and anything else that says
     // "at 09:00" instead of naming an instant. It is not a display preference: nothing formats through it, and an
@@ -392,36 +429,11 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "When a spent usage limit moves a turn to another account, carry the provider session (the model keeps everything, and re-reads all of it once on the other account) while the conversation's context is under this many tokens; at or above it, start a fresh session with the sandbox's measured brief instead. Zero always starts fresh.",
         ),
-    // Off by default: every refresh spends the account's own allowance on a conversation nobody is using yet.
-    keepWarm: z
-        .boolean()
-        .default(false)
-        .describe(
-            "Keep a Claude conversation's prompt cache warm after each turn a person asked for, so coming back to it hours later costs a cache read instead of re-sending everything. Each refresh re-reads the cached context at the cache price and adds nothing to the conversation. Any one conversation can be kept warm or let cool by hand either way.",
-        ),
-    keepWarmHours: z
-        .number()
-        .min(1)
-        .max(8)
-        .default(4)
-        .describe(
-            "How long an idle conversation is kept warm after its last turn, in hours. Shortened where refreshing would cost more than the cold resume it saves, and at midnight where the agent runs, when the date in its prompt changes.",
-        ),
-    keepWarmMinTokens: z
-        .number()
-        .int()
-        .min(0)
-        .default(100_000)
-        .describe("Only conversations at least this large, in tokens, are kept warm by themselves: a small one is cheap to re-read anyway."),
-    keepWarmReserve: z
-        .number()
-        .int()
-        .min(0)
-        .max(90)
-        .default(15)
-        .describe(
-            "How much of an account's usage limit, in percent, keeping conversations warm must leave untouched for real work. Refreshing stops once any limit that account's model spends is fuller than that.",
-        ),
+    // Off by default: every refresh spends the account's own allowance on a conversation nobody is using yet. Before
+    // 2026-09-26 these were four top-level settings (settings-history.ts folds them).
+    keepWarm: KeepWarmSettingsSchema.prefault({}).describe(
+        "Keeping an idle conversation's prompt cache warm, so coming back to it hours later costs a cache read instead of re-sending everything. Any one conversation can be kept warm or let cool by hand whatever `auto` says.",
+    ),
     // Worth it since the container is recreated on every update or environment approval — otherwise approving a
     // Dockerfile change costs the run that asked for it.
     // What happens to breakage found after the work that caused it has left the turn. A land that turns the main tree's own
@@ -436,7 +448,7 @@ export const SandboxSettingsSchema = z.object({
             "Whether breakage found after the work left its turn is repaired without asking. A land that turns the main tree's check red is repaired once the work queued behind it has been checked too: by the conversation that landed it while it still has the work in mind, otherwise by a fresh conversation handed the failures and the suspects' changes. Main's CI staying red on the same failure gets a fix agent once pushes go quiet, and a failure on the CI fleet itself is re-run once instead. Off, all of it is only reported.",
         ),
     // Where heavy work runs: a runner (the same image, on one of the owner's machines) instead of this sandbox. Keyed by
-    // the heavy-command rule an agent's command matched (platform/resources/heavy-commands.ts), and one entry for the
+    // the heavy-command rule an agent's command matched (system/resources/heavy-commands.ts), and one entry for the
     // check after landing, each naming a runner id. A runner that is offline, outdated or full hands the work back here,
     // which the command's output says. Never pushed to a runner itself (portability/definition.ts), which must not pass
     // work on again.
@@ -517,6 +529,12 @@ export const SandboxSettingsSchema = z.object({
         .describe("How many levels deep the delegation may go, since a subagent can start subagents of its own."),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
+// What a save takes: the settings as read, less what is only read. `turn.ending` (and its `verify-ui-edits` built-in) is
+// retired; a file written before still parses (and its conversion drops such rules), but no save may stand a new one.
+export const SandboxSettingsWriteSchema = SandboxSettingsSchema.refine((settings) => !settings.rules.some(isRetiredMomentRule), {
+    message: "turn.ending is retired: nothing runs when a turn ends any more, so a rule cannot stand there",
+    path: ["rules"],
+});
 
 // A browser telling the sandbox which clock IT is on. An offer, not an instruction: see `adoptTimezone`.
 export const TimezoneOfferSchema = z.object({

package/src/schemas/speaker.ts

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

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

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

package/src/schemas/state-plan.ts

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

package/src/schemas/system.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { StatePlanSchema } from "./state-plan.js";
 // version is this build's baked-in version; latest/updateAvailable come from comparing it to the published stable
 // release.
 // Whether a runtime can serve a turn, probed off the turn path. "unknown" reads as available-but-unverified, never as
@@ -29,19 +30,10 @@ export const StagedUpdateSchema = z.object({
     at: z.number().describe("When the download finished, in milliseconds, which answers whether this is still the update being offered."),
     // The staged build's state pre-flight (the daemon's state-plan.ts, run by `ic sandbox prepare` over read-only mounts
     // of this sandbox's volumes): what its first boot converts, before anyone accepts the update.
-    plan: z
-        .object({
-            ok: z.boolean().describe("False when a conversion would fail on this sandbox's files, which refuses the update before anything is touched."),
-            downgrade: z.boolean().optional().describe("The staged build is older than the one that converted these files; it opens them read-only."),
-            steps: z
-                .array(z.object({ document: z.string(), change: z.string() }))
-                .optional()
-                .describe("Each stored file the first boot converts, and how."),
-            failures: z
-                .array(z.object({ document: z.string(), detail: z.string() }))
-                .optional()
-                .describe("Each conversion that would fail, and why."),
-        })
+    // Embedded verbatim by the ic that staged it (StatePlanSchema); a marker an older ic wrote held only `ok` with
+    // `downgrade` and `steps`, or `failures`, so everything but `ok` stays optional here.
+    plan: StatePlanSchema.partial()
+        .extend({ ok: StatePlanSchema.shape.ok })
         .optional()
         .describe("What the downloaded build's first boot would convert in this sandbox's stored files. Absent when no plan could be had, which says nothing either way."),
 });
@@ -92,8 +84,9 @@ export const InfoSchema = z.object({
     ),
 });
 export type Info = z.infer<typeof InfoSchema>;
-// What the daemon could not read in its own `.intentic/` state files. Reported per file, only for files listed in
-// REPORTED_MANIFEST_PATHS (workspace-state.ts). `kind`:
+// What the daemon could not read in its own `.intentic/` state files, and in the files on its volume that
+// REPORTED_VOLUME_FILES names. Reported per file, only for files listed in REPORTED_MANIFEST_PATHS or
+// REPORTED_VOLUME_FILES (workspace-state.ts). `kind`:
 // unreadable: whole file ignored, everything in it at default.
 // unknownKey: only that key ignored; `suggestion` may name what it should be.
 // invalidEntry: one list entry skipped, rest of the file stands.
@@ -103,6 +96,13 @@ export const ManifestProblemSchema = z.object({
         .describe(
             "What to do about it. Unreadable means the whole file is being ignored and everything in it is at its default. An unknown key means only that key is ignored. An invalid entry means one item of a list was skipped and the rest is fine.",
         ),
+    // Why, as a word a reader matches on; `detail` is prose for a person and never parsed. Absent from an older daemon.
+    reason: z
+        .enum(["io", "not-json", "conversion-failed", "rejected"])
+        .optional()
+        .describe(
+            "Why it could not be read: the file could not be opened (io), it is not JSON, a conversion to this version's shape failed, or its contents are not what this version expects (rejected). A rejected file after a newer version ran is usually that version's, not a broken one.",
+        ),
     detail: z.string().describe("What exactly was wrong, as one sentence and nothing else. Never the remedy: that is `fix`."),
     suggestion: z.string().optional().describe("The name it was probably meant to be, when one is close enough to guess honestly."),
     // Set only when the fix isn't "open the file and correct it", e.g. a version skew where editing would be wrong.
@@ -115,7 +115,11 @@ export type ManifestProblem = z.infer<typeof ManifestProblemSchema>;
 // Workspace-relative path and everything currently wrong with that file; a clean file is absent from the list, not
 // present and empty.
 export const ManifestProblemReportSchema = z.object({
-    path: z.string().describe("The file, as a workspace path. The file is the unit somebody fixes, which is why problems are grouped by it."),
+    path: z
+        .string()
+        .describe(
+            "The file, as a workspace path, or as its absolute path on the daemon's own history volume for one kept there (the conversation registry). The file is the unit somebody fixes, which is why problems are grouped by it.",
+        ),
     problems: z
         .array(ManifestProblemSchema)
         .describe("Everything currently wrong with it. A file with nothing wrong is absent rather than present and empty."),

package/src/schemas/workspace/mainline.test.ts

@@ -0,0 +1,28 @@
+import { pushFixConversationId } from "../../ids/conversation-ids.js";
+import { pushFixBase, pushRedOf, type Red, RedSchema } from "./mainline.js";
+
+// What a push left is a Red like any other (source `push`, scope the project), and the hand-over's id is named by when
+// that red began, so the editor and the daemon find the same attempt whichever of them asks.
+
+const red = (over: Partial<Red>): Red => RedSchema.parse({ source: `push`, scope: `app`, since: 100, ...over });
+
+describe(`a project's push red`, () => {
+    test(`is the push red of that project, never a land check's red of the same folder or another project's`, () => {
+        const land = red({ source: `land` });
+        const other = red({ scope: `web` });
+        const mine = red({});
+        expect(pushRedOf([land, other, mine], `app`)).toBe(mine);
+        expect(pushRedOf([land, other], `app`)).toBeUndefined();
+        expect(pushRedOf(undefined, `app`)).toBeUndefined();
+    });
+
+    test(`names its hand-over by when it began, with the workspace root spelled as the workspace`, () => {
+        expect(pushFixBase(red({}))).toBe(pushFixConversationId(`app`, `red:100`));
+        expect(pushFixBase(red({ scope: `` }))).toBe(pushFixConversationId(`workspace`, `red:100`));
+        expect(pushFixBase(undefined)).toBeUndefined();
+    });
+
+    test(`that began later is a fresh attempt`, () => {
+        expect(pushFixBase(red({ since: 200 }))).toBe(pushFixConversationId(`app`, `red:200`));
+    });
+});