@intentic/sandbox-contract 1.239.0 → 1.242.0

package/src/events.ts

@@ -3,7 +3,7 @@ import { AgentHarnessSchema, AgentProviderSchema, PermissionModeSchema } from ".
 import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
 import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
 import { FastModeStateSchema } from "./schemas/fast-mode.js";
-import { AgentReplySchema, UsageWindowSchema } from "./schemas/plan-limits.js";
+import { AccountUsageSchema, AgentReplySchema, ProviderRefusalSchema, UsageWindowSchema } from "./schemas/plan-limits.js";
 import { ShareDetailSchema } from "./schemas/share.js";
 import { MemberRoleSchema } from "./schemas/shared.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "./schemas/terminal.js";
@@ -45,7 +45,11 @@ export type AskQuestion = z.infer<typeof AskQuestionSchema>;
 export const ProgramAskSchema = z.object({
     text: z.string().describe("What would run."),
     language: z.enum(["bash", "javascript"]).describe("Which of the two backends it is written for, named as the grammar that colours it."),
-    truncated: z.boolean().describe("Whether this is the head of a longer program, so the card can say so instead of ending mid-word."),
+    truncated: z
+        .boolean()
+        .describe(
+            "Whether this is an excerpt of a longer program, so the card can say so instead of ending mid-word. An excerpt always carries the flagged fragment: the beginning, then a window around the fragment, with any skipped middle written into the text as a bracketed count.",
+        ),
     spans: z
         .array(z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }))
         .describe("Which fragments of the text put it in the class that held it. Offsets into text, in order, never overlapping."),
