@intentic/sandbox-contract 1.316.0 → 1.318.0

package/src/events/agent-words.ts

@@ -1,5 +1,6 @@
 import type { SubagentVerification } from "../schemas/terminal.js";
 import type { TranscriptAgentWords, TranscriptRow } from "./transcript.js";
+import { needWakeRow } from "./need-wake.js";
 import { watchWakeRow } from "./watch-wake.js";
 
 // Composer and parser of another agent's prompt (a peer's message, a child's report) are one piece of knowledge.
@@ -43,6 +44,9 @@ export interface ChildReportFields {
     readonly report: string;
     // Undefined when nothing of the child's work was seen, which is not a verdict.
     readonly verification: SubagentVerification | undefined;
+    // Where its work went, in the daemon's words: into the parent's own checkout, or held off it by a clash. Undefined
+    // for a child whose work lands as any conversation's does.
+    readonly landing?: string | undefined;
 }
 
 // The wait tool's `verification` field, in words.
@@ -72,7 +76,7 @@ export const childReportPrompt = (fields: ChildReportFields): string => {
         "",
         fields.report.trim() === "" ? "(It ended without a closing report.)" : fields.report.trim(),
         "",
-        "Its changes are in its own worktree and land the way any agent's do. Its account of its own work is a claim, not " +
+        `${fields.landing ?? "Its changes are in its own worktree and land the way any agent's do."} Its account of its own work is a claim, not ` +
             "a result: check what matters before you build on it, and follow up with the subagents tools as you would mid-turn.",
     ].join("\n");
 };
@@ -124,4 +128,4 @@ export const agentWordsRow = (prompt: string): TranscriptRow | undefined => {
 };
 
 /** The row for a prompt nobody at the composer typed; every transcript reader asks this one function. */
-export const unspokenPromptRow = (prompt: string): TranscriptRow | undefined => watchWakeRow(prompt) ?? agentWordsRow(prompt);
+export const unspokenPromptRow = (prompt: string): TranscriptRow | undefined => watchWakeRow(prompt) ?? needWakeRow(prompt) ?? agentWordsRow(prompt);

package/src/events/land-breakage.ts

@@ -1,8 +1,7 @@
-// The follow-ups the daemon USED to send when the check it ran after every land went red: back to the conversation
+// The follow-ups the daemon USED to send when the check it ran after every land failed: back to the conversation
 // that landed the work, or to a fresh conversation started on it. Nothing sends either any more: nothing checks work
-// after it lands, CI checks what the owner pushes (schemas/workspace/push-checks.ts). They stay on the wire because
-// records already hold them, and the chat has to go on recognising them: a prompt nobody typed must not reach a reader
-// as their own words.
+// after it lands, CI checks what the owner pushes (schemas/ci.ts). They stay on the wire because records already hold
+// them, and the chat has to go on recognising them: a prompt nobody typed must not reach a reader as their own words.
 
 // Anchored on by the chat, so it must stay unique and stable across releases.
 export const LAND_BREAKAGE_OPENING =

package/src/events/need-wake.test.ts

@@ -0,0 +1,55 @@
+import { unspokenPromptRow } from "./agent-words.js";
+import { needRowText, needWakeOf, needWakePrompt, needWakeRow, type NeedWakeFields, type NeedWakeOutcome } from "./need-wake.js";
+
+const fields = (over: Partial<NeedWakeFields> = {}): NeedWakeFields => ({
+    outcome: "met",
+    id: "need-7k2q",
+    title: "Connect GitHub",
+    why: "to open the pull request for the fix",
+    result: 'GitHub is connected as "github".',
+    use: ["In this turn, prefix a command with GH_TOKEN={{secret:github/token}}."],
+    ...over,
+});
+
+const OUTCOMES: NeedWakeOutcome[] = ["met", "declined"];
+
+describe("need wake", () => {
+    // The composer and the parser are the same piece of knowledge; this holds them together when either is reworded.
+    it.each(OUTCOMES)("round-trips a %s wake back to its fields", (outcome) => {
+        const prompt = needWakePrompt(fields({ outcome }));
+        expect(needWakeOf(prompt)).toEqual({ outcome, title: "Connect GitHub", id: "need-7k2q", sent: prompt });
+    });
+
+    it("tells a met need to carry on and a declined one not to wait", () => {
+        expect(needWakePrompt(fields()).split("\n").at(-1)).toBe("Continue the task that needed it.");
+        expect(needWakePrompt(fields({ outcome: "declined", use: [] }))).not.toContain("Continue the task");
+    });
+
+    it("leaves the agent's reason out when it gave none, rather than printing an empty label", () => {
+        expect(needWakePrompt(fields({ why: undefined }))).not.toContain("You asked because:");
+        expect(needWakePrompt(fields())).toContain("You asked because: to open the pull request for the fix");
+    });
+
+    it("is not a wake once its labelled lines are gone", () => {
+        const prompt = needWakePrompt(fields());
+        expect(needWakeOf(prompt.replace("Need id: need-7k2q\n", ""))).toBeUndefined();
+        expect(needWakeOf(prompt.replace("Need: Connect GitHub\n", ""))).toBeUndefined();
+        expect(needWakeOf("please connect github")).toBeUndefined();
+    });
+
+    it("becomes a notice row that says what happened, and every transcript reader finds it", () => {
+        const prompt = needWakePrompt(fields());
+        const row = needWakeRow(prompt);
+        expect(row).toEqual({
+            role: "notice",
+            text: "Connect GitHub: done, and the agent carries on.",
+            needWake: { outcome: "met", title: "Connect GitHub", id: "need-7k2q", sent: prompt },
+        });
+        expect(unspokenPromptRow(prompt)).toEqual(row);
+        expect(needWakeRow(needWakePrompt(fields({ outcome: "declined" })))?.text).toBe("Connect GitHub: declined, and the agent was told.");
+    });
+
+    it("words a raised need's row for a reader that draws no card", () => {
+        expect(needRowText({ title: "The OPENAI_API_KEY secret" })).toBe("Needs a person: The OPENAI_API_KEY secret");
+    });
+});

