@intentic/sandbox-contract 1.308.0 → 1.309.0

package/src/schemas/metrics.ts

@@ -105,3 +105,151 @@ export const SandboxMetricsSchema = z.object({
         .describe("Every process in the sandbox but the daemon, by what kind of work it is. A kind with nothing running is absent."),
 });
 export type SandboxMetrics = z.infer<typeof SandboxMetricsSchema>;
+
+// What is filling the sandbox's disk, by what it is for (GET /system/storage). Sizes are apparent bytes, and a file
+// with several hard links counts once, toward the first place the scan met it.
+
+// Every category a byte on the sandbox's volumes can belong to; STORAGE_CLEANABILITY below says which may be cleaned.
+export const STORAGE_CATEGORIES = [
+    // The workspace's own files: repositories, their dependencies, anything the owner or an agent put there.
+    "workspace",
+    // Transcripts, runtime session stores, attachments and loop memory of every conversation, archived ones included.
+    "conversations",
+    // Each open conversation's own checkout of the repositories, and the dependencies its turns installed over them.
+    "checkouts",
+    // The minute-by-minute and per-turn snapshots the History timeline restores from.
+    "restorePoints",
+    // The repositories' own git data: every commit and branch, pushed or not.
+    "repositories",
+    // Installed versions of the agent runtimes: the one turns use and the one kept for Revert.
+    "engines",
+    // Search indexes and caches the sandbox keeps up to date by itself while it runs.
+    "indexes",
+    // Installed extensions and their scratch.
+    "extensions",
+    // The sandbox's own Docker: images, containers, volumes.
+    "docker",
+    // Settings, credentials, sign-ins and the ledgers of what was spent and done.
+    "state",
+    // Anything no part of the sandbox claims.
+    "other",
+    // Git data and checkouts of repositories deleted from the workspace.
+    "trash",
+    // Copies of the sandbox packed for download.
+    "exports",
+    // Files agents produced: generated images, reports, harness output.
+    "artifacts",
+    // Screenshots and page snapshots the agent's browser took.
+    "browserCaptures",
+    // The agent browser's profiles, with the sites it is signed in to.
+    "browserProfiles",
+    // Weights downloaded for local models.
+    "modelWeights",
+    // The sandbox's own logs and terminal captures.
+    "logs",
+    // Scratch space agents and checks leave behind.
+    "scratch",
+    // Package managers' content stores, which the next install refills.
+    "packageStores",
+    // Build tools' output caches.
+    "buildCaches",
+] as const;
+export const StorageCategoryIdSchema = z.enum(STORAGE_CATEGORIES);
+export type StorageCategoryId = z.infer<typeof StorageCategoryIdSchema>;
+
+// none: never removed from here; safe: comes back by itself, removed without asking; confirm: removed only once the
+// owner has read what it costs.
+export const StorageCleanabilitySchema = z.enum(["none", "safe", "confirm"]);
+export type StorageCleanability = z.infer<typeof StorageCleanabilitySchema>;
+
+// Which categories may be cleaned, and which ask first: the daemon's cleaner refuses by it, the editor words its
+// confirm by it. State, credentials and live work are `none`; what regenerates is `safe`; the owner's own data asks.
+export const STORAGE_CLEANABILITY = {
+    workspace: "none",
+    conversations: "none",
+    // A live conversation's working copy; archiving the conversation is what frees it.
+    checkouts: "none",
+    // No compaction is safe to offer: `git gc --auto` already runs after every snapshot, and every object is reachable.
+    restorePoints: "none",
+    repositories: "none",
+    // The Engines card keeps two versions and owns which is which; removing one here would strand its Revert.
+    engines: "none",
+    // Held open by what maintains them: removing a file frees nothing until they close it.
+    indexes: "none",
+    extensions: "none",
+    docker: "none",
+    state: "none",
+    other: "none",
+    // Nothing reads it again, but it may hold commits never pushed anywhere.
+    trash: "confirm",
+    exports: "confirm",
+    artifacts: "confirm",
+    browserCaptures: "confirm",
+    browserProfiles: "confirm",
+    modelWeights: "confirm",
+    logs: "safe",
+    scratch: "safe",
+    packageStores: "safe",
+    buildCaches: "safe",
+} as const satisfies Record<StorageCategoryId, StorageCleanability>;
+
+export const StorageItemSchema = z.object({
+    path: z.string().describe("Where it is, as an absolute path inside the sandbox."),
+    bytes: z.number().describe("Its size in bytes."),
+});
+export type StorageItem = z.infer<typeof StorageItemSchema>;
+
+export const StorageCategoryUsageSchema = z.object({
+    id: StorageCategoryIdSchema,
+    cleanability: StorageCleanabilitySchema.describe("Whether this category can be cleaned from here, and whether cleaning it asks first."),
+    bytes: z.number().describe("Its size in bytes."),
+    files: z.number().describe("How many files it holds."),
+    cleanableBytes: z
+        .number()
+        .optional()
+        .describe(
+            "What cleaning it would free right now: only what is old enough and not in use. Absent where nothing here may be cleaned, and for a package store, whose own tool decides what no project needs.",
+        ),
+    items: z.array(StorageItemSchema).describe("Its biggest parts, largest first, at most eight."),
+});
+export type StorageCategoryUsage = z.infer<typeof StorageCategoryUsageSchema>;
+
+export const StorageScanSchema = z.object({
+    startedAt: z.number().describe("When the scan began, in milliseconds."),
+    finishedAt: z.number().describe("When it ended, in milliseconds: the moment these sizes describe."),
+    outcome: z
+        .enum(["complete", "partial"])
+        .describe("`partial` when the scan hit its time limit first, so every size is at least what it says rather than exactly it."),
+    disk: z
+        .object({
+            usedBytes: z.number().describe("Space used on the volume the workspace lives on."),
+            totalBytes: z.number().describe("That volume's size."),
+        })
+        .optional()
+        .describe("The volume as a whole. Absent when the volume would not say."),
+    categories: z.array(StorageCategoryUsageSchema).describe("Every category that holds anything, largest first."),
+    unreadable: z.number().describe("Files and folders the scan could not read, and so did not count."),
+});
+export type StorageScan = z.infer<typeof StorageScanSchema>;
+
+export const StorageReportSchema = z.object({
+    scan: StorageScanSchema.optional().describe("The last scan that finished. Absent until one has, and again after the daemon restarts."),
+    scanning: z.boolean().describe("Whether a scan is running now."),
+});
+export type StorageReport = z.infer<typeof StorageReportSchema>;
+
+export const StorageCleanInputSchema = z.object({
+    category: StorageCategoryIdSchema.describe("The category to clean; one whose cleanability is `none` is refused."),
+});
+export type StorageCleanInput = z.infer<typeof StorageCleanInputSchema>;
+
+export const StorageCleanResultSchema = z.object({
+    category: StorageCategoryIdSchema,
+    freedBytes: z.number().describe("Space the removals gave back, in bytes. A file that is still linked elsewhere frees nothing and is not counted."),
+    removed: z.number().describe("How many items were removed."),
+    kept: z
+        .number()
+        .describe("How many were left in place: changed too recently, in use by a running program, or no longer this category's."),
+    failed: z.number().describe("How many removals the filesystem refused."),
+});
+export type StorageCleanResult = z.infer<typeof StorageCleanResultSchema>;