@@ -76,11 +80,16 @@ export const PermissionAskSchema = z.object({
     program: ProgramAskSchema.optional().describe(
         "The program this card is holding, when the card is about one. Present on a command gate's card and absent on every other permission ask.",
     ),
+    /* THE JUDGE'S OWN SENTENCE, and on a command card it is the reason the card exists rather than a note added
+     * to it: the judge read the owner's policy and the program and decided this needed asking, and this is what
+     * it decided. Written by the quick model from the program text and the policy, never by the agent being
+     * gated — a card whose persuasive half was authored by the thing it is stopping argues for its own approval,
+     * and the turns that raise cards are exactly the ones whose account of themselves may be a stranger's. */
     explain: z
         .string()
         .optional()
         .describe(
-            "One plain sentence saying what the program does and why the agent wants it. Written by the quick model, never by the agent being gated, and only when the owner switched the setting on.",
+            "One plain sentence saying what the program does and why it is being asked about. Written by the judge that read your safety policy, never by the agent being gated.",
         ),
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
@@ -286,19 +295,192 @@ export const ToolCallContentSchema = z.discriminatedUnion("type", [
 ]);
 export type ToolCallContent = z.infer<typeof ToolCallContentSchema>;
 
-// ---- restored transcripts ----
-// What /sessions/{id} replays into a reopened tab, and what the daemon's own conversation record stores. It has
-// to REDRAW the transcript the user was looking at rather than merely paraphrase it, so it keeps the assistant's
-// thinking and the tool cards its turn ran, which is also what lets a runtime handoff carry more than bare
-// prose across to the replacement session (see runtime-history.ts). Reconstructed from the stored
-// tool_use/tool_result blocks, so a restored card carries everything the live `tool_call` frame did except
-// the streaming-only correlation fields.
+/* WHAT A PARKED CARD IS ABOUT: the document the turn wrote and is now asking a question against.
+ *
+ * A card asks for a decision; until this it carried no SUBJECT. The commonest shape of a real decision is "I
+ * analysed this and wrote it up, now choose", and the write-up went into a file whose card had already folded
+ * itself into `Write · +135 −0` twenty tool calls back. So the reader was asked to choose between options
+ * describing a document the chat had never shown them.
+ *
+ * Carried BY VALUE rather than as a path, for the same reason the diff on a tool call is: the bytes are already
+ * in hand when the card is raised, a path would make the card's meaning depend on a file that keeps changing
+ * under it, and a restored or published transcript has no workspace to go read. The path rides along anyway, so
+ * a document past the wire cap still has somewhere to send the reader.
+ *
+ * Nothing is asked of the MODEL for this. It calls `ask` exactly as before; the daemon knows what the turn
+ * wrote, because every write came past it as a frame (documents.ts decides which of them is a document). A
+ * harness that can see the answer must not spend prompt on asking the model to repeat it. */
+export const CardDocumentSchema = z.object({
+    path: z.string().describe("Where it lives, as a workspace path."),
+    title: z.string().describe("What it is called: its opening heading, or its file name."),
+    markdown: z.string().describe("The document itself."),
+    truncated: z.boolean().optional().describe("It was clipped at the wire cap; the file on disk has more."),
+    plan: z.boolean().optional().describe("It is one of the CLI's plan files, written to be approved rather than merely read."),
+});
+export type CardDocument = z.infer<typeof CardDocumentSchema>;
+
+/* ONE CARD'S OWN FIELDS, spelled once. Three readers carry the same card and must agree on what it is: the
+ * frame that raises it (AgentEventSchema below), the journal entry that keeps a parked one across a restart
+ * (ParkedCardSchema), and the record row that keeps it for good (TranscriptRowSchema's card fields). A shape
+ * declared inline in each was three shapes with one name. */
+const REQUEST_ID = z.string().describe("What to send back when you answer.");
+const planCard = {
+    requestId: REQUEST_ID,
+    text: z.string().describe("The plan itself."),
+    // Present when the adjacent plan prose POINTS at a document instead of being one: the model wrote the real
+    // plan to a file and summarised it there. Absent when the text already is the whole plan.
+    document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
+};
+const questionCard = {
+    requestId: REQUEST_ID,
+    questions: z.array(AskQuestionSchema).describe("What it wants to know."),
+    document: CardDocumentSchema.optional().describe("The document this turn wrote and is asking about, so the choice can be read beside it."),
+};
+const permissionCard = { requestId: REQUEST_ID };
+// The agent's browser needs a person: it parked mid-sign-in on something it cannot clear itself (a captcha,
+// a password it does not hold, a phone check). `session` names the browser session on /browsers, the card's
+// one action is going THERE, where the live stage and Take control already are; the Browsers banner and this
+// card resolve the same requestId. `account` is the capability the sign-in is for, so the card can say whose
+// login is stuck even after the browser has navigated somewhere unrecognizable.
+const browserHelpCard = {
+    requestId: z.string(),
+    session: z.string(),
+    account: z.string(),
+    message: z.string(),
+};
+// The agent's TERMINAL needs a person: a command it started is sitting at a prompt it cannot answer (a
+// one-time password, a security-key touch, a confirm). `session` names the tmux session on the terminal
+// panel, the card's one action is going THERE, where the live pane and its prompt already are, which is
+// the same division of labour the browser card has with /browsers.
+const terminalHelpCard = {
+    requestId: z.string(),
+    session: z.string(),
+    message: z.string(),
+};
+const serviceOfferCard = { requestId: z.string(), offer: ServiceOfferSchema };
+const capabilityOfferCard = { requestId: z.string(), offer: CapabilityOfferSchema };
+const paymentOfferCard = { requestId: z.string(), offer: PaymentOfferSchema };
+
+/* HOW AN OFFER'S ACCEPTED HALF ENDED, the follow-up that lands on the card after the click. Each is the body of
+ * the frame that reports it (`service_receipt`, `capability_outcome`, `payment_receipt`) and the field the
+ * record keeps it in, one shape for both, so a receipt reopened tomorrow says exactly what the live card said. */
+export const ServiceReceiptSchema = z.object({
+    outcome: z.enum(["ok", "refunded", "refused"]),
+    credits: z.number(),
+    remaining: z.number().optional(),
+});
+export type ServiceReceipt = z.infer<typeof ServiceReceiptSchema>;
+export const CapabilityOutcomeSchema = z.object({
+    outcome: z.enum(["connected", "unfinished"]),
+    id: z.string().optional(),
+});
+export type CapabilityOutcome = z.infer<typeof CapabilityOutcomeSchema>;
+export const PaymentReceiptSchema = z.object({
+    outcome: z.enum(["paid", "failed"]),
+    amountUsd: z.string(),
+    transaction: z.string().optional(),
+    network: z.string().optional(),
+});
+export type PaymentReceipt = z.infer<typeof PaymentReceiptSchema>;
+
+/* THE THREE RESTORABLE CARDS, named so the turn journal can hold them verbatim: a parked turn's raised cards
+ * are written down beside its prompt (sandbox turn-journal.ts), and a daemon death under the park restores the
+ * very same frames instead of ending the turn `interrupted`, the card the user was about to answer survives
+ * the restart that killed the process holding it. The two handover cards are deliberately not among them:
+ * `browser_help`'s Chromium and `terminal_help`'s waiting command both die with the container, so those parks
+ * cannot be restored, only reported. */
+const PlanCardSchema = z.object({
+    kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
+    ...planCard,
+});
+const QuestionCardSchema = z.object({
+    kind: z.literal("question").describe("The agent has asked you something and is waiting."),
+    ...questionCard,
+});
+const PermissionCardSchema = PermissionAskSchema.extend({
+    kind: z.literal("permission").describe("The agent wants to use a tool it needs permission for."),
+    ...permissionCard,
+});
+export const ParkedCardSchema = z.discriminatedUnion("kind", [PlanCardSchema, QuestionCardSchema, PermissionCardSchema]);
+export type ParkedCard = z.infer<typeof ParkedCardSchema>;
+
+// ---- transcript cards ----
+/* THE CARDS A TURN PARKED ON, as a transcript row carries them: the card exactly as it was raised, how it was
+ * settled, and whatever landed on it afterwards (a permission's late explanation, an offer's stream and
+ * receipt). One shape for the live row and the recorded one, because they are the same row: the daemon folds
+ * the turn's frames into these rows as they stream (transcript-fold.ts) and writes the same rows down when the
+ * turn settles, so a chat reopened tomorrow is the chat that was on screen.
+ *
+ * The STATUS is settled by the fold, from the reply that released the card (card-status.ts), and rides the
+ * row rather than the reply it came from: every reader wants the verdict, and the one derivation lives beside
+ * the fold that applies it. `pending` is a card the turn is still parked on; `cancelled` is nobody answering,
+ * the turn stopped or died under the card, which is not a decision and does not read back as one. */
+export const PlanStatusSchema = z.enum(["pending", "approved", "rejected", "cancelled"]);
+export type PlanStatus = z.infer<typeof PlanStatusSchema>;
+export const QuestionStatusSchema = z.enum(["pending", "answered", "cancelled"]);
+export type QuestionStatus = z.infer<typeof QuestionStatusSchema>;
+export const PermissionStatusSchema = z.enum(["pending", "allowed", "always", "denied", "cancelled"]);
+export type PermissionStatus = z.infer<typeof PermissionStatusSchema>;
+export const HelpStatusSchema = z.enum(["pending", "helped", "declined", "cancelled"]);
+export type HelpStatus = z.infer<typeof HelpStatusSchema>;
+export const OfferStatusSchema = z.enum(["pending", "approved", "skipped", "cancelled"]);
+export type OfferStatus = z.infer<typeof OfferStatusSchema>;
+// A yes settles the DECISION, not the ask: the owner is now setting the capability up, so the card moves to
+// `connecting` and stays there until the capability_outcome frame says how the setup ended.
+export const CapabilityOfferStatusSchema = z.enum(["pending", "connecting", "skipped", "cancelled"]);
+export type CapabilityOfferStatus = z.infer<typeof CapabilityOfferStatusSchema>;
+
+export const TranscriptPlanSchema = z.object({ ...planCard, status: PlanStatusSchema.describe("Where the decision stands.") });
+export type TranscriptPlan = z.infer<typeof TranscriptPlanSchema>;
+export const TranscriptQuestionSchema = z.object({
+    ...questionCard,
+    status: QuestionStatusSchema.describe("Where the answer stands."),
+    answers: z
+        .record(z.string(), z.array(z.string()))
+        .optional()
+        .describe("What was chosen, keyed by the question, with the chosen labels or the user's own words."),
+});
+export type TranscriptQuestion = z.infer<typeof TranscriptQuestionSchema>;
+// `explain`, the judge's sentence, lands here through PermissionAskSchema; it is on the card from the moment
+// it is raised, so nothing patches it in afterwards.
+export const TranscriptPermissionSchema = PermissionAskSchema.extend({ ...permissionCard, status: PermissionStatusSchema.describe("Where the decision stands.") });
+export type TranscriptPermission = z.infer<typeof TranscriptPermissionSchema>;
+export const TranscriptBrowserHelpSchema = z.object({ ...browserHelpCard, status: HelpStatusSchema.describe("How the hand-over ended.") });
+export type TranscriptBrowserHelp = z.infer<typeof TranscriptBrowserHelpSchema>;
+export const TranscriptTerminalHelpSchema = z.object({ ...terminalHelpCard, status: HelpStatusSchema.describe("How the hand-over ended.") });
+export type TranscriptTerminalHelp = z.infer<typeof TranscriptTerminalHelpSchema>;
+export const TranscriptServiceOfferSchema = z.object({
+    ...serviceOfferCard,
+    status: OfferStatusSchema.describe("Where the decision stands."),
+    events: z.array(ServiceStreamEventSchema).optional().describe("The approved run's stream, in order (the service_event frames)."),
+    receipt: ServiceReceiptSchema.optional().describe("How the approved run ended (the service_receipt frame)."),
+});
+export type TranscriptServiceOffer = z.infer<typeof TranscriptServiceOfferSchema>;
+export const TranscriptCapabilityOfferSchema = z.object({
+    ...capabilityOfferCard,
+    status: CapabilityOfferStatusSchema.describe("Where the decision stands."),
+    outcome: CapabilityOutcomeSchema.optional().describe("How an accepted ask's setup ended (the capability_outcome frame)."),
+});
+export type TranscriptCapabilityOffer = z.infer<typeof TranscriptCapabilityOfferSchema>;
+export const TranscriptPaymentOfferSchema = z.object({
+    ...paymentOfferCard,
+    status: OfferStatusSchema.describe("Where the decision stands."),
+    receipt: PaymentReceiptSchema.optional().describe("How the approved payment ended (the payment_receipt frame)."),
+});
+export type TranscriptPaymentOffer = z.infer<typeof TranscriptPaymentOfferSchema>;
+
+// ---- transcript rows ----
+// What a conversation is made of, on every surface: the rows the daemon folds a turn's frames into as they
+// stream (the live chat renders these, patched as they grow), the rows the record keeps once the turn settles,
+// and the rows /agents/{id}/transcript replays into a reopened tab. One shape because it is one thing: a
+// reopened chat REDRAWS the transcript the user was looking at rather than paraphrasing it, so a row keeps the
+// assistant's thinking and the tool cards its block ran, which is also what lets a runtime handoff carry more
+// than bare prose across to a replacement session (see runtime-history.ts).
 //
-// One restored tool card. A subagent's own calls and its thinking nest under the Agent card that spawned them,
-// the same two fields (and the same recursion) the live ChatTool carries, so a reopened chat redraws the
-// delegation it was showing instead of a leaf card with the whole child collapsed into its result text.
-// z.lazy because the shape refers to itself: a subagent that delegates nests one level deeper.
-export const RestoredToolCallSchema: z.ZodType<RestoredToolCall> = z.lazy(() =>
+// One tool card. A subagent's own calls and its thinking nest under the Agent card that spawned them, so a
+// delegation reads as one unit instead of a flat run of siblings. z.lazy because the shape refers to itself: a
+// subagent that delegates nests one level deeper.
+export const TranscriptToolSchema: z.ZodType<TranscriptTool> = z.lazy(() =>
     z.object({
         id: z.string().describe("The call's id."),
         name: z.string().describe("Which tool."),
@@ -310,17 +492,40 @@ export const RestoredToolCallSchema: z.ZodType<RestoredToolCall> = z.lazy(() =>
         locations: z.array(ToolCallLocationSchema).optional().describe("The files it touched."),
         content: z.array(ToolCallContentSchema).optional().describe("What it produced: text, a change to a file, or a picture."),
         children: z
-            .array(RestoredToolCallSchema)
+            .array(TranscriptToolSchema)
             .optional()
             .describe(
                 "Calls a delegated helper made, nested under the call that started it, so a reopened conversation redraws the delegation rather than collapsing it into one result.",
             ),
         thinking: z.string().optional().describe("What the agent was reasoning about around this call."),
+        subagent: TranscriptSubagentSchema.optional().describe(
+            "The helper this call started, as the daemon's registry sees it: what it is, how it is going, what it has spent. What a card can say about a backgrounded child whose result is minutes away.",
+        ),
     }),
 );
-// Mutable, unlike most of this file: both builders settle a card IN PLACE when its result arrives turns later
-// (restoredTurn's `cards` map, readWorkspaceSession's `awaiting`), which is what saves them a second pass.
-export interface RestoredToolCall {
+/* THE CHILD A CALL STARTED, on the card whose id the `subagent`/`subagent_update` frames name (that call's own),
+ * so no correlation is needed: an Agent card wears its subagent's live state, and a Bash card that turned out
+ * to be a `codex exec` wears its delegate's. The identifying fields arrive once (the `subagent` frame), the
+ * moving ones (status, spend, what it is doing) replace as each update lands. */
+export const TranscriptSubagentSchema = z.object({
+    kind: SubagentKindSchema,
+    agentType: z.string().optional(),
+    description: z.string().optional(),
+    model: z.string().optional(),
+    provider: z.string().optional(),
+    background: z.boolean().optional(),
+    status: SubagentStatusSchema,
+    tokens: z.number().optional(),
+    toolUses: z.number().optional(),
+    lastTool: z.string().optional(),
+    summary: z.string().optional(),
+    error: z.string().optional(),
+    verification: SubagentVerificationSchema.optional(),
+});
+export type TranscriptSubagent = z.infer<typeof TranscriptSubagentSchema>;
+// Mutable, unlike most of this file: the fold settles a card IN PLACE when its result arrives turns later
+// (transcript-fold.ts's `cards` map, readWorkspaceSession's `awaiting`), which is what saves it a second pass.
+export interface TranscriptTool {
     id: string;
     name: string;
     category: ToolKind;
@@ -328,8 +533,9 @@ export interface RestoredToolCall {
     target?: string | undefined;
     locations?: ToolCallLocation[] | undefined;
     content?: ToolCallContent[] | undefined;
-    children?: RestoredToolCall[] | undefined;
+    children?: TranscriptTool[] | undefined;
     thinking?: string | undefined;
+    subagent?: TranscriptSubagent | undefined;
 }
 
 /* ONE NOTE THE DAEMON PUT IN FRONT OF A USER'S MESSAGE, as both audiences see it: the model reads `text`, and
@@ -341,15 +547,26 @@ export const TurnNoteSchema = z.object({
 });
 export type TurnNote = z.infer<typeof TurnNoteSchema>;
 
-// One restored bubble. Each stored assistant message becomes its own, which is what reproduces the live
-// interleaving, prose, the tool cards that prose introduced, then the next block of prose, rather than
-// collapsing a turn's whole narration into a single bubble with its tools hanging off the end.
-export const RestoredMessageSchema = z.object({
-    /* `notice` is neither side of the conversation: it is something that HAPPENED to the turn, recorded so a
-     * reopened session can say it. The one that matters is a refused turn, a provider that answers "your
-     * organization has disabled Claude subscription access" produced no assistant text, so a transcript of the
-     * two speakers alone ends on the user's message and the session reads as broken. It is the same muted line
-     * the live client draws for the codes it does not turn red (ChatRole's `notice`). */
+// End-of-turn accounting (assistant rows only, the last bubble of a turn): what the turn cost, attached where
+// the answer ended so a reader can see what each exchange spent.
+export const TranscriptUsageSchema = z.object({
+    costUsd: z.number().optional(),
+    inputTokens: z.number().optional(),
+    outputTokens: z.number().optional(),
+    durationMs: z.number().optional(),
+    numTurns: z.number().optional(),
+});
+export type TranscriptUsage = z.infer<typeof TranscriptUsageSchema>;
+
+// One row. Each block of the agent's prose is its own, with the tool cards that block introduced, which is what
+// reproduces the way a turn actually unfolded rather than collapsing its whole narration into one bubble with
+// every tool hanging off the end.
+export const TranscriptRowSchema = z.object({
+    /* `notice` is neither side of the conversation: it is something that HAPPENED to the turn, a refusal, a
+     * landed delta, a compaction, a stop, written down so a reopened conversation says it too. The one that
+     * matters most is a refused turn: a provider that answers "your organization has disabled Claude
+     * subscription access" produced no assistant text, so a transcript of the two speakers alone ends on the
+     * user's message and reads as broken. */
     role: z
         .enum(["user", "assistant", "notice"])
         .describe(
@@ -371,28 +588,36 @@ export const RestoredMessageSchema = z.object({
         .describe(
             "When it was sent, in milliseconds. On the user's rows only, because that is the only moment actually known: a turn's own frames arrive with no clock, so stamping the agent's rows could only ever mean the whole turn's start or end.",
         ),
-    // Files the user attached to this turn (user bubbles only) as workspace-relative paths, recovered from
-    // the stored prompt's attachment note, so a reopened tab redraws chips, not the injected protocol text.
+    // Files the user attached to this turn (user rows only) as workspace-relative paths, the uploads alone:
+    // a path @-mentioned inline in the text is already visible there and is not drawn as a chip.
     attachments: z.array(z.string()).optional().describe("Files attached to this message, as workspace paths."),
-    /* The checkpoint this message can be rewound to (user bubbles only), filled in when the transcript is read
-     * back. Not stored in the record itself, it is looked up per read from the daemon's rewind points, which
-     * a rewind rewrites, so a reopened tab offers exactly the turns that are still there to go back to. */
+    /* The checkpoint this message can be rewound to (user rows only), and where this message sits in the
+     * conversation's record, which is what the rewind route addresses it by. Never stored: both are stamped
+     * onto the live row by the turn's own `checkpoint` frame and onto a replayed row by the read that serves
+     * it, looked up from the daemon's rewind points, which a rewind rewrites, so a reopened tab offers exactly
+     * the turns that are still there to go back to. */
     checkpointId: z
         .string()
         .optional()
         .describe(
             "The saved point this message can be rewound to. Looked up on each read rather than stored, so what is offered is exactly what is still there to go back to.",
         ),
+    rewindIndex: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("This message's position in the conversation's record, which is how a rewind names it. Present only beside a checkpoint."),
     thinking: z.string().optional().describe("What the agent was reasoning about."),
-    tools: z.array(RestoredToolCallSchema).optional().describe("The tool calls this part of the turn made."),
+    tools: z.array(TranscriptToolSchema).optional().describe("The tool calls this part of the turn made."),
+    todos: z.array(TodoItemSchema).optional().describe("The agent's task checklist, as of this bubble."),
+    usage: TranscriptUsageSchema.optional().describe("What the turn cost, on the bubble its answer ended in."),
     /* What the daemon added to this turn's message (user rows only), the same notes the live `preamble` frame
-     * carries. A daemon-recorded turn takes them straight off that frame in its own log, typed end to end
-     * (sessions/turn-transcript.ts); only a conversation adopted from a provider's session store recovers them
-     * by parsing the composed prompt kept there, the one store the daemon never wrote typed.
+     * carries, read off that frame by the fold.
      *
      * On the message rather than as a row of its own, and that matters twice: they ARE part of what was
      * sent, and a record row per turn preamble would break the one-row-per-bubble correspondence a branch counts
-     * with (see the client's recordedRows, notices are drawn locally and never recorded). */
+     * with. */
     notes: z
         .array(TurnNoteSchema)
         .optional()
@@ -414,29 +639,118 @@ export const RestoredMessageSchema = z.object({
         .describe(
             "A person wrote this in the agent's voice, with no turn behind it. Marked for the human re-reading the conversation months later, so their own words do not pass as the agent's. The agent itself never sees the mark.",
         ),
-    /* THE ONE-PRESS OFFER A RECORDED NOTICE CARRIES (notice rows only), named rather than inferred from its
-     * words. Only `tierHold` today: the line saying this turn ran on a cheaper model, whose offer is "keep this
-     * chat on my pick".
-     *
-     * It is on the wire because the offer has to survive a reopen, and a reopened tab has only the record. The
-     * chat's other one-press notices are drawn live and never recorded, so they never needed this; a routed turn
-     * is different precisely because the whole point of recording it is that somebody reads it LATER. A KIND, not
-     * a callback, exactly as the live ones are: the reader decides what the press does and whether the offer
-     * still stands (a chat already holding its pick shows a settled sentence, not a stale button). */
+    /* THE ONE-PRESS OFFER A NOTICE CARRIES (notice rows only), named rather than inferred from its words: the
+     * landed notice's "keep future work on the branch", the outage notice's "stop resuming these by itself",
+     * the terminal a dependency install the daemon just started is running in, and the routed turn's "keep
+     * this chat on my pick". A KIND, not a callback: the chat decides what the press does and whether the
+     * offer still stands (a chat already holding its pick shows a settled sentence, not a stale button). */
     noticeAction: z
-        .enum(["tierHold"])
+        .enum(["landHold", "outageOptOut", "depsInstall", "tierHold"])
         .optional()
-        .describe("A one-press follow-up this recorded notice offers, by name. The chat decides what it does and whether it still applies."),
+        .describe("A one-press follow-up this notice offers, by name. The chat decides what it does and whether it still applies."),
+    /* A WAIT THIS NOTICE DESCRIBES that had not finished when it was written (notice rows only): the chat draws
+     * a spinner over it while the wait is on, and the plain line once it is over. A KIND rather than a boolean
+     * because whether the wait is STILL running is a fact about the conversation now, not about a row in a
+     * record: the reader pairs the kind with the live state that answers it. */
+    noticeWait: z.enum(["credentialRenewal"]).optional().describe("The wait this notice describes, by name, so a reader can say whether it is still on."),
+    /* THE CARD THIS BUBBLE PARKED ON (assistant rows only), at most one: a card closes the bubble it lands in,
+     * so the next thing the agent says opens a fresh row beneath it. One field per kind rather than one union
+     * field, so a reader reaches the card it draws 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."),
+    permission: TranscriptPermissionSchema.optional().describe("The tool this row asked permission for, and the decision."),
+    browserHelp: TranscriptBrowserHelpSchema.optional().describe("The browser hand-over this row asked for, and how it ended."),
+    terminalHelp: TranscriptTerminalHelpSchema.optional().describe("The terminal hand-over this row asked for, and how it ended."),
+    serviceOffer: TranscriptServiceOfferSchema.optional().describe("The priced service run this row offered, the decision, and the receipt."),
+    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."),
 });
-export type RestoredMessage = z.infer<typeof RestoredMessageSchema>;
+export type TranscriptRow = z.infer<typeof TranscriptRowSchema>;
+
+/* THE CARD FIELDS A ROW CAN CARRY, as one list, for every reader that has to ask "does this row hold a card":
+ * the fold that counts a card-only bubble as a row, the chat's row count (a branch is cut by it), and the
+ * surfaces that draw whichever card a bubble is waiting on. */
+export const CARD_FIELDS = ["plan", "question", "permission", "browserHelp", "terminalHelp", "serviceOffer", "capabilityOffer", "paymentOffer"] as const;
+export type CardField = (typeof CARD_FIELDS)[number];
+export type TranscriptCards = Pick<TranscriptRow, CardField>;
+// Whether a row holds a card at all, answered or not.
+export const holdsCard = (row: TranscriptCards): boolean => CARD_FIELDS.some((field) => row[field] !== undefined);
+// Whether a row is holding the turn open on a card nobody has answered.
+export const isAwaitingDecision = (row: TranscriptCards): boolean => CARD_FIELDS.some((field) => row[field]?.status === "pending");
+
+/* ONE CHANGE TO A RUN'S ROWS, what the attach stream carries while a turn runs. The daemon folds each frame
+ * into its rows (transcript-fold.ts) and says what moved, so a client keeps rows, never frames: it applies
+ * these to the list it holds and draws it. `index` counts from the run's first row, which the attach head
+ * places in the conversation.
+ *
+ * Prose and thinking arrive as APPENDS to a row rather than as the row again, so the chat can type them out at
+ * the pace they are written; a tool card arrives whole (`tool`, by id, replacing an earlier copy of the same
+ * id wherever it nests), because its updates are snapshots already; everything else replaces its row. `drop`
+ * is the one removal: an assistant row opened for a block that then wrote nothing. */
+export const TranscriptPatchSchema = z.discriminatedUnion("op", [
+    z.object({ op: z.literal("append").describe("A new row at the end."), row: TranscriptRowSchema }),
+    z.object({ op: z.literal("replace").describe("This row, whole, in place of the one at that index."), index: z.number().int().nonnegative(), row: TranscriptRowSchema }),
+    z.object({ op: z.literal("drop").describe("The row at that index is gone: it was opened and never written into."), index: z.number().int().nonnegative() }),
+    z.object({ op: z.literal("text").describe("More of the agent's prose, onto that row's text."), index: z.number().int().nonnegative(), text: z.string() }),
+    z.object({ op: z.literal("thinking").describe("More of the agent's reasoning, onto that row's thinking."), index: z.number().int().nonnegative(), text: z.string() }),
+    z.object({
+        op: z.literal("tool").describe("A tool card, whole: new, or the latest state of one already there, matched by id wherever it nests."),
+        index: z.number().int().nonnegative(),
+        tool: TranscriptToolSchema,
+        parent: z.string().optional().describe("The card this one nests under, when it is a delegated helper's own call."),
+    }),
+]);
+export type TranscriptPatch = z.infer<typeof TranscriptPatchSchema>;
 
 export const SessionTranscriptSchema = z.object({
     messages: z
-        .array(RestoredMessageSchema)
+        .array(TranscriptRowSchema)
         .describe(
             "The conversation, in order. Each block of the agent's prose is its own message with the tools that block introduced, which is what reproduces the way it actually unfolded.",
         ),
 });
+/* HOW A TURN THAT LEFT WORK BEHIND ENDED, as the daemon has it, for whoever asks and however long after.
+ *
+ * One shape for every ending that leaves finished work behind a live session, because they are one situation
+ * with one answer (a press) and they differ only in what can honestly be said about WHEN and what the press
+ * DOES. The client folds this straight into its pick-up state (chat/pickUp.ts), which is why the field names
+ * line up: a second vocabulary between the two halves is how they came to disagree in the first place.
+ *
+ * IT USED TO BE A BOOLEAN, and the boolean is what left the longest wait uncovered. One flag could only say
+ * "a Stop, or a daemon killed under it", so a spent allowance, the one ending that reliably OUTLIVES the
+ * window that hit it, reached a reopened tab as nothing at all: no strip, no countdown, no press, and the user
+ * typing the word by hand hours later. It could not say more without these three facts, and each of them
+ * changes what the surface may promise:
+ *
+ *   · `resetsAt` is the only honest "not before this" any ending knows, and it is the whole of what a chat
+ *     reopened the next morning wants to be told;
+ *   · `held` is what makes the press cheap. The daemon keeps the refused turn whole, so continuing RE-RUNS it
+ *     and adds nothing to the conversation; without this the same press appends a message reading "Continue",
+ *     which is exactly the transcript pollution the press exists to prevent, and `ran` separates a turn that
+ *     got somewhere from one the allowance refused at the door (two different sentences);
+ *   · `scheduled` says somebody else is already bringing this turn back, so the surface REPORTS a wait instead
+ *     of offering one, and no local automation races the daemon's own pass for it. */
+export const TurnEndingSchema = z.object({
+    reason: z
+        .enum(["stopped", "limit", "outage"])
+        .describe(
+            "Which ending left the work here: a Stop or a daemon killed under the turn, a spent usage allowance, or a provider that refused it.",
+        ),
+    resetsAt: z
+        .number()
+        .optional()
+        .describe("When the spent allowance reopens, in epoch seconds. Absent for every ending that names no instant, and for a provider that publishes none."),
+    held: z
+        .object({ ran: z.boolean().describe("Whether the held turn got anywhere before it was refused, which is a different sentence from one refused at the door.") })
+        .optional()
+        .describe("Present when the daemon still holds the refused turn whole, so a press re-runs it rather than appending a message after it."),
+    scheduled: z
+        .boolean()
+        .optional()
+        .describe("Whether something other than the user is already booked to send this turn again, so the surface reports the wait instead of offering a press."),
+});
+export type TurnEnding = z.infer<typeof TurnEndingSchema>;
+
 /* THE RECORD A REOPENED TAB IS REBUILT FROM: the messages, plus what the session behind them is BOUND to.
  *
  * A provider session is minted on one runtime under one credential, and it resumes only there, so a client
@@ -446,7 +760,7 @@ export const SessionTranscriptSchema = z.object({
  * is what made switching BACK to the account that minted it announce a fresh session and then retire a
  * perfectly resumable one, spending the whole transcript again on a cold prompt cache.
  *
- * All optional, and absent together on a conversation that has no session to resume. */
+ * The session fields are all optional, and absent together on a conversation that has no session to resume. */
 export const AgentTranscriptSchema = SessionTranscriptSchema.extend({
     sessionId: z.string().optional().describe("The provider session behind the last turn, when there is one."),
     provider: AgentProviderSchema.optional().describe("Which provider minted that session."),
@@ -455,6 +769,19 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({
         .string()
         .optional()
         .describe("Which stored account it belongs to, as the daemon resolved it. Absent when no stored account paid for the turn."),
+    /* AND HOW THE LAST TURN ENDED, for the endings that leave the client something to OFFER rather than
+     * something to draw: work half done behind a session that is perfectly alive, where the only thing missing
+     * is somebody saying carry on.
+     *
+     * It rides the transcript because the offer used to ride the WINDOW. A chat armed the continue press from
+     * the stream it was watching when the turn stopped, so the press existed only where somebody had been
+     * looking: stop an agent from the board with its chat closed, or reopen the tab on another device, or after
+     * a reload that dropped the tab, and the same stopped session came back with no way on but typing the word
+     * by hand, which is precisely what the press exists to spare. The daemon is the one party that knows this
+     * about a conversation whoever asks and however long after, so it is the one that says it. */
+    ending: TurnEndingSchema.optional().describe(
+        "How the last turn ended, when it left work behind that one press finishes. Absent for a conversation whose last turn ended on its own, and for the failures that name something to repair first.",
+    ),
 });
 
 /* WHAT A PUBLISHED CONVERSATION'S PAGE IS HANDED, the whole of it, baked into the page as one JSON block.
@@ -464,7 +791,7 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({
  * it, which also settles the security question by construction, a page with nothing to ask has no way to ask
  * for something it was not given.
  *
- * The messages are the SAME RestoredMessage rows the app replays a reopened tab from, already filtered to the
+ * The messages are the SAME TranscriptRow rows the app replays a reopened tab from, already filtered to the
  * chosen detail level and with every picture path rewritten to the copy published beside the page. That
  * sameness is the point: the shared page renders them with the app's own components, so what a recipient sees
  * is what the owner saw. */
@@ -473,68 +800,16 @@ export const SharePayloadSchema = z.object({
     // When the snapshot was taken, not when the conversation happened, see SharedConversation.sharedAt.
     sharedAt: z.number(),
     detail: ShareDetailSchema,
-    messages: z.array(RestoredMessageSchema),
+    messages: z.array(TranscriptRowSchema),
 });
 export type SharePayload = z.infer<typeof SharePayloadSchema>;
 
-/* WHAT A PARKED CARD IS ABOUT: the document the turn wrote and is now asking a question against.
- *
- * A card asks for a decision; until this it carried no SUBJECT. The commonest shape of a real decision is "I
- * analysed this and wrote it up, now choose", and the write-up went into a file whose card had already folded
- * itself into `Write · +135 −0` twenty tool calls back. So the reader was asked to choose between options
- * describing a document the chat had never shown them.
- *
- * Carried BY VALUE rather than as a path, for the same reason the diff on a tool call is: the bytes are already
- * in hand when the card is raised, a path would make the card's meaning depend on a file that keeps changing
- * under it, and a restored or published transcript has no workspace to go read. The path rides along anyway, so
- * a document past the wire cap still has somewhere to send the reader.
- *
- * Nothing is asked of the MODEL for this. It calls `ask` exactly as before; the daemon knows what the turn
- * wrote, because every write came past it as a frame (documents.ts decides which of them is a document). A
- * harness that can see the answer must not spend prompt on asking the model to repeat it. */
-export const CardDocumentSchema = z.object({
-    path: z.string().describe("Where it lives, as a workspace path."),
-    title: z.string().describe("What it is called: its opening heading, or its file name."),
-    markdown: z.string().describe("The document itself."),
-    truncated: z.boolean().optional().describe("It was clipped at the wire cap; the file on disk has more."),
-    plan: z.boolean().optional().describe("It is one of the CLI's plan files, written to be approved rather than merely read."),
-});
-export type CardDocument = z.infer<typeof CardDocumentSchema>;
-
-/* THE THREE RESTORABLE CARDS, named so the turn journal can hold them verbatim: a parked turn's raised cards
- * are written down beside its prompt (sandbox turn-journal.ts), and a daemon death under the park restores the
- * very same frames instead of ending the turn `interrupted`, the card the user was about to answer survives
- * the restart that killed the process holding it. The two handover cards are deliberately not among them:
- * `browser_help`'s Chromium and `terminal_help`'s waiting command both die with the container, so those parks
- * cannot be restored, only reported. */
-const PlanCardSchema = z.object({
-    kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
-    requestId: z.string().describe("What to send back when you answer."),
-    text: z.string().describe("The plan itself."),
-    // Present when the adjacent plan prose POINTS at a document instead of being one: the model wrote the real
-    // plan to a file and summarised it there. Absent when the text already is the whole plan.
-    document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
-});
-const QuestionCardSchema = z.object({
-    kind: z.literal("question").describe("The agent has asked you something and is waiting."),
-    requestId: z.string().describe("What to send back when you answer."),
-    questions: z.array(AskQuestionSchema).describe("What it wants to know."),
-    document: CardDocumentSchema.optional().describe("The document this turn wrote and is asking about, so the choice can be read beside it."),
-});
-const PermissionCardSchema = PermissionAskSchema.extend({
-    kind: z.literal("permission").describe("The agent wants to use a tool it needs permission for."),
-    requestId: z.string().describe("What to send back when you answer."),
-});
-export const ParkedCardSchema = z.discriminatedUnion("kind", [PlanCardSchema, QuestionCardSchema, PermissionCardSchema]);
-export type ParkedCard = z.infer<typeof ParkedCardSchema>;
-
 // One frame from an agent turn, relayed to the UI. `kind`-discriminated. The daemon normalizes the SDK's
 // ~40 SDKMessage types down to this union: high-value block types get a dedicated frame
 // (delta/thinking/tool_call/tool_call_update/todos/usage/rate_limit_info/account_usage/context_usage/init/compact); any SDK message
 // without a UI mapping is dropped. `plan`/`question`/`permission` pause the turn until the user answers on the
-// `POST /agent/reply` side channel, and `resolved` releases the one it names; `permission_note` adds a sentence
-// to a permission card already on screen without settling it; `mode` reports the live permission posture as the
-// agent changes it.
+// `POST /agent/reply` side channel, and `resolved` releases the one it names; `mode` reports the live
+// permission posture as the agent changes it.
 // `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
 // subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
@@ -843,35 +1118,18 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     PlanCardSchema,
     QuestionCardSchema,
     PermissionCardSchema,
-    // The agent's browser needs a person: it parked mid-sign-in on something it cannot clear itself (a captcha,
-    // a password it does not hold, a phone check). `session` names the browser session on /browsers, the card's
-    // one action is going THERE, where the live stage and Take control already are; the Browsers banner and this
-    // card resolve the same requestId. `account` is the capability the sign-in is for, so the card can say whose
-    // login is stuck even after the browser has navigated somewhere unrecognizable.
-    z.object({
-        kind: z.literal("browser_help"),
-        requestId: z.string(),
-        session: z.string(),
-        account: z.string(),
-        message: z.string(),
-    }),
-    // The agent's TERMINAL needs a person: a command it started is sitting at a prompt it cannot answer (a
-    // one-time password, a security-key touch, a confirm). `session` names the tmux session on the terminal
-    // panel, the card's one action is going THERE, where the live pane and its prompt already are, which is
-    // the same division of labour the browser card has with /browsers. Not journalled for restore, and for the
+    // The agent's browser needs a person (see browserHelpCard for what the card carries). Not journalled for
+    // restore: the Chromium holding the page dies with the container.
+    z.object({ kind: z.literal("browser_help"), ...browserHelpCard }),
+    // The agent's TERMINAL needs a person (see terminalHelpCard). Not journalled for restore, and for the
     // browser card's reason one door along: the pane holding the prompt belongs to a process the restart kills.
-    z.object({
-        kind: z.literal("terminal_help"),
-        requestId: z.string(),
-        session: z.string(),
-        message: z.string(),
-    }),
+    z.object({ kind: z.literal("terminal_help"), ...terminalHelpCard }),
     /* A premium service run awaiting the owner's click. Raised OUTSIDE the turn generator, the daemon's
      * services route parks the agent's own `services run` call and pushes this frame into the live run
      * (platform/service-offer.ts), so unlike the four cards above it is not journalled for restore: its
      * waiter is the CLI's held connection, which dies with the daemon, and a restored card would offer
      * buttons nothing is waiting behind. Settles through the same `POST /agent/reply` as every other card. */
-    z.object({ kind: z.literal("service_offer"), requestId: z.string(), offer: ServiceOfferSchema }),
+    z.object({ kind: z.literal("service_offer"), ...serviceOfferCard }),
     /* One event off an approved run's stream, pushed as the provider emits it so the settled card shows the
      * run living rather than a spinner of unknowable length. Today that is `status` lines; `result` stays off
      * the transcript on purpose (it is the agent's answer to act on, not the card's to duplicate), the frame
@@ -881,49 +1139,31 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * rather than a promise: `ok` served and charged, `refunded` failed to answer and charged nothing,
      * `refused` the platform said no after the click (a raced-out allowance). `remaining` is the meter after,
      * when the platform stated one. Skip needs no receipt, nothing happened, and `resolved` already says so. */
-    z.object({
-        kind: z.literal("service_receipt"),
-        requestId: z.string(),
-        outcome: z.enum(["ok", "refunded", "refused"]),
-        credits: z.number(),
-        remaining: z.number().optional(),
-    }),
+    ServiceReceiptSchema.extend({ kind: z.literal("service_receipt"), requestId: z.string() }),
     /* A missing capability asking for the owner's setup, the agent hit something this sandbox is not
      * connected to and raised the card instead of describing manual steps. Raised OUTSIDE the turn generator
      * exactly like the service offer above (the daemon's ask route parks the agent's `capabilities request`
      * call and pushes this frame into the live run; capabilities/capability-offer.ts), so it is not
      * journalled for restore either: its waiter is the CLI's held connection, which dies with the daemon.
      * Settles through the same `POST /agent/reply` as every other card. */
-    z.object({ kind: z.literal("capability_offer"), requestId: z.string(), offer: CapabilityOfferSchema }),
+    z.object({ kind: z.literal("capability_offer"), ...capabilityOfferCard }),
     /* How an accepted ask ended, pushed once the daemon stops watching for the connection: `connected`, the
      * capability came live while the agent waited (`id` is the connected instance, the agent's handle for it)
      *, or `unfinished`, the setup did not complete while anyone was waiting (the deadline passed, or the
      * asking command died). A skip needs no outcome frame, nothing was set up, and `resolved` already says
      * so. It is what settles the card's "waiting for you to finish setup" state on every surface. */
-    z.object({
-        kind: z.literal("capability_outcome"),
-        requestId: z.string(),
-        outcome: z.enum(["connected", "unfinished"]),
-        id: z.string().optional(),
-    }),
+    CapabilityOutcomeSchema.extend({ kind: z.literal("capability_outcome"), requestId: z.string() }),
     /* A USDC payment awaiting the owner's click. Raised OUTSIDE the turn generator exactly like the service
      * offer above (the daemon's wallet route parks the agent's `wallet fetch` call and pushes this frame into
      * the live run; wallet/payment-offer.ts), so it is not journalled for restore either: its waiter is the
      * CLI's held connection, which dies with the daemon. Settles through the same `POST /agent/reply`. */
-    z.object({ kind: z.literal("payment_offer"), requestId: z.string(), offer: PaymentOfferSchema }),
+    z.object({ kind: z.literal("payment_offer"), ...paymentOfferCard }),
     /* How an approved (or auto-approved) payment ended, pushed after the endpoint answered so the card can
      * settle as a receipt rather than a promise: `paid`, the endpoint confirmed settlement (`transaction` is
      * the onchain hash when it stated one); `failed`, the payment was refused or settlement failed, in which
      * case the signed authorization expires unused and NOTHING left the wallet. A skip needs no receipt,
      * nothing moved, and `resolved` already says so. */
-    z.object({
-        kind: z.literal("payment_receipt"),
-        requestId: z.string(),
-        outcome: z.enum(["paid", "failed"]),
-        amountUsd: z.string(),
-        transaction: z.string().optional(),
-        network: z.string().optional(),
-    }),
+    PaymentReceiptSchema.extend({ kind: z.literal("payment_receipt"), requestId: z.string() }),
     // The card above named by `requestId` is released, the user answered (or dismissed it, or the turn was
     // stopped out from under it), so the turn is executing again. Emitted by whoever parked, the moment its
     // waiter settles, because the park's END is otherwise invisible on this stream: nothing else here says
@@ -939,19 +1179,12 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // already moved on. It rides verbatim, exactly as the client POSTed it; absent, nobody answered (the turn
     // was stopped, or died under the card), which is not a decision and must not replay as one.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
-    /* A LATE SENTENCE FOR A CARD ALREADY ON SCREEN: the quick model's plain-language reading of a held command,
-     * landing on the permission card named by `requestId` (see PermissionAsk.explain).
-     *
-     * A frame of its own rather than a field on the card, because the card MUST NOT WAIT FOR IT. This is a
-     * safety prompt and the turn is parked on it; a quick-model rung can take tens of seconds before the chain
-     * steps down (agent/quick-model.ts measured one at 58), and holding the card back for that reads exactly
-     * like the agent freezing, which is the failure the explanation was meant to prevent rather than cause. So
-     * the card goes out complete and unexplained, and this arrives if and when it does. Same shape and the same
-     * reason as `service_event`, which streams a running service's status onto an offer already rendered.
-     *
-     * Never arrives at all when the setting is off, when nothing is connected to answer, or when the user
-     * settles the card first, and none of those change what the card says. */
-    z.object({ kind: z.literal("permission_note"), requestId: z.string(), explain: z.string() }),
+    /* There was a `permission_note` frame here: a late sentence raced onto a command card that had already gone
+     * out, because the explanation was optional and the card must not wait for a quick-model rung that might
+     * take tens of seconds. It is gone with the setting that made it optional. The judge now decides the
+     * verdict, so the sentence is not a decoration arriving afterwards — it is the REASON THE CARD EXISTS, and
+     * a card cannot be raised before it is known. Nothing races, and `PermissionAsk.explain` is populated at
+     * raise time (guard/command-gate.ts). */
     // The turn's permission mode, whenever it changes, the user's pick at turn start, then every move the
     // AGENT makes on its own (EnterPlanMode on a request that needs thinking through, ExitPlanMode once the
     // user approves). The composer's mode selector follows this, so the UI never lies about the live posture.
@@ -1077,23 +1310,34 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         // rate_limit_event or the account's persisted usage windows). Absent when the reset instant is unknown
         // (nothing to schedule against).
         resetsAt: z.number().optional(),
-        // Where the daemon's resume of THIS turn stands, for the two codes that have one (provider-outage,
-        // claude-token-refused). "scheduled" = the resume is armed and this turn comes back by itself;
-        // "available" = the daemon remembered the failed turn and arming THIS conversation
-        // (AgentSummarySchema.resumeAfterOutage) picks up that same resume, which is what the chat's offer
-        // banner hangs off, outage only, since a renewal is never gated on a posture at all. The two words
-        // are read against the effective posture (the conversation's override, else the sandbox default), so a
-        // chat armed on its own says "scheduled" while the unarmed board around it says "available".
-        // Absent means there is nothing automatic to resume: a spent usage limit never has one,
-        // and a refused credential has none once re-minting it has already been tried and failed.
+        /* Where the daemon's resume of THIS turn stands, for the three codes that have one (provider-outage,
+         * claude-token-refused, rate_limit). "scheduled" = the resume is armed and this turn comes back by
+         * itself; "available" = the daemon remembered the failed turn and arming THIS conversation
+         * (AgentSummarySchema's resumeAfterOutage / resumeAfterLimit) picks up that same resume, which is what
+         * the offer banner hangs off, gated codes only, since a credential renewal is never gated on a posture
+         * at all. The two words are read against the effective posture (the conversation's override, else the
+         * sandbox default), so a chat armed on its own says "scheduled" while the unarmed board around it says
+         * "available". Absent means there is nothing automatic to resume: a limit whose reset instant nobody
+         * published has nothing to schedule against, and a refused credential has none once re-minting it has
+         * already been tried and failed.
+         *
+         * A SPENT ALLOWANCE USED TO BE ABSENT HERE BY RULE, and the rule was right about the default and wrong
+         * about the ceiling. The budget is the user's, so nothing fires unless they said so, which is what the
+         * posture is; what the old absence also cost was the case a press cannot reach, a 2am wall on a board
+         * nobody is watching. Both words are now honest for it: unarmed says "available", which is an offer,
+         * and armed says "scheduled", which the card counts down to. */
         autoResume: z.enum(["scheduled", "available"]).optional(),
         /* THE DAEMON IS STILL HOLDING THIS EXACT TURN, so the way on is to RE-RUN it rather than to send
          * something after it. rate_limit only, and the counterpart to `autoResume` rather than a member of it:
-         * that field answers "is a machine bringing this back", and a spent allowance is the one failure where
-         * the answer is deliberately no (the allowance is the user's own budget to spend, turn-resume.ts). This
+         * that field answers "is a machine bringing this back", which for a spent allowance is a posture the
+         * user sets and defaults to no (the allowance is their own budget to spend, turn-resume.ts). This
          * answers the question that was never asked, "and if the user says go, what happens", which had exactly
          * one possible answer for as long as it went unasked: a new user message reading "Continue".
          *
+         * BOTH ANSWERS RUN THROUGH THIS FIELD, which is why it is not folded into the one above: an armed
+         * conversation's scheduled fire and an unarmed one's press are the same held turn re-run the same way,
+         * and the only difference is who says go.
+         *
          * That answer was wrong in a way the chat could not show. The press is not a new instruction, it is the
          * same one again, and appending it said otherwise to the only reader that matters: the provider session
          * grew one "Continue" per press, each with a synthetic "No response requested." above it, so a chat that
@@ -1120,34 +1364,73 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
 ]);
 export type AgentEvent = z.infer<typeof AgentEventSchema>;
 
-// The /agent/attach stream: a head frame identifying the run, then its AgentEvents stamped with their 1-based
-// seq (the client's resume cursor), then `end` when the run is over, every frame delivered, nothing more
-// coming. A stream that closes WITHOUT `end` was dropped mid-run; the client re-attaches with `after` = the
-// last seq it holds. The head's `prompt`/`startedAt` let a window that didn't initiate the turn (a reload, a
-// second window, another device) synthesize the user bubble and the elapsed readout; its `seq` is the log
-// length at attach time, the replay/live boundary.
+/* THE FRAMES THAT ARE FACTS ABOUT THE TURN rather than words in it: which session it runs, where it stands,
+ * what it costs, how it failed. Everything else an AgentEvent can say is transcript, and reaches a client as
+ * rows and patches (TranscriptPatchSchema) after the daemon has folded it; these reach it as themselves,
+ * because there is nothing to fold, a client keeps them as state beside the transcript. A frame can be both,
+ * a `worktree` that rebased writes a notice AND says where the branch is, so the two lists overlap, and the
+ * fold and this list each take the half that is theirs. */
+export const TURN_FACT_KINDS = [
+    "session",
+    "worktree",
+    "init",
+    "terminal",
+    "browser",
+    "commands",
+    "usage",
+    "rate_limit_info",
+    "fast_mode",
+    "tier",
+    "provider_retry",
+    "account_usage",
+    "context_usage",
+    "mode",
+    "error",
+] as const;
+export type TurnFact = Extract<AgentEvent, { kind: (typeof TURN_FACT_KINDS)[number] }>;
+export const isTurnFact = (event: AgentEvent): event is TurnFact => (TURN_FACT_KINDS as readonly string[]).includes(event.kind);
+// The same members AgentEventSchema declares, picked out rather than declared twice: a fact's shape is the
+// frame's shape, and a second spelling of it would be the drift the list above exists to prevent.
+type AgentEventMember = (typeof AgentEventSchema.options)[number];
+const factMembers = AgentEventSchema.options.filter((member) => (TURN_FACT_KINDS as readonly string[]).includes(member.shape.kind.value)) as unknown as [
+    AgentEventMember,
+    ...AgentEventMember[],
+];
+export const TurnFactSchema = z.discriminatedUnion("kind", factMembers) as unknown as z.ZodType<TurnFact>;
+
+/* The /agent/attach stream: a head carrying the run's rows so far, then every change to them and every fact
+ * about the turn as each lands, then `end` when the run is over, nothing more coming. A stream that closes
+ * WITHOUT `end` was dropped mid-run; the client re-attaches and takes the head's rows again, whole, which is
+ * what makes attaching idempotent: a window never re-folds what it has already drawn, it replaces it.
+ *
+ * Facts REPLAY on every attach (their seq is at or below the head's), because a window joining late still has
+ * to learn which session the turn runs and where its branch stands; patches are only ever live (their seq is
+ * above the head's), because the head already holds their result. */
 export const AttachFrameSchema = z.discriminatedUnion("kind", [
     z.object({
-        kind: z.literal("attached").describe("The first frame, identifying the run you have joined."),
+        kind: z.literal("attached").describe("The first frame, identifying the run you have joined and handing you its transcript so far."),
         run: z.string().describe("The run's id."),
-        prompt: z.string().describe("What was said to start it, so a window that did not start the turn can still draw the message."),
         startedAt: z.number().describe("When it started, in milliseconds, so a window joining late can show how long it has been going."),
-        seq: z.number().describe("How many frames already exist. Everything at or below this number is replay; everything above it is live."),
+        seq: z.number().describe("How many frames the run has produced so far. A fact at or below this number is being replayed; a patch is never."),
+        rows: z
+            .array(TranscriptRowSchema)
+            .describe("The turn's rows as they stand: what was asked, and everything the agent has said and done since. Draw these, then apply the patches that follow."),
     }),
     z.object({
-        kind: z.literal("frame").describe("One thing that happened."),
-        seq: z
-            .number()
-            .describe("Its position in the run, counting from one. Keep the last one you saw and hand it back to resume rather than replay."),
-        event: AgentEventSchema.describe(
-            "What happened, as one of about forty shapes: the agent's words arriving piece by piece, a tool being called and answering, a plan or a question it is waiting on, a mode change, the turn's cost. Each carries its own `kind`.",
-        ),
+        kind: z.literal("patch").describe("One change to the run's rows."),
+        seq: z.number().describe("Its position in the run, counting from one."),
+        patch: TranscriptPatchSchema,
+    }),
+    z.object({
+        kind: z.literal("fact").describe("One thing about the turn that is not a row: its session, its branch, its cost, a failure."),
+        seq: z.number().describe("Its position in the run, counting from one. At or below the head's number, it is being replayed."),
+        fact: TurnFactSchema,
     }),
     z.object({
         kind: z
             .literal("end")
             .describe(
-                "The run is over and every frame has been delivered. A stream that closes without this was dropped mid-run, so re-attach with the last position you hold rather than assuming the turn finished.",
+                "The run is over and every frame has been delivered. A stream that closes without this was dropped mid-run, so re-attach rather than assuming the turn finished.",
             ),
     }),
 ]);
@@ -1427,9 +1710,34 @@ export type Presence = z.infer<typeof PresenceSchema>;
 export const AgentsSchema = z.object({ kind: z.literal("agents"), agents: z.array(AgentSummarySchema), rev: z.number() });
 export type Agents = z.infer<typeof AgentsSchema>;
 
+/* AN ACCOUNT'S HEADROOM JUST MOVED, the reading itself, keyed the way the daemon's store keys it (a Claude
+ * account id, or `${provider}:${authFile}` for a routed subscription).
+ *
+ * The fifth push, and the one that lets every ring, rail and picker row stop refetching on mount. A reading
+ * lands on the daemon for one of four reasons, a turn settled, a plan refused, a screen asked, a provider
+ * pushed, and until this frame existed only the window that caused it ever heard: every other window drew the
+ * number it had loaded that morning until something in it happened to remount. Snapshot-not-diff per account,
+ * last frame wins, and a browser that missed one simply holds the older reading, which is what `measuredAt`
+ * is for. `usage` absent ⇒ the account's snapshot was cleared (it was disconnected). */
+export const AccountUsageChangedSchema = z.object({
+    kind: z.literal("accountUsage"),
+    // The provider whose row this account is, because the key alone does not say (a native id is bare).
+    provider: z.string(),
+    account: z.string(),
+    usage: AccountUsageSchema.optional(),
+});
+export type AccountUsageChanged = z.infer<typeof AccountUsageChangedSchema>;
+
+// A provider's last refusal was recorded or settled. The observed half of "can I run on this" (see
+// ProviderRefusalSchema), pushed for the same reason the reading above is: a refusal at 4am used to reach a
+// window only when it next reloaded its account rows. `refusal` absent ⇒ settled, nothing stands.
+export const ProviderRefusalChangedSchema = z.object({ kind: z.literal("providerRefusal"), provider: z.string(), refusal: ProviderRefusalSchema.optional() });
+export type ProviderRefusalChanged = z.infer<typeof ProviderRefusalChangedSchema>;
+
 // The /events stream union: the hello identity frame, then liveness heartbeats interleaved with boot progress,
-// workspace-change batches, repo-set snapshots, ref-move batches, runtime-domain nudges, and presence + fleet
-// roster snapshots. oRPC validates every yielded frame against this, so all kinds must live here.
+// workspace-change batches, repo-set snapshots, ref-move batches, runtime-domain nudges, presence + fleet
+// roster snapshots, and account headroom / refusal changes. oRPC validates every yielded frame against this,
+// so all kinds must live here.
 export const SystemEventSchema = z.discriminatedUnion("kind", [
     HelloSchema,
     HeartbeatSchema,
@@ -1440,5 +1748,7 @@ export const SystemEventSchema = z.discriminatedUnion("kind", [
     RuntimeChangedSchema,
     PresenceSchema,
     AgentsSchema,
+    AccountUsageChangedSchema,
+    ProviderRefusalChangedSchema,
 ]);
 export type SystemEvent = z.infer<typeof SystemEventSchema>;