package/src/events/need-wake.ts

@@ -0,0 +1,71 @@
+import type { TranscriptNeedWake, TranscriptRow } from "./transcript.js";
+
+// What a need says when its answer reaches a conversation, and how that reads to a person. Delivered as an ordinary
+// turn prompt (a steer into a live turn, or a turn of its own), so composing it and recognising it stay one piece of
+// knowledge, exactly as a condition watch's wake does (watch-wake.ts): the daemon's record, a steered live turn and a
+// provider's session store all turn this prompt back into the same row.
+
+export type NeedWakeOutcome = TranscriptNeedWake["outcome"];
+
+// Per-outcome opening sentence, which is also what the parser anchors on: keep each unique and stable across releases,
+// or a reworded opening un-recognises wakes already in a record and they read as the user's own words.
+const OPENINGS: Record<NeedWakeOutcome, string> = {
+    met: "Need met: a person gave you what you asked for.",
+    declined: "Need declined: a person said no to what you asked for. Carry on without it, and say plainly what it would have enabled.",
+};
+
+// Labels the prompt writes and the parser reads back. `Need` and `Need id` are load-bearing on both sides.
+const NEED = "Need: ";
+const NEED_ID = "Need id: ";
+const ASKED = "You asked because: ";
+
+export interface NeedWakeFields {
+    readonly outcome: NeedWakeOutcome;
+    readonly id: string;
+    readonly title: string;
+    readonly why: string | undefined;
+    // The daemon's sentence on how it ended ("Connected as "github".", "Stored under OPENAI_API_KEY.").
+    readonly result: string;
+    // What the agent can do with it now, and what arrives on its next turn; empty for a decline.
+    readonly use: readonly string[];
+}
+
+export const needWakePrompt = (fields: NeedWakeFields): string =>
+    [
+        OPENINGS[fields.outcome],
+        `${NEED}${fields.title}`,
+        `${NEED_ID}${fields.id}`,
+        ...(fields.why === undefined || fields.why === "" ? [] : [`${ASKED}${fields.why}`]),
+        fields.result,
+        ...fields.use,
+        ...(fields.outcome === "met" ? ["Continue the task that needed it."] : []),
+    ].join("\n");
+
+const headline = (outcome: NeedWakeOutcome, title: string): string =>
+    outcome === "met" ? `${title}: done, and the agent carries on.` : `${title}: declined, and the agent was told.`;
+
+const valueOn = (lines: readonly string[], label: string): string | undefined => lines.find((line) => line.startsWith(label))?.slice(label.length);
+
+// The words a raised need's row carries for a reader that draws no card (search, an export, an older client); the card
+// itself is drawn from the need.
+export const needRowText = (need: { readonly title: string }): string => `Needs a person: ${need.title}`;
+
+// Which need wake a stored prompt is, if any; undefined for every prompt that isn't one, so any reader can ask without
+// checking first. One that opens as a wake but lost its labelled lines is not one.
+export const needWakeOf = (prompt: string): TranscriptNeedWake | undefined => {
+    const outcome = (Object.keys(OPENINGS) as NeedWakeOutcome[]).find((key) => prompt.startsWith(OPENINGS[key]));
+    if (outcome === undefined) {
+        return undefined;
+    }
+    const lines = prompt.split("\n");
+    const title = valueOn(lines, NEED);
+    const id = valueOn(lines, NEED_ID);
+    return title === undefined || id === undefined ? undefined : { outcome, title, id, sent: prompt };
+};
+
+// The row a wake becomes: a notice, since a need being answered happened to the conversation rather than being said by
+// either side. Undefined when the prompt is not a need wake at all.
+export const needWakeRow = (prompt: string): TranscriptRow | undefined => {
+    const wake = needWakeOf(prompt);
+    return wake === undefined ? undefined : { role: "notice", text: headline(wake.outcome, wake.title), needWake: wake };
+};