package/src/schemas/providers/plan-limits.ts

@@ -214,6 +214,14 @@ export const SteerSchema = z
     .object({
         conversationId: z.string().min(1).describe("Which running conversation to interrupt."),
         text: z.string().max(20_000).describe("What to say to it. It arrives mid-turn without stopping the turn."),
+        messageId: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe(
+                "Your id for this message. Sending again under an id the sandbox already took is answered with what it did with it the first time, never a second delivery. Leave it out and the sandbox names the message itself.",
+            ),
         attachments: z
             .array(z.string().min(1))
             .max(20)
@@ -233,8 +241,42 @@ export const SteerSchema = z
     .refine((steer) => steer.text.trim().length > 0 || (steer.attachments?.length ?? 0) > 0, {
         message: "text or attachments required",
     });
-// True cancel, aborted daemon-side; unlike closing the /agent fetch, which sends no cancel frame.
-export const StopTurnSchema = z.object({ conversationId: z.string().min(1).describe("Which conversation's running turn to cancel.") });
+// True cancel, aborted daemon-side; unlike closing the /agent fetch, which sends no cancel frame. A stop names the run
+// it means, so one arriving after that run settled cannot cancel whatever the conversation started next.
+export const StopTurnSchema = z.union([
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        run: z
+            .string()
+            .min(1)
+            .describe(
+                "The run you mean to cancel, as starting or attaching to it named it. If another turn has started since, nothing is cancelled and the answer names the one running instead.",
+            ),
+    }),
+    // A send not yet answered has no run to name, only the id it gave its message.
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        messageId: z
+            .string()
+            .min(1)
+            .describe(
+                "The message you sent, while its run is not named yet: cancels the turn it is in. If none is, nothing is cancelled: the message has not become a turn, or its turn has already ended.",
+            ),
+    }),
+    // Only for a turn nobody can name: one the sandbox runs with no run to attach to (a scheduled automation's).
+    z.object({
+        conversationId: z.string().min(1).describe("Which conversation's running turn to cancel."),
+        live: z
+            .literal(true)
+            .describe("Cancel whatever turn is running now, whichever that is. Only for a turn you cannot name: one that has no run to attach to."),
+    }),
+]);
+export type StopTurn = z.infer<typeof StopTurnSchema>;
+export const StopResultSchema = z.object({
+    stopped: z.boolean().describe("Whether a turn was cancelled."),
+    running: z.string().optional().describe("The run that is live instead of the one you named, left running. Absent when nothing else runs."),
+});
+export type StopResult = z.infer<typeof StopResultSchema>;
 // The press carries WHO serves the re-run; the daemon keeps WHAT the turn is (prompt, attachments, worktree) from its
 // own record, since re-deriving from a stripped client transcript would replay a different turn.
 export const ResumeRoutingSchema = z.object({
@@ -261,3 +303,26 @@ export const ResumeTurnSchema = z.object({
         "Who serves the re-run, when the conversation has been re-pointed since it was refused. Leave it out to run it on whatever the turn carried.",
     ),
 });
+// Names one queued message as it was read, so a change made against an older copy is refused rather than written over
+// somebody else's.
+export const QueuedMessageRefSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue."),
+    id: z.string().min(1).describe("Which waiting message."),
+    revision: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("The message's revision as you read it. If it has been changed since, from this window or another, nothing happens."),
+});
+export type QueuedMessageRef = z.infer<typeof QueuedMessageRefSchema>;
+export const QueueEditSchema = QueuedMessageRefSchema.extend({
+    text: z.string().describe("What the message should say instead. It keeps its place in the queue."),
+});
+export type QueueEdit = z.infer<typeof QueueEditSchema>;
+export const QueueResumeSchema = z.object({
+    conversationId: z.string().min(1).describe("Whose queue to let go."),
+    routing: ResumeRoutingSchema.optional().describe(
+        "Who serves the turn the waiting messages start, when the conversation has been re-pointed since they were queued: the usual answer to a refusal that held them. Leave it out to send them as they were queued.",
+    ),
+});
+export type QueueResume = z.infer<typeof QueueResumeSchema>;

package/src/schemas/providers/usage.ts

@@ -72,6 +72,9 @@ export const UsageTurnSchema = z.object({
     // Hash of the brief that was sent, recorded on control turns too. Load-bearing rather than decorative: the file is
     // rewritten monthly, so a 30-day window holds two different treatments and pooling them would measure neither.
     notesCohort: z.string().optional(),
+    // Arm of the lean-guidance experiment, stable per conversation; true is the short form. The cohort hashes both forms.
+    guidanceArm: z.boolean().optional(),
+    guidanceCohort: z.string().optional(),
     // What became of pre-turn retrieval on this turn, and how long it took. Assignment and DELIVERY are different
     // facts: the first version of this mechanism was assigned to every eligible turn and reached four in five of them,
     // which is the difference between a null result and a mechanism that never ran. Absent means the flag was off, so

package/src/schemas/settings.ts

@@ -254,6 +254,21 @@ export const SandboxSettingsSchema = z.object({
         .describe(
             "Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control.",
         ),
+    // Measured by the `guidance` experiment against the full set; the full set stays the default until that says otherwise.
+    leanGuidance: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Send this product's own guidance in its short form: only what the agent cannot find out by looking, instead of a paragraph for every habit it was once caught in. Off by default, because the long form is the one the product was tuned on.",
+        ),
+    leanGuidanceHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe(
+            "What share of conversations to keep on the long form, so the two can be compared. Whole conversations rather than individual turns, because the guidance sits in the prompt for the whole session.",
+        ),
     iqSearch: z
         .boolean()
         .default(false)
@@ -578,6 +593,7 @@ export const SavingsReportSchema = z.object({
     // Same absence rule as `search`: not measured, never zero.
     map: TurnExperimentSchema.optional(),
     notes: TurnExperimentSchema.optional(),
+    guidance: TurnExperimentSchema.optional(),
 });
 export type SavingsReport = z.infer<typeof SavingsReportSchema>;
 

package/src/schemas/turn-break.ts

@@ -47,3 +47,11 @@ export const RETRY_LADDER_TRIES = RETRY_LADDER_MS.length;
 
 /** The wait before the next rung, or undefined once the ladder is spent. */
 export const retryLadderDelay = (triesWithoutProgress: number): number | undefined => RETRY_LADDER_MS[triesWithoutProgress];
+
+// Where an automatic re-run ladder stands, whichever wall climbs it (an outage's breaker, a stopped turn's rungs).
+// `made` equal to `max` is a spent ladder: nothing more goes unasked.
+export const RetryLadderSchema = z.object({
+    made: z.number().int().min(0).describe("Automatic re-runs already sent for this turn."),
+    max: z.number().int().min(1).describe("How many the ladder may send before it stands down."),
+});
+export type RetryLadder = z.infer<typeof RetryLadderSchema>;

package/src/state/history-state.ts

@@ -113,5 +113,11 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "runner-pair-consumed.json", portability: "identity" },
     // This container's own identity and reconnect token; elsewhere it would dial the parent as this runner.
     { path: "runner-identity.json", portability: "identity" },
+    // The owner's yes to a workspace's hooks, pinned to their bytes: a trust decision the target's owner makes again.
+    { path: "hook-approvals.json", portability: "identity", note: "Approve the workspace's Claude Code hooks again from Approvals." },
+    // The hook sets waiting for that yes; the next turn that finds them lists them again.
+    { path: "hook-requests.json", portability: "derived" },
+    // The owner's yes to each workspace extension's declared powers, decided again by the target's owner.
+    { path: "extension-approvals.json", portability: "identity", note: "Approve the extensions written in this workspace again from Extensions." },
     { path: "local-cert/", portability: "identity" },
 ];

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

@@ -60,8 +60,8 @@ describe(`staleQueryKeys`, () => {
     });
 
     it(`ignores a store's own temp file while it is mid-swap`, () => {
-        // jsonFile's atomic-rename temp name: `.<name>.<pid>.tmp` beside the target.
-        expect(staleQueryKeys([`.intentic/.settings.json.42.tmp`], [])).toEqual([]);
+        // writeTextFile's atomic-rename temp name: `.<name>.<pid>.<n>.tmp` beside the target.
+        expect(staleQueryKeys([`.intentic/.settings.json.42.7.tmp`], [])).toEqual([]);
         expect(staleQueryKeys([`.intentic/config/settings.json`], [])).toEqual([`settings`, `manifests`]);
     });
 

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

@@ -186,7 +186,8 @@ describe("foldTurn", () => {
                 code: "provider-outage",
                 message: "Anthropic is down.",
                 autoResume: "scheduled",
-                outage: { retryAt: 1, attempt: 2, maxAttempts: 6 },
+                outage: { retryAt: 1 },
+                retries: { made: 1, max: 6 },
             },
         ];
         // The row states what happened and nothing more: what happens next, and the one control that changes it, are
@@ -200,6 +201,23 @@ describe("foldTurn", () => {
         });
     });
 