package/src/events/resume.test.ts

@@ -1,4 +1,4 @@
-import { RESUME_NOTES, resumeDisclosure, withResumeNote, withoutResumeNote } from "./resume.js";
+import { RESUME_NOTES, resumeDisclosure, resumeNoticeRow, withResumeNote, withoutResumeNote } from "./resume.js";
 
 // Wrapping then unwrapping a resume note must return the exact original prompt; a mismatch leaks machine narration into
 // the user's own words on screen.
@@ -46,7 +46,7 @@ test("the spent-allowance notes do not disclose as each other", () => {
 test("a turn the door turned away discloses as its own notice, apart from the allowance's refusal", () => {
     const door = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.door));
     const refused = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.refused));
-    expect(door).toEqual({ kind: "notice", text: expect.stringContaining("turned away") });
+    expect(door).toEqual({ kind: "notice", text: expect.stringContaining("turned away"), reason: "door" });
     expect(door).not.toEqual(refused);
 });
 
@@ -60,5 +60,16 @@ test("a re-run after the window overflowed discloses as its own notice", () => {
     expect(resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.overflow))).toEqual({
         kind: "notice",
         text: "Sent again in a fresh session after the last one outgrew the model's context window.",
+        reason: "overflow",
+    });
+});
+
+// The row keeps the English line, and names the re-run so an app can say it in its reader's language.
+test("a re-run's notice row names its reason beside its words", () => {
+    const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES.restart));
+    expect(disclosure?.kind === "notice" ? resumeNoticeRow(disclosure) : undefined).toEqual({
+        role: "notice",
+        text: "The sandbox came back, this turn picked up where it left off.",
+        noticeCode: { code: "resumed", params: { reason: "restart" } },
     });
 });

package/src/events/resume.ts

@@ -1,4 +1,5 @@
-import type { TurnNote } from "./transcript.js";
+import { noticeCode, type ResumeNoticeReason } from "./sandbox-notice.js";
+import type { TranscriptRow, TurnNote } from "./transcript.js";
 
 // What a resumed turn's prompt says happened; lives on the wire since the client must recognise it too.
 
@@ -46,23 +47,35 @@ export type ResumeReason = keyof typeof RESUME_NOTES;
 
 // How a resumed turn's interruption reads to a person: `notice` for the whole-turn re-runs, a muted line with the
 // repeat dropped; `note` for the answered case, the user's real answer disclosed normally.
-export type ResumeDisclosure = { readonly kind: "notice"; readonly text: string } | { readonly kind: "note"; readonly note: TurnNote };
+// A notice names its reason too, so the row it becomes can say it in the reader's language (sandbox-notice.ts).
+export type ResumeDisclosure =
+    | { readonly kind: "notice"; readonly text: string; readonly reason: ResumeNoticeReason }
+    | { readonly kind: "note"; readonly note: TurnNote };
+
+const notice = (reason: ResumeNoticeReason, text: string): ResumeDisclosure => ({ kind: "notice", text, reason });
 
 const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
-    auth: { kind: "notice", text: "Claude sign-in renewed, this turn picked up where it left off." },
-    outage: { kind: "notice", text: "The model provider came back, this turn picked up where it left off." },
-    restart: { kind: "notice", text: "The sandbox came back, this turn picked up where it left off." },
-    stopped: { kind: "notice", text: "Sent again after the turn stopped short, picking up where it left off." },
+    auth: notice("auth", "Claude sign-in renewed, this turn picked up where it left off."),
+    outage: notice("outage", "The model provider came back, this turn picked up where it left off."),
+    restart: notice("restart", "The sandbox came back, this turn picked up where it left off."),
+    stopped: notice("stopped", "Sent again after the turn stopped short, picking up where it left off."),
     // None of these four auto-resumed, a person pressed Continue; `switched`/`carried` name the differing account.