+    // The count lives in the record, so a reader scrolling back sees how many times a stuck turn was sent again.
+    it("says on a stopped turn's row which automatic try comes next, or that the ladder stood down", () => {
+        const timedOut = "Google turn timed out waiting for OpenCode.";
+        const booked: AgentEvent[] = [{ kind: "error", message: timedOut, autoResume: "scheduled", nextAt: 1, retries: { made: 1, max: 3 } }];
+        expect(foldOf("hi", booked).at(-1)).toEqual({ role: "notice", text: `${timedOut} Retrying by itself: attempt 2 of 3.` });
+        const spent: AgentEvent[] = [{ kind: "error", message: timedOut, autoResume: "available", retries: { made: 3, max: 3 } }];
+        expect(foldOf("hi", spent).at(-1)).toEqual({
+            role: "notice",
+            text: `${timedOut} Retried 3 of 3 times by itself; nothing more is sent automatically.`,
+        });
+        // An outage nobody armed says so, instead of promising the breaker's retry.
+        const unarmed: AgentEvent[] = [
+            { kind: "error", code: "provider-outage", message: "Anthropic is down.", autoResume: "available", outage: { retryAt: 1 }, retries: { made: 0, max: 6 } },
+        ];
+        expect(foldOf("hi", unarmed).at(-1)).toEqual({ role: "notice", text: "Anthropic is down. Nothing is retrying it, so the turn is waiting here." });
+    });
+
     it("writes the turn's own events down as notices", () => {
         const events: AgentEvent[] = [
             { kind: "worktree", branch: "agent/x", base: "abc1234", sync: { commits: 2, blocked: [] } },
@@ -213,7 +231,7 @@ describe("foldTurn", () => {
             { role: "notice", text: "Context compacted to free up space." },
             {
                 role: "notice",
-                text: "Changes landed in your workspace: review them in the Changes panel. Installing 1 new dependency it added; the project's checks run when that finishes, and the outcome lands in Activity.",
+                text: "Changes landed in your workspace: review them in the Changes panel. Installing 1 dependency it added or changed; the project's checks run when that finishes, and the outcome lands in Activity.",
                 noticeAction: "depsInstall",
             },
         ]);
@@ -495,8 +513,8 @@ describe("patches", () => {
     });
 });
 
-// A refusal that ran nothing offers the message back to the composer — true where somebody typed one, false for a run
-// that started itself, where there is no composer and no typed message.
+// A refusal that ran nothing offers the message back for another press — true where somebody typed one, false for a
+// run that started itself, where there is no composer and no typed message.
 describe(`a refusal that ran nothing`, () => {
     const REFUSED = { kind: `error`, code: `context-window-too-small`, message: `This model accepts 16,384 tokens.` } as const satisfies AgentEvent;
 
@@ -551,9 +569,9 @@ describe(`a refusal that ran nothing`, () => {
         expect(foldOf(`land it`, [REFUSED]).at(-1)?.noticeAction).toBeUndefined();
     });
 
-    // The bug this retraction exists for: the composer keeps the words for another press, so a bubble left standing
-    // here is the SAME message a second time, and a third, once per press against a gate that keeps refusing.
-    it(`takes the message back out, leaving the composer's copy as the only one`, () => {
+    // The bug this retraction exists for: the conversation's queue keeps the words for another press, so a bubble left
+    // standing here is the SAME message a second time, and a third, once per press against a gate that keeps refusing.
+    it(`takes the message back out, leaving the queue's copy as the only one`, () => {
         const fold = new TranscriptFold(openingOf(`land it`));
         const patches = fold.apply(REFUSED);
 

package/src/text/transcript-fold.ts

@@ -62,10 +62,11 @@ const dependencyLine = (deps: { missing: number; started: string[]; deferred: bo
     if (deps === undefined || deps.missing === 0) {
         return ``;
     }
-    const what = `${deps.missing} new ${deps.missing === 1 ? `dependency` : `dependencies`}`;
+    // `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} are queued: installation starts after this turn and any other active agents finish, appears in Work terminals, then its checks and outcome land in Activity.`
-        : ` Installing ${what} it added; the project's checks run when that finishes, and the outcome lands in Activity.`;
+        ? ` ${what} ${deps.missing === 1 ? `is` : `are`} queued: installation starts after this turn and any other active agents finish, appears in Work terminals, then its checks and outcome land in Activity.`
+        : ` Installing ${what}; the project's checks run when that finishes, and the outcome lands in Activity.`;
 };
 
 // One line reporting the daemon's rebase of this agent's branch onto the current workspace; `blocked` names repos it
@@ -106,10 +107,10 @@ const landedRow = (event: Extract<AgentEvent, { kind: "landed" }>): TranscriptRo
     };
 };
 
-// The clause after a refusal that ran nothing. A turn somebody typed is held in the composer for another press; a turn
-// that started itself — an automation, a loop, a watch wake — has no typed message and nobody watching, so promising a
-// resend there names a composer the reader is not looking at. Neither version promises a retry: whether one comes is
-// the scheduler's decision, not this row's to state.
+// The clause after a refusal that ran nothing. A turn somebody typed is held in its conversation's queue for another
+// press; a turn that started itself — an automation, a loop, a watch wake — has no typed message and nobody watching,
+// so promising a resend there names a composer the reader is not looking at. Neither version promises a retry: whether
+// one comes is the scheduler's decision, not this row's to state.
 const undelivered = (unattended: boolean): string =>
     unattended
         ? `Nothing ran, and nothing is held: this run started on its own, so there is no message waiting to be sent again.`
@@ -152,9 +153,7 @@ const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow
     const { message, code } = event;
     switch (code) {
         case "provider-outage":
-            return event.outage === undefined
-                ? { role: "notice", text: `${message} Nothing is retrying it, so the turn is waiting here.` }
-                : { role: "notice", text: `${message} Retrying by itself: attempt ${event.outage.attempt} of ${event.outage.maxAttempts}.` };
+            return { role: "notice", text: `${message} ${retryClause(event) ?? `Nothing is retrying it, so the turn is waiting here.`}` };
         case "claude-token-refused":
             return event.autoResume === "scheduled"
                 ? {
@@ -169,18 +168,31 @@ const errorRow = (event: Extract<AgentEvent, { kind: "error" }>): TranscriptRow
             break;
     }
     if (!turnedAwayCode(code)) {
-        return { role: "notice", text: message };
+        const clause = retryClause(event);
+        return { role: "notice", text: clause === undefined ? message : `${message} ${clause}` };
     }
     return heldRow(event);
 };
 
-// The turn's opening user row: text, timestamp, attachments, and whatever the daemon later stamps onto it (checkpoint,
-// notes).
-export const userRow = (text: string, sentAt: number, attachments: readonly string[]): TranscriptRow => {
+// What a laddered wall's automatic re-runs are doing, said on the failure's own row so the count stays in the record.
+const retryClause = (event: Extract<AgentEvent, { kind: "error" }>): string | undefined => {
+    const { retries } = event;
+    if (retries === undefined) {
+        return undefined;
+    }
+    if (event.autoResume === "scheduled") {
+        return `Retrying by itself: attempt ${retries.made + 1} of ${retries.max}.`;
+    }
+    return retries.made >= retries.max ? `Retried ${retries.made} of ${retries.max} times by itself; nothing more is sent automatically.` : undefined;
+};
+
+// The turn's opening user row: text, timestamp, attachments, the message's id, and whatever the daemon later stamps onto
+// it (checkpoint, notes).
+export const userRow = (text: string, sentAt: number, attachments: readonly string[], messageId?: string): TranscriptRow => {
     // Drops an attachment already inline as an @-mention, unless it's a generated upload path (its own thumbnail).
     const inline = new Set(mentionedPathTokens(text));
     const chips = attachments.filter((path) => !inline.has(path) || path.includes(`/records/artifacts/attachments/`));
-    return { role: "user", text, sentAt, ...(chips.length > 0 ? { attachments: chips } : {}) };
+    return { role: "user", text, sentAt, ...(chips.length > 0 ? { attachments: chips } : {}), ...(messageId === undefined ? {} : { messageId }) };
 };
 
 export class TranscriptFold {
@@ -196,7 +208,7 @@ export class TranscriptFold {
     private readonly parked = new Map<string, number>();
     // The turn's opening user row, where the checkpoint and daemon notes land; cleared once `retract` takes it back.
     private opener: number | undefined;
-    // Set by `retract`: this turn was refused before it ran, and its message went back to the composer.
+    // Set by `retract`: this turn was refused before it ran, and its message went back to the conversation's queue.
     private unrun = false;
 
     constructor(
@@ -426,6 +438,7 @@ export class TranscriptFold {
             text: event.text,
             sentAt: event.sentAt,
             ...(event.attachments === undefined ? {} : { attachments: [...event.attachments] }),
+            ...(event.messageId === undefined ? {} : { messageId: event.messageId }),
         });
         // Anchors pair by position with the checkpoints only a person's steer reserves.
         if (event.voice === undefined) {
@@ -461,9 +474,9 @@ export class TranscriptFold {
         );
     }
 
-    // Attended refusals only: the composer holds those words for another press, so a bubble left standing repeats them
-    // once per press. Splicing is safe because nothing ran — no open bubble, no parked card, no steer above it. A turn
-    // the sandbox kept (`held`) keeps its message and is recorded: no composer anywhere holds a copy of it.
+    // Attended refusals only: the conversation's queue holds those words for another press, so a bubble left standing
+    // repeats them once per press. Splicing is safe because nothing ran — no open bubble, no parked card, no steer above
+    // it. A turn the sandbox kept (`held`) keeps its message and is recorded: no queue holds a copy of it.
     private retract(event: Extract<AgentEvent, { kind: "error" }>): TranscriptPatch[] {
         if (!this.turnedAway(event) || event.held !== undefined) {
             return [];