-    limit: { kind: "notice", text: "Sent again after the allowance ran out mid-turn, picking up where it left off." },
-    switched: { kind: "notice", text: "Sent again on the switched account after the allowance ran out mid-turn, in a fresh session." },
-    carried: { kind: "notice", text: "Sent again on the switched account after the allowance ran out mid-turn, carrying the session with it." },
-    refused: { kind: "notice", text: "Sent again after the allowance refused it: nothing had run." },
-    door: { kind: "notice", text: "Sent again: the first attempt was turned away before anything ran." },
-    overflow: { kind: "notice", text: "Sent again in a fresh session after the last one outgrew the model's context window." },
+    limit: notice("limit", "Sent again after the allowance ran out mid-turn, picking up where it left off."),
+    switched: notice("switched", "Sent again on the switched account after the allowance ran out mid-turn, in a fresh session."),
+    carried: notice("carried", "Sent again on the switched account after the allowance ran out mid-turn, carrying the session with it."),
+    refused: notice("refused", "Sent again after the allowance refused it: nothing had run."),
+    door: notice("door", "Sent again: the first attempt was turned away before anything ran."),
+    overflow: notice("overflow", "Sent again in a fresh session after the last one outgrew the model's context window."),
     answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
 };
 
+/** The row a whole-turn re-run stands in for its repeated words with, wherever a reader restores one. */
+export const resumeNoticeRow = (resume: Extract<ResumeDisclosure, { kind: "notice" }>): TranscriptRow => ({
+    role: "notice",
+    text: resume.text,
+    noticeCode: noticeCode({ code: "resumed", params: { reason: resume.reason } }),
+});
+
 // What a stored prompt's resume note should be shown as; undefined when the prompt isn't a resume, so any reader can
 // ask without checking first.
 export const resumeDisclosure = (prompt: string): ResumeDisclosure | undefined => {

package/src/events/sandbox-notice.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+// The sandbox's own notice rows (a land, a hold, a renewal, a stop), as a code and the facts they were worded from. The
+// row's `text` stays the English sentence, which older apps, stored transcripts and agents reading their own history
+// go on reading; `noticeCode` beside it is what lets an app say the same thing in the reader's language and words.
+
+// On the wire a code is any string and its facts a flat record: a transcript page carrying a code newer than its reader
+// still parses, and that reader draws `text`. The codes this build writes, with their facts typed, are
+// SandboxNoticeSchema below.
+export const NoticeCodeSchema = z.object({
+    code: z.string().describe("Which of the sandbox's notices this row is, by name. A reader that does not know the name shows the row's text."),
+    params: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe("The facts the notice was worded from, by name: counts, names, and the provider's own sentence where the notice quotes one."),
+});
+export type NoticeCode = z.infer<typeof NoticeCodeSchema>;
+
+const count = z.number().int().nonnegative();
+
+// A failure's own sentence, which the notice's clause follows: the provider's words, or the sandbox's under `error`, its
+// failure code, for a reader that words a failure it knows itself.
+const failure = {
+    message: z.string(),
+    error: z.string().optional(),
+};
+
+// The re-runs a resumed turn's row can name (events/resume.ts); a reason a reader does not know draws the row's text.
+const ResumeNoticeReasonSchema = z.enum(["auth", "outage", "restart", "stopped", "limit", "switched", "carried", "refused", "door", "overflow"]);
+export type ResumeNoticeReason = z.infer<typeof ResumeNoticeReasonSchema>;
+
+// Every code this build writes, one per sentence shape, each with the facts that shape needs.
+export const SandboxNoticeSchema = z.discriminatedUnion("code", [
+    z.object({ code: z.literal("compacted") }),
+    z.object({ code: z.literal("stopped") }),
+    // The branch was rebased onto `commits` new commits, and/or could not be in the repos named in `blocked`.
+    z.object({ code: z.literal("synced"), params: z.object({ commits: count, blocked: z.string().optional() }) }),
+    z.object({ code: z.literal("intoParent") }),
+    z.object({ code: z.literal("intoParentClash"), params: z.object({ files: count }) }),
+    z.object({ code: z.literal("landHeld") }),
+    z.object({ code: z.literal("landConflict"), params: z.object({ files: count, repos: z.string() }) }),
+    // `deps` dependencies the turn added or changed, installing now, or `queued` behind any other install.
+    z.object({ code: z.literal("landed"), params: z.object({ deps: count.optional(), queued: z.boolean().optional() }).optional() }),
+    z.object({ code: z.literal("retrying"), params: z.object({ ...failure, attempt: count, of: count }) }),
+    z.object({ code: z.literal("retried"), params: z.object({ ...failure, made: count, of: count }) }),
+    z.object({ code: z.literal("outageWaiting"), params: z.object(failure) }),
+    z.object({ code: z.literal("renewing"), params: z.object(failure) }),
+    z.object({ code: z.literal("renewalWithdrawn"), params: z.object(failure) }),
+    z.object({ code: z.literal("reconnect"), params: z.object(failure) }),
+    z.object({ code: z.literal("undelivered"), params: z.object({ ...failure, unattended: z.boolean().optional() }) }),
+    // A turn the sandbox kept whole, its message above; `memory` when a memory hold kept it.
+    z.object({ code: z.literal("kept"), params: z.object({ ...failure, memory: z.boolean().optional() }) }),
+    z.object({ code: z.literal("memoryHeld"), params: z.object(failure) }),
+    // A failure the sandbox names by code and adds nothing to.
+    z.object({ code: z.literal("failed"), params: z.object(failure) }),
+    z.object({ code: z.literal("questionDismissed") }),
+    z.object({ code: z.literal("planApproved") }),
+    z.object({ code: z.literal("keptPlanning") }),
+    // `note` is the agent's own words; `every` the interval, already worded ("5m").
+    z.object({ code: z.literal("watching"), params: z.object({ note: z.string(), every: z.string() }) }),
+    z.object({ code: z.literal("restartInterrupted") }),
+    // A turn that picked up a conversation the sandbox kept warm: `tokens` read from the cache ("305k"), or for
+    // keptCold sent again, after `span` ("2h 5m") and `refreshes` refreshes.
+    z.object({ code: z.literal("keptWarm"), params: z.object({ tokens: z.string(), span: z.string(), refreshes: count }) }),
+    z.object({ code: z.literal("keptCold"), params: z.object({ tokens: z.string(), span: z.string(), refreshes: count }) }),
+    // A turn sent thin for a small window ("16k"): what was left out, and whether the base instructions were swapped too.
+    z.object({ code: z.literal("contextTrim"), params: z.object({ window: z.string(), omitted: z.string().optional(), base: z.boolean() }) }),
+    z.object({ code: z.literal("resumed"), params: z.object({ reason: ResumeNoticeReasonSchema }) }),
+    // An agent's own dependency install starting: into its conversation's own copy (`ownCopy`) or the main tree; the
+    // workspace root (`root`) and up to three project folders named (`projects`, each with its slash, already joined),
+    // and how many `more` were not named.
+    z.object({
+        code: z.literal("installing"),
+        params: z.object({ ownCopy: z.boolean(), root: z.boolean().optional(), projects: z.string().optional(), more: count.optional() }),
+    }),
+]);
+export type SandboxNotice = z.infer<typeof SandboxNoticeSchema>;
+
+/** The wire form of one of this build's notices, facts nobody gave left off rather than sent as nothing. */
+export const noticeCode = (notice: SandboxNotice): NoticeCode => {
+    if (!("params" in notice) || notice.params === undefined) {
+        return { code: notice.code };
+    }
+    const params = Object.fromEntries(
+        Object.entries(notice.params).filter((entry): entry is [string, string | number | boolean] => entry[1] !== undefined),
+    );
+    return Object.keys(params).length === 0 ? { code: notice.code } : { code: notice.code, params };
+};
+
+/** One of this build's notices, read off a row; undefined for a row without one, or with a code or facts this build does not know. */
+export const sandboxNoticeOf = (row: { readonly noticeCode?: NoticeCode | undefined }): SandboxNotice | undefined =>
+    row.noticeCode === undefined ? undefined : SandboxNoticeSchema.safeParse(row.noticeCode).data;

package/src/events/system-events.ts

@@ -53,6 +53,13 @@ export const HelloSchema = z.object({
     shapes: z.record(z.string(), z.string()).optional(),
     build: z.string().optional(),
     boot: BootProgressSchema.optional(),
+    // A project sandbox's folder, workspace-relative (`my-app` for /work/my-app): the owner's own folder, synced live
+    // with their computer, which the browser scopes the workspace to on arrival. Absent on every other sandbox.
+    projectDir: z.string().optional(),
+    // What answers: a sandbox's daemon, or the desktop app's sidecar serving a folder on the user's own computer
+    // (_devices/local-files), whose `routes` are the few a folder has rather than a daemon's missing ones. Absent reads
+    // as a sandbox, which every daemon before this field was.
+    surface: z.enum(["sandbox", "folder"]).optional(),
 });
 export type Hello = z.infer<typeof HelloSchema>;
 

package/src/events/transcript.ts

@@ -3,7 +3,9 @@ import { AgentHarnessSchema, AgentProviderSchema } from "../schemas/agent.js";
 import { ShareDetailSchema } from "../schemas/share.js";
 import { TurnErrandSchema, TurnSpeakerSchema } from "../schemas/speaker.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
+import { NeedSchema } from "../schemas/needs.js";
 import { RetryLadderSchema } from "../schemas/turn-break.js";
+import { NoticeCodeSchema } from "./sandbox-notice.js";
 import type { ToolCallContent, ToolCallLocation, ToolCallStatus, ToolKind} from "./requests.js";
 import { browserHelpRequest, capabilityOfferRequest, CapabilityOutcomeSchema, credentialOfferRequest, CredentialReceiptSchema, paymentOfferRequest, PaymentReceiptSchema, PermissionAskSchema, permissionRequest, planRequest, questionRequest, terminalHelpRequest, TodoItemSchema, ToolCallContentSchema, ToolCallLocationSchema, ToolCallStatusSchema, ToolKindSchema } from "./requests.js";
 
@@ -104,7 +106,7 @@ export const TranscriptSubagentSchema = z.object({
         .string()
         .optional()
         .describe(
-            "Its own id, where that is not the card's: a spawned subagent is named by its own conversation, which is what the roster, `wait` and its page call it. Absent, the card's id is its id, as it is for one the runtime started in-process.",
+            "Its own id, where that is not the card's: a spawned subagent is named by its own conversation, which is what the roster, `wait` and its own chat call it. Absent, the card's id is its id, as it is for one the runtime started in-process.",
         ),
     kind: SubagentKindSchema,
     agentType: z.string().optional(),
@@ -155,6 +157,15 @@ export const TranscriptWatchWakeSchema = z.object({
 });
 export type TranscriptWatchWake = z.infer<typeof TranscriptWatchWakeSchema>;
 
+// A need's answer that reached this conversation as a prompt (need-wake.ts); the row keeps the prompt and names the need.
+export const TranscriptNeedWakeSchema = z.object({
+    outcome: z.enum(["met", "declined"]).describe("How the need ended: a person gave it, or said no."),
+    title: z.string().describe("The need, as its card leads with it."),
+    id: z.string().describe("The need's handle, which its live card is keyed by."),
+    sent: z.string().describe("The whole prompt the model received, disclosed under the row."),
+});
+export type TranscriptNeedWake = z.infer<typeof TranscriptNeedWakeSchema>;
+
 // Another agent's words that reached this conversation as a prompt; the row keeps the prompt and names the sender.
 export const TranscriptAgentWordsSchema = z.object({
     kind: z.enum(["peer", "child"]).describe("Who sent it: another conversation in the workspace, or a subagent this one started."),
@@ -290,6 +301,11 @@ export const TranscriptRowSchema = z.object({
         .string()
         .optional()
         .describe("Which instance of the wait this notice names, for a kind that can have several running at once."),
+    // The sandbox's own notice by name, beside its English `text` (sandbox-notice.ts); absent on every other row, and
+    // on the notices written before rows carried it, which a reader draws from `text` as it always did.
+    noticeCode: NoticeCodeSchema.optional().describe(
+        "Which of the sandbox's own notices this row is, and the facts it was worded from, so a reader can say it in the reader's own language. The text stays the English sentence.",
+    ),
     // At most one card per row; a card closes its bubble. One field per kind, so a reader reaches it by name.
     plan: TranscriptPlanSchema.optional().describe("The plan this row asked approval for, and the answer."),
     question: TranscriptQuestionSchema.optional().describe("The questions this row asked, and the picks that answered them."),
@@ -299,6 +315,12 @@ export const TranscriptRowSchema = z.object({
     capabilityOffer: TranscriptCapabilityOfferSchema.optional().describe("The capability setup this row asked for, the decision, and the outcome."),
     paymentOffer: TranscriptPaymentOfferSchema.optional().describe("The payment this row asked for, the decision, and the receipt."),
     watchWake: TranscriptWatchWakeSchema.optional().describe("The condition watch that woke this conversation, and the prompt it was woken with."),
+    // A need is not a parked card: it holds no turn open, outlives the one that raised it, and its live state is the
+    // needs store's, keyed by `need.id`. What rides here is the need as it was raised, for a reader with no store.
+    need: NeedSchema.optional().describe(
+        "Something the agent asked a person for, as it was when raised. Its live state (answered, met) is read by its id, since it outlives the turn.",
+    ),
+    needWake: TranscriptNeedWakeSchema.optional().describe("The answered need that reached this conversation, and the prompt it came as."),
     agentWords: TranscriptAgentWordsSchema.optional().describe("Another agent's words that reached this conversation, whose they are, and the prompt they came as."),
     backgroundJob: TranscriptBackgroundJobSchema.optional().describe("The background job this row marks the start of."),
     credentialOffer: TranscriptCredentialOfferSchema.optional().describe(

package/src/events/verify-nudge.ts

@@ -1,7 +1,7 @@
 // The follow-up the daemon USED to send when a turn ended with work it could not confirm. Nothing sends it any more:
-// nothing checks inside a conversation, CI checks what the owner pushes (schemas/workspace/push-checks.ts). It stays on
-// the wire because records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not
-// reach a reader as their own words.
+// nothing checks inside a conversation, CI checks what the owner pushes (schemas/ci.ts). It stays on the wire because
+// records already hold it, and the chat has to go on recognising it: a prompt nobody typed must not reach a reader as
+// their own words.
 
 // Anchored on by the reader, so it must stay unique and stable across releases — a reworded opening un-recognises every
 // nudge already in a record, and they read as the user's own typing again.

package/src/ids/conversation-ids.test.ts

@@ -7,8 +7,6 @@ import {
     latestFixAttempt,
     newConversationId,
     nextFixAttemptId,
-    PUSH_FIX_PREFIX,
-    pushFixConversationId,
 } from "./conversation-ids.js";
 import { ConversationIdSchema } from "../schemas/agent.js";
 
@@ -90,28 +88,6 @@ test("the prefix is carried by every fix id", () => {
     expect(ciFixConversationId(`ci-fix`, 7)).toBe(`ci-fix-ci-fix-7`);
 });
 
-test("a push fix id is the same string every time the same failure derives it", () => {
-    expect(pushFixConversationId(`intentic`, `checkout gates,lint`)).toBe(pushFixConversationId(`intentic`, `checkout gates,lint`));
-    expect(pushFixConversationId(`intentic`, `checkout gates,lint`)).toMatch(/^push-fix-intentic-[0-9a-z]{7}$/);
-});
-
-test("a push fix id separates failures and scopes", () => {
-    expect(pushFixConversationId(`intentic`, `lint`)).not.toBe(pushFixConversationId(`intentic`, `checkout gates`));
-    expect(pushFixConversationId(`web`, `lint`)).not.toBe(pushFixConversationId(`api`, `lint`));
-});
-
-// Signatures cover raw gate output: control characters, unicode, path-like strings, and pathological lengths.
-test("every derived push fix id passes the conversation-id guard", () => {
-    const signatures = [``, `checkout gates`, `✗ lint · pnpm lint`, `a`.repeat(4_000), `../../etc/passwd`, `a\nb\tc`, `résumé`];
-    for (const scope of [`root`, `apps/web`, `my repo`, `___`, `x`.repeat(80)]) {
-        for (const signature of signatures) {
-            const id = pushFixConversationId(scope, signature);
-            expect(ConversationIdSchema.safeParse(id).success).toBe(true);
-            expect(id.startsWith(PUSH_FIX_PREFIX)).toBe(true);
-        }
-    }
-});
-
 // Attempt 1 is the bare derived id, so every fix conversation minted before attempts existed reads as attempt 1.
 test("the first attempt wears the failure's own id, later ones carry their number", () => {
     const base = ciFixConversationId(`web`, 41);
@@ -136,8 +112,8 @@ test("another failure's id is not an attempt at this one", () => {
 });
 
 test("attempts are read off the roster, earliest first, and the newest is the live answer", () => {
-    const base = pushFixConversationId(`intentic`, `lint`);
-    const roster = [{ id: `swift-otter-k9m2` }, { id: fixAttemptId(base, 3) }, { id: base }, { id: pushFixConversationId(`intentic`, `typecheck`) }];
+    const base = ciFixConversationId(`intentic`, 7);
+    const roster = [{ id: `swift-otter-k9m2` }, { id: fixAttemptId(base, 3) }, { id: base }, { id: ciFixConversationId(`intentic`, 8) }];
     expect(fixAttemptsOf(base, roster).map((entry) => entry.attempt)).toEqual([1, 3]);
     expect(latestFixAttempt(base, roster)?.agent.id).toBe(fixAttemptId(base, 3));
     expect(latestFixAttempt(base, [])).toBeUndefined();

package/src/ids/conversation-ids.ts

@@ -160,13 +160,9 @@ const repoSlug = (repo: string): string =>
         .replace(/^-+|-+$/g, "") || "repo";
 export const ciFixConversationId = (repo: string, runId: number): string => `${CI_FIX_PREFIX}${repoSlug(repo)}-${runId}`;
 
-// Keyed by when the project's push red began (pushFixBase, `red:<since>`), not a run id (a push has none): a refused push
-// is owed by that red too (push-checks-store.ts). Hashed rather than spelled into the branch name; the fix agent's first
-// message names what it is for.
-export const PUSH_FIX_PREFIX = "push-fix-";
-
 // FNV-1a, not a cryptographic hash: nothing here is secret, the only requirement is the same failure yields the same
-// seven characters in every browser and in node. The one spelling: a push finding's id (push-checks-store.ts) is this too.
+// seven characters in every browser and in node. The one spelling: what a failing main owes is named by it too (a
+// failed job's id, ci/main-fixer.ts).
 const FNV_OFFSET = 0x811c_9dc5;
 const FNV_PRIME = 0x0100_0193;
 export const fnvDigest = (text: string): string => {
@@ -177,14 +173,12 @@ export const fnvDigest = (text: string): string => {
     return (hash >>> 0).toString(36).padStart(7, "0");
 };
 
-export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${fnvDigest(signature)}`;
-
-// A red main-line check that no conversation still holding the work could take: keyed by the project and the moment its
-// red streak began, so every attempt at one streak shares a base and a later streak in the same project starts over.
+// A failing main-line check that no conversation still holding the work could take: keyed by the project and the moment
+// it began failing, so every attempt at one streak shares a base and a later streak in the same project starts over.
 // Seconds in base36 keep it short; the workspace root is spelled `workspace`, since its project folder is empty.
 export const LAND_FIX_PREFIX = "land-fix-";
-export const landFixConversationId = (project: string, redSince: number): string =>
-    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(redSince / 1000).toString(36)}`;
+export const landFixConversationId = (project: string, failingSince: number): string =>
+    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(failingSince / 1000).toString(36)}`;
 
 // ONE FAILURE, MANY ATTEMPTS, ONE LIVE ANSWER. The derived id above names the FAILURE; an attempt at it is a
 // conversation of its own, so starting over (another model, a clean worktree) never rewrites a record some other window

package/src/ids/project-dir.fixture.json

@@ -0,0 +1,65 @@
+{
+    "names": [
+        { "name": "my-app", "valid": true },
+        { "name": "My_App.v2", "valid": true },
+        { "name": "a", "valid": true },
+        { "name": "0", "valid": true },
+        { "name": "Public", "valid": true },
+        { "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "valid": true },
+        { "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "valid": false },
+        { "name": "public", "valid": false },
+        { "name": "refs", "valid": false },
+        { "name": "site", "valid": false },
+        { "name": "root", "valid": false },
+        { "name": "intent", "valid": false },
+        { "name": "desired-state", "valid": false },
+        { "name": "app", "valid": false },
+        { "name": "AGENTS.md", "valid": false },
+        { "name": "node_modules", "valid": false },
+        { "name": "dist", "valid": false },
+        { "name": "venv", "valid": false },
+        { "name": "claude.json", "valid": false },
+        { "name": "__pycache__", "valid": false },
+        { "name": ".intentic", "valid": false },
+        { "name": ".hidden", "valid": false },
+        { "name": "-flag", "valid": false },
+        { "name": "_under", "valid": false },
+        { "name": "", "valid": false },
+        { "name": "a/b", "valid": false },
+        { "name": "..", "valid": false },
+        { "name": "has space", "valid": false },
+        { "name": "café", "valid": false },
+        { "name": "my-app/", "valid": false }
+    ],
+    "folders": [
+        { "folder": "my-app", "dirName": "my-app" },
+        { "folder": "My App", "dirName": "My-App" },
+        { "folder": "My  App!!", "dirName": "My-App" },
+        { "folder": "Café Menu", "dirName": "Cafe-Menu" },
+        { "folder": "日本語", "dirName": "project" },
+        { "folder": "", "dirName": "project" },
+        { "folder": "...", "dirName": "project" },
+        { "folder": ".config", "dirName": "config" },
+        { "folder": "--flag--", "dirName": "flag" },
+        { "folder": "_private", "dirName": "private" },
+        { "folder": "public", "dirName": "public-project" },
+        { "folder": "site", "dirName": "site-project" },
+        { "folder": "app", "dirName": "app-project" },
+        { "folder": "AGENTS.md", "dirName": "AGENTS.md-project" },
+        { "folder": "dist", "dirName": "dist-project" },
+        { "folder": "node_modules", "dirName": "node_modules-project" },
+        { "folder": "__pycache__", "dirName": "pycache__" },
+        { "folder": "a--b", "dirName": "a-b" },
+        { "folder": "report (final) v2", "dirName": "report-final-v2" },
+        {
+            "folder": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+            "dirName": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+        },
+        {
+            "folder": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa b",
+            "dirName": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        { "folder": "C++ Project", "dirName": "C-Project" },
+        { "folder": "release.2024.", "dirName": "release.2024" }
+    ]
+}