@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/events.ts

@@ -3,9 +3,12 @@ import {
     AgentProviderSchema,
     AgentReplySchema,
     AgentSummarySchema,
+    FastModeStateSchema,
     LandConflictSchema,
+    MemberRoleSchema,
     PermissionModeSchema,
     RateLimitInfoSchema,
+    ShareDetailSchema,
     SubagentKindSchema,
     SubagentStatusSchema,
     UsageWindowSchema,
@@ -51,6 +54,66 @@ export const PermissionAskSchema = z.object({
 });
 export type PermissionAsk = z.infer<typeof PermissionAskSchema>;
 
+/* ONE PRICED SERVICE RUN, OFFERED — the card the daemon raises when the agent asks to run a premium service
+ * (platform/service-offer.ts). Everything with a number on it is the PLATFORM's answer, relayed verbatim from
+ * the catalog it serves the daemon: the model that asked contributes `request` (the JSON it wants sent) and
+ * `why` (its one line of rationale), and nothing else — which is what makes the price on the card impossible
+ * to misquote, and the click on it the only way the run can happen. */
+export const ServiceOfferSchema = z.object({
+    // The service, as the platform lists it: `<slug>` is what the run names, the rest is the catalog row.
+    slug: z.string(),
+    name: z.string(),
+    publisher: z.string(),
+    description: z.string(),
+    creditsPerRun: z.number(),
+    // The owner's meter as the platform stated it with the catalog — what "N left today" renders from. Absent
+    // when the platform sent none (it answers a meter only to a member, and membership was already checked
+    // before this card went up, so in practice it is present; the field stays honest about the wire).
+    credits: z.object({ allowance: z.number(), remaining: z.number(), resetsAt: z.string() }).optional(),
+    // The request body the agent wants forwarded, verbatim — shown so the owner can see what leaves.
+    request: z.string(),
+    // The agent's one-line case for spending — the only prose on the card that is the model's.
+    why: z.string().optional(),
+});
+export type ServiceOffer = z.infer<typeof ServiceOfferSchema>;
+
+/* WHAT A SERVICE STREAMS — the provider's event vocabulary, stated once here and imported by everyone who
+ * touches it: the platform validates each line of a provider's NDJSON against this before relaying it, the
+ * daemon turns `status` events into transcript frames, and the editor renders them under the offer card.
+ * A run is `status` lines (each replaces the last — a spinner label, not a log) ending in exactly one
+ * `result`, whose `data` is the answer the agent acts on. The union is where future event kinds land when
+ * services start streaming richer transcript elements; today's two are the smallest honest set. */
+export const ServiceStreamEventSchema = z.discriminatedUnion(`event`, [
+    z.object({ event: z.literal(`status`), text: z.string() }),
+    z.object({ event: z.literal(`result`), data: z.unknown() }),
+]);
+export type ServiceStreamEvent = z.infer<typeof ServiceStreamEventSchema>;
+
+/* ONE MISSING CAPABILITY, ASKED FOR — the card the daemon raises when the agent hits something this sandbox
+ * is not connected to (capabilities/capability-offer.ts). `card` names the catalog card and `name` is that
+ * card's own title, both resolved by the daemon from the catalog it validates the ask against — the model
+ * that asked contributes `why` (its one line of rationale) and nothing else, which is what makes the card
+ * impossible to misrepresent, and the click on it the only way anything gets connected. */
+export const CapabilityOfferSchema = z.object({
+    // The catalog card being asked for, and how the catalog itself titles it ("Notion", "GitHub", "Docker").
+    card: z.string(),
+    name: z.string(),
+    // The agent's one-line case for connecting it — the only prose on the card that is the model's.
+    why: z.string().optional(),
+});
+export type CapabilityOffer = z.infer<typeof CapabilityOfferSchema>;
+
+/* The trailer the PLATFORM appends to every relayed run stream — never provider-authored: it is the ledger
+ * speaking after the stream settled. `ok` means the run served and was charged (`remaining` is the meter
+ * after); `refunded` means the provider's stream died before its `result` and the charge was reversed. */
+export const ServiceRunReceiptSchema = z.object({
+    event: z.literal(`receipt`),
+    outcome: z.enum([`ok`, `refunded`]),
+    credits: z.number(),
+    remaining: z.number().optional(),
+});
+export type ServiceRunReceipt = z.infer<typeof ServiceRunReceiptSchema>;
+
 // One provider-advertised slash command — an ACP agent's available_commands entry, or a Claude Code session's
 // supportedCommands() (its built-ins plus the workspace's own .claude/commands and any plugin/skill commands).
 // `hint` is the argument placeholder the popover shows after the name.
@@ -101,12 +164,12 @@ export type ToolCallLocation = z.infer<typeof ToolCallLocationSchema>;
 // tools (old_string/new_string) and whole-file for Write; an absent oldText means a new file / unknown
 // previous content. Sides are capped daemon-side; `truncated` marks a clipped side.
 //
-// `image` is a PICTURE THE TOOL PRODUCED, carried as a workspace path rather than as bytes: a browser
-// screenshot is already on disk under .intentic/browser/output (the artifact hook put it there), so the client
-// fetches it from /workspace/raw like any other file. Base64 on the wire would push a third of a megabyte
-// through the event stream and into the stored transcript for every screenshot, to show something the
-// workspace can already serve — and the path is what keeps the picture openable afterwards, which the inlined
-// bytes would not be. Root-relative, forward-slash: the same route space as ToolCallLocation.
+// `image` is a PICTURE THE TOOL PRODUCED, carried as a workspace path rather than as bytes. Browser screenshots
+// already live under .intentic/artifacts/browser, and provider-generated images are copied into
+// .intentic/artifacts/imagegen, so the client fetches either from /workspace/raw like any other file. Base64 on
+// the wire would bloat the event stream and every stored transcript to show bytes the workspace already serves;
+// the path also keeps the picture openable afterwards. Root-relative, forward-slash: the same route space as
+// ToolCallLocation.
 export const ToolCallContentSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("text"), text: z.string() }),
     z.object({
@@ -121,9 +184,10 @@ export const ToolCallContentSchema = z.discriminatedUnion("type", [
 export type ToolCallContent = z.infer<typeof ToolCallContentSchema>;
 
 // ---- restored transcripts ----
-// What /sessions/{id} replays into a reopened tab. Deliberately NOT SessionTranscriptMessage (the {role,text}
-// seed a resumed turn carries as prompt context): this one has to REDRAW the transcript the user was looking
-// at, so it keeps the assistant's thinking and the tool cards its turn ran. Reconstructed from the stored
+// 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.
 //
@@ -158,23 +222,98 @@ export interface RestoredToolCall {
     thinking?: string | undefined;
 }
 
+/* ONE NOTE THE DAEMON PUT IN FRONT OF A USER'S MESSAGE, as both audiences see it: the model reads `text`, and
+ * the chat draws `title` on a collapsed row that opens to that same `text`. Shared by the live frame and the
+ * restored transcript so a note reads identically whether the tab watched it arrive or reopened an hour later. */
+export const TurnNoteSchema = z.object({ title: z.string(), text: z.string() });
+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({
-    role: z.enum(["user", "assistant"]),
+    /* `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`). */
+    role: z.enum(["user", "assistant", "notice"]),
     text: z.string(),
+    /* WHEN THIS TURN WAS SENT, in epoch milliseconds (user rows only) — what the chat shows on the bubble it
+     * belongs to. The turn's START, not the moment the record was written: a turn that ran for twenty minutes
+     * was still sent when the user pressed send, and a stamp taken at settlement would say the conversation
+     * happened at the times its answers finished.
+     *
+     * Only the user's row carries one, because it is the only row whose moment the daemon actually knows. A
+     * turn's frames arrive with no clock of their own, so an assistant bubble could only ever be stamped with
+     * the whole turn's start or end — a number that says nothing about when that particular block was written.
+     * Rows recorded before this existed simply have none, and the chat draws nothing for them. */
+    sentAt: z.number().optional(),
     // 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.
     attachments: z.array(z.string()).optional(),
+    /* 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. */
+    checkpointId: z.string().optional(),
     thinking: z.string().optional(),
     tools: z.array(RestoredToolCallSchema).optional(),
+    /* What the daemon added to this turn's message (user rows only) — the same notes the live `preamble` frame
+     * carries, recovered from the stored prompt when the transcript is read back. The reader that strips them out
+     * of the user's words is the one that hands them over here instead of dropping them on the floor.
+     *
+     * On the message rather than as a row of its own, and that is load-bearing 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). */
+    notes: z.array(TurnNoteSchema).optional(),
+    /* THE USER WROTE THIS ROW WEARING THE AGENT'S VOICE (assistant rows only) — the composer's "as agent" mode
+     * appending straight into the record, with no turn behind it (agents.place).
+     *
+     * The flag exists for exactly one audience: the HUMAN re-reading the transcript, whose bubble carries a
+     * quiet mark so that months later their own words don't pass as the agent's. The one reader that must
+     * never see it is the agent itself — a placed line reaches the model only through the handoff that seeds a
+     * fresh runtime session (agent/runtime-history.ts), which renders role and text alone, so there the line is
+     * indistinguishable from anything the agent genuinely said. Keep it that way: rendering this flag into any
+     * agent-facing text would break the feature's whole contract. */
+    placed: z.boolean().optional(),
 });
 export type RestoredMessage = z.infer<typeof RestoredMessageSchema>;
 
 export const SessionTranscriptSchema = z.object({ messages: z.array(RestoredMessageSchema) });
 export const AgentTranscriptSchema = SessionTranscriptSchema.extend({ sessionId: z.string().optional() });
 
+/* WHAT A PUBLISHED CONVERSATION'S PAGE IS HANDED — the whole of it, baked into the page as one JSON block.
+ *
+ * A share has to keep working with nothing behind it: no daemon, no session, no sandbox that has to still be
+ * running when the recipient finally opens the link. So the page carries its conversation rather than fetching
+ * 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
+ * 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. */
+export const SharePayloadSchema = z.object({
+    title: z.string(),
+    // When the snapshot was taken, not when the conversation happened — see SharedConversation.sharedAt.
+    sharedAt: z.number(),
+    detail: ShareDetailSchema,
+    messages: z.array(RestoredMessageSchema),
+});
+export type SharePayload = z.infer<typeof SharePayloadSchema>;
+
+/* 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"), requestId: z.string(), text: z.string() });
+const QuestionCardSchema = z.object({ kind: z.literal("question"), requestId: z.string(), questions: z.array(AskQuestionSchema) });
+const PermissionCardSchema = PermissionAskSchema.extend({ kind: z.literal("permission"), requestId: z.string() });
+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
@@ -185,21 +324,26 @@ export const AgentTranscriptSchema = SessionTranscriptSchema.extend({ sessionId:
 // subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("session"), sessionId: z.string() }),
-    /* First frame of an isolated turn: the conversation's worktree identity — its branch (agent/<id>) and the
-     * ROOT repo's short base sha (the checkout moment). Emitted before any provider frames.
+    /* WHERE AN ISOLATED TURN IS STANDING: the conversation's worktree identity — its branch (agent/<id>) and
+     * the ROOT repo's short base sha. First frame of the turn, before any provider frames, and again each time
+     * the branch MOVES underneath it, which is why `base` names where the branch sits now rather than the
+     * moment it was checked out.
      *
      * `unenforced` marks the degraded container: no CAP_SYS_ADMIN, so the turn's worktree could not be
      * bind-mounted over the workspace root and the harness is rewriting tool paths into it instead. That
      * fallback covers what arrives as tool input and not what a subprocess computes for itself, so the
      * operator needs to know — this state used to be one line in the daemon log at boot, and the way it got
-     * noticed was files appearing in the main tree from agents that were supposed to be on branches.
+     * noticed was files appearing in the main tree from agents that were supposed to be on branches. Repeated
+     * on every emission, because it describes the turn and a client rebuilds its standing from the last frame.
      *
-     * `sync` reports the pre-turn rebase (agents/sync.ts), and rides here because this frame is already the
-     * turn's "where you are standing" announcement. Present only when the branch was BEHIND the main line —
-     * `commits` is how many main-line commits it gained, `blocked` names the repos whose rebase would not apply
-     * and was rolled back. Both can be non-empty at once in a multi-repo composition. It is a notice and never
-     * a question: the user is answering their agent, and the alternative to rebasing is not "stay safe" but
-     * "conflict at land time", which interrupts them harder. */
+     * `sync` reports a rebase (agents/sync.ts) and rides here because this frame is already the turn's "where
+     * you are standing" announcement. Present only when the branch was BEHIND the main line — `commits` is how
+     * many main-line commits it gained, `blocked` names the repos whose rebase would not apply and was rolled
+     * back. Both can be non-empty at once in a multi-repo composition. Two moments produce it: before the turn
+     * starts, and after a card the turn parked on is answered — a question or a plan approval waits minutes
+     * for a person, and the main line does not stop moving meanwhile. It is a notice and never a question: the
+     * user is answering their agent, and the alternative to rebasing is not "stay safe" but "conflict at land
+     * time", which interrupts them harder. */
     z.object({
         kind: z.literal("worktree"),
         branch: z.string(),
@@ -213,18 +357,47 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // can say whether the user's own copy is at risk or the main line simply moved on underneath the agent.
     // held ⇒ auto-land is off for this agent: nothing was applied and nothing failed — the delta is waiting
     // on the branch for a deliberate Land (landed is false, conflicts absent).
+    // `deps` rides along when the landed delta left the main tree declaring dependencies it does not have —
+    // the residue of an agent adding one without installing it, which every LATER turn would inherit through
+    // the overlay it mounts over the main checkout. The daemon reconciles it rather than asking anyone to
+    // (workspace/reconcile-deps.ts); this is the receipt, and `deferred` is the honest answer while other turns
+    // are still running, since an install cannot touch a tree they are mounted on.
     z.object({
         kind: z.literal("landed"),
         landed: z.boolean(),
         conflicts: z.array(LandConflictSchema).optional(),
         held: z.boolean().optional(),
+        deps: z.object({ missing: z.number(), started: z.array(z.string()), deferred: z.boolean() }).optional(),
     }),
+    /* WHAT THE DAEMON ADDED TO THE USER'S MESSAGE before the model read it — the exact words, not a summary of
+     * them.
+     *
+     * A turn's prompt is not only what was typed: the daemon prepends notes the model needs and the user did not
+     * write (agent/turn-preamble.ts owns the list — a rebase that moved the branch, dependencies that are behind,
+     * workspace context retrieved for this very message, where an unenforced runtime's files really live). Those
+     * notes change what the agent does, and for a long time the chat's only trace of any of them was one muted
+     * line paraphrasing the rebase — so a user watching an agent act on instructions they could not see had no
+     * way to find out what those instructions said. This frame is the fix: the note text verbatim, one entry per
+     * note, rendered collapsed so it costs a click rather than a scroll.
+     *
+     * `title` is the note's own opening header, which is what the stripper already anchors on — so the two
+     * cannot drift, and a note nobody thought to title cannot reach the wire unlabelled.
+     *
+     * ONE MOMENT, always: the notes went in front of the user's own message before the turn started, so they hang
+     * off that message and are stored on it, which is how a reopened tab still has them. Nothing is injected into
+     * a RUNNING turn — the rebase taken while a card sat waiting was the only thing that ever was, and it no
+     * longer says anything to the model at all (agent/turn-preamble.ts). */
+    z.object({ kind: z.literal("preamble"), notes: z.array(TurnNoteSchema) }),
     // The SDK's init handshake; carries the model it actually resolved for the turn.
     z.object({ kind: z.literal("init"), model: z.string() }),
     // The pre-turn workspace snapshot's id (the attribution-fence "user" capture), emitted once before the
     // provider stream so the client can offer "restore to before this message" on the turn's user bubble.
     // Absent on isolated turns (they snapshot nothing) and when the tree was already clean at turn start.
-    z.object({ kind: z.literal("checkpoint"), id: z.string() }),
+    /* The workspace checkpoint capturing the state as this turn FOUND it — what "go back to before this
+     * message" restores. `index` is the message's position in the conversation's transcript, which the rewind
+     * route addresses it by; absent on a turn with no conversation behind it (the bench, a one-shot), where
+     * the id still powers a plain restore but there is no message to rewind to. */
+    z.object({ kind: z.literal("checkpoint"), id: z.string(), index: z.number().int().nonnegative().optional() }),
     z.object({ kind: z.literal("delta"), text: z.string(), parentToolUseId: z.string().optional() }),
     // The prose block the `delta` frames were writing is finished. A turn emits several: the model says what
     // it is about to do, runs tools, reports what it found, runs more, then summarizes — each a separate text
@@ -318,6 +491,29 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // The live gate: the provider's answer to "may this turn run", pushed mid-turn. Drives the rate-limited
     // notice, not the headroom readouts — see RateLimitInfoSchema.
     RateLimitInfoSchema.extend({ kind: z.literal("rate_limit_info"), account: z.string().optional() }),
+    /* WHAT SPEED THIS TURN ACTUALLY RAN AT, and when it isn't the one asked for, why. Emitted only when the
+     * answer CHANGES within a turn, so the ordinary case is one frame at init and nothing after it; a turn that
+     * enters cooldown mid-flight (fast mode has its own rate-limit pool, separate from the model's) emits a
+     * second.
+     *
+     * This frame exists because fast mode fails SILENTLY and for a lot of different reasons — the plan is free,
+     * extra usage is off, the model doesn't offer it, the turn is routed through the translator and so isn't
+     * first-party, an env var disables it, the pool is in cooldown. Asking for it and getting standard speed is
+     * indistinguishable, from the outside, from asking for it and getting it: same frames, same text, a bill
+     * that differs by 2x. A toggle whose effect can't be observed is worse than no toggle, so the daemon
+     * reports the harness's own answer rather than the client's assumption.
+     *
+     * `reason` is forwarded VERBATIM as the string the harness reported (SDK: FastModeDisabledReason) rather
+     * than re-typed as an enum here: the set is the vendor's and grows on their schedule, and a reason this
+     * build hasn't heard of should reach the user as an unfamiliar word, not fail schema validation and take
+     * the whole frame with it. The client maps the ones it knows to sentences and shows the rest as-is. */
+    z.object({
+        kind: z.literal("fast_mode"),
+        state: FastModeStateSchema,
+        // Absent when nothing is blocking fast mode — including on `state: "on"`, and on an `off` that simply
+        // wasn't asked for.
+        reason: z.string().optional(),
+    }),
     /* The turn is alive but WAITING on the provider: a request failed transiently (5xx, 529, a dropped socket)
      * and the harness is retrying it inside this same turn. A status, not a failure — nothing has been lost and
      * the turn may still finish normally, so the client renders it where "thinking" goes rather than in the
@@ -329,16 +525,19 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
      * actually loses the work — so the wait has to be visible, with its own next-attempt clock.
      *
      * `attempt`/`maxAttempts` are the harness's own counters; `nextAttemptAt` (epoch ms) is when it will try
-     * again, so the readout counts down instead of freezing on a number nobody can interpret. Optional because
-     * only Claude's harness reports the delay: Codex says which attempt it is on and nothing else
-     * (codex-agent.ts), and inventing a countdown for it would be a clock the retry never keeps. */
+     * again, so the readout counts down instead of freezing on a number nobody can interpret. BOTH are optional
+     * for the same reason, which is that each runtime publishes a different half of the wait and none of them
+     * publishes all of it: Claude's harness reports the delay and the bound, Codex says which attempt it is on
+     * and nothing else (codex-agent.ts), OpenCode names the next instant but no bound (grok-agent.ts). Inventing
+     * the missing half would be a countdown, or a limit, the retry never agreed to. */
     z.object({
         kind: z.literal("provider_retry"),
         attempt: z.number(),
-        maxAttempts: z.number(),
+        maxAttempts: z.number().optional(),
         nextAttemptAt: z.number().optional(),
-        // The HTTP status behind it when there was one (529 reads as capacity, 500 as a fault — the client says
-        // which). Absent for a transport failure that never got a response.
+        // The HTTP status behind it when there was one (529 reads as capacity, 429 as a rate limit, 500 as a
+        // fault — the client says which). Absent for a transport failure that never got a response, and for a
+        // runtime that reports the refusal as prose rather than a code (grok-agent.ts reads it back off that).
         status: z.number().optional(),
     }),
     // Every plan-limit pool for the account that served the turn, read from the CLI's usage endpoint once the
@@ -348,10 +547,73 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("account_usage"), account: z.string().optional(), windows: z.array(UsageWindowSchema) }),
     ContextUsageSchema.extend({ kind: z.literal("context_usage") }),
     z.object({ kind: z.literal("compact"), trigger: z.string(), preTokens: z.number().optional(), postTokens: z.number().optional() }),
-    // The three interactive cards. Each parks the turn until `POST /agent/reply` resolves its `requestId`.
-    z.object({ kind: z.literal("plan"), requestId: z.string(), text: z.string() }),
-    z.object({ kind: z.literal("question"), requestId: z.string(), questions: z.array(AskQuestionSchema) }),
-    PermissionAskSchema.extend({ kind: z.literal("permission"), requestId: z.string() }),
+    // The four interactive cards. Each parks the turn until `POST /agent/reply` resolves its `requestId`.
+    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
+    // 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(),
+    }),
+    /* 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 }),
+    /* 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
+     * carries the whole union so richer event kinds land here without a contract break. */
+    z.object({ kind: z.literal("service_event"), requestId: z.string(), event: ServiceStreamEventSchema }),
+    /* How an approved run ended, pushed after the platform answered so the card can settle as a receipt
+     * 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(),
+    }),
+    /* 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 }),
+    /* 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(),
+    }),
     // 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
@@ -395,6 +657,14 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // nothing is coming (the turn was already a resume, or it ran on a credential with nothing to
                 // re-mint from) — that is the case where reconnecting really is the fix.
                 "claude-token-refused",
+                /* THE ACCOUNT IS FINE AND STILL NOT ALLOWED TO RUN — an Anthropic organization that has turned
+                 * Claude Code off for this seat. The token authenticates, the plan's own usage endpoint answers
+                 * with real pools, and every turn is refused anyway, which is why it is its own code rather than
+                 * a member of either neighbour: a spent allowance comes back on a clock and a refused credential
+                 * comes back on a re-mint, and NEITHER of those is true here. Only an admin re-enabling access
+                 * is, so nothing is re-run and nothing asks the user to reconnect — the one recovery that looks
+                 * plausible and is guaranteed to waste their time. */
+                "claude-not-entitled",
                 // The model provider itself failed transiently — 500/502/503, a 529 at capacity, a dropped
                 // socket — and the harness's own in-turn retries did not outlast it. Nothing about the workspace
                 // or the request is wrong, so the daemon remembers the turn and re-runs it on an escalating
@@ -427,9 +697,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
          * that is down only spends tokens on refusals, so each attempt waits longer than the last
          * (provider-health.ts owns the schedule).
          *
-         * `attempt`/`maxAttempts` are on the wire so the notice can say the automation is BOUNDED. An
-         * on-by-default retry that gives no account of how long it will keep going is the kind users switch off
-         * defensively; one that says "attempt 2 of 6" is one they leave on. */
+         * `attempt`/`maxAttempts` are on the wire so the notice can say the automation is BOUNDED. A retry that
+         * gives no account of how long it will keep going is the kind users switch back off the week they turn
+         * it on; one that says "attempt 2 of 6" is one they leave on. */
         outage: z.object({ retryAt: z.number(), attempt: z.number(), maxAttempts: z.number() }).optional(),
     }),
     z.object({ kind: z.literal("done") }),
@@ -456,17 +726,27 @@ export type AttachFrame = z.infer<typeof AttachFrameSchema>;
  * carries the run's prompt verbatim, and a window joining a resumed run would otherwise render the note as a
  * message the USER wrote — the same words the user already said one run up, with a machine's preamble on them.
  * Recognising the prefix is what lets that window reuse the bubble that is already there instead. */
+// The instruction the three whole-turn re-runs share: what follows the note is the original request, repeated.
+// `answered` deliberately does not carry it — what follows THAT note is not a repetition but the user's answer,
+// and telling the model to "continue from that point instead of starting over" about words it has never seen
+// is how a resume reads as the user contradicting themselves.
+const REPEATED =
+    "The interrupted request is repeated below — where part of it was already completed in this session, continue from that point instead of starting over.";
 export const RESUME_NOTES = {
-    auth: "The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically.",
-    outage: "The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically.",
-    restart: "The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back.",
+    auth: `The Claude credential that interrupted this conversation has been renewed, and this turn resumed automatically. ${REPEATED}`,
+    outage: `The model provider was briefly unavailable and interrupted this conversation; this turn resumed automatically. ${REPEATED}`,
+    restart: `The sandbox restarted while this turn was running, which stopped it, and this turn resumed automatically once it came back. ${REPEATED}`,
+    // A turn that was PARKED on the user when the daemon died: nothing re-runs at boot — the card is restored
+    // instead, and this is the turn their answer starts (turn-resume.ts). What rides below the note is the
+    // answer itself, so the model picks the session back up at exactly the decision it had handed over.
+    answered:
+        "The sandbox restarted while this conversation was waiting for the user to respond; it is back, and their response follows below — continue from where the session left off.",
 } as const;
 
-// The prompt a resume actually sends: the note, then why the words below are being repeated, then them.
+// The prompt a resume actually sends: the note (each carries its own account of what the words below are),
+// then them.
 export const withResumeNote = (prompt: string, note: string): string =>
-    Object.values(RESUME_NOTES).some((known) => prompt.startsWith(known))
-        ? prompt
-        : `${note} The interrupted request is repeated below — where part of it was already completed in this session, continue from that point instead of starting over.\n\n${prompt}`;
+    Object.values(RESUME_NOTES).some((known) => prompt.startsWith(known)) ? prompt : `${note}\n\n${prompt}`;
 
 // The user's own words inside a resumed prompt — the note and its explanation stripped back off. Returns the
 // prompt unchanged when it is not a resume, so a caller can hand every attach head through it.
@@ -475,6 +755,42 @@ export const withoutResumeNote = (prompt: string): string => {
     return note === undefined ? prompt : prompt.slice(prompt.indexOf("\n\n") + 2);
 };
 
+export type ResumeReason = keyof typeof RESUME_NOTES;
+
+/* HOW A RESUMED TURN READS TO THE PERSON — the same interruption the note above tells the model, said in the
+ * transcript's own voice instead.
+ *
+ * Stripping the note out of the user's words is only half the job, and for years it was the only half anyone
+ * did: what a reopened conversation showed was a paragraph of machine prose stapled to the front of a message
+ * the user had already sent once, directly under their own copy of it. Both halves of that are wrong — it was
+ * never their sentence, and the words under it are a REPEAT rather than something new they said.
+ *
+ * So the two shapes below, which is the whole of what a reader has to be told:
+ *
+ * `notice` — the three whole-turn re-runs. The words under the note are already in the transcript one turn up,
+ * so the repeat is dropped entirely and the interruption takes its place as a muted line, sitting with the
+ * failure line it resolves ("Failed to authenticate…") and reading like every other thing that HAPPENED to a
+ * turn rather than like something anybody typed.
+ *
+ * `note` — the answered case, where what rides under the note is the user's actual answer to a card and belongs
+ * in the transcript as their words. Nothing is dropped; the explanation rides that message as a collapsed row,
+ * the same disclosure every other daemon-written note gets (TurnNote). */
+export type ResumeDisclosure = { readonly kind: "notice"; readonly text: string } | { readonly kind: "note"; readonly note: TurnNote };
+
+const RESUME_DISCLOSURES: Record<ResumeReason, ResumeDisclosure> = {
+    auth: { kind: "notice", text: "Claude sign-in renewed — this turn picked up where it left off." },
+    outage: { kind: "notice", text: "The model provider came back — this turn picked up where it left off." },
+    restart: { kind: "notice", text: "The sandbox came back — this turn picked up where it left off." },
+    answered: { kind: "note", note: { title: "Picked back up after a sandbox restart", text: RESUME_NOTES.answered } },
+};
+
+// What a stored prompt's resume note should be SHOWN as; undefined when the prompt is not a resume at all, so
+// every reader of a stored prompt can ask without first testing whether it is one.
+export const resumeDisclosure = (prompt: string): ResumeDisclosure | undefined => {
+    const reason = (Object.keys(RESUME_NOTES) as ResumeReason[]).find((key) => prompt.startsWith(RESUME_NOTES[key]));
+    return reason === undefined ? undefined : RESUME_DISCLOSURES[reason];
+};
+
 // One parsed line from `intentic … --output ndjson` (engine events, provider `log`, the terminal `result`).
 // Open-ended by design — the sandbox consumes the wire shape, not @intentic/engine's types — so a string
 // `kind` plus arbitrary extra fields pass through. The apply-events tail (intentic.contract `applyEvents`) rides
@@ -537,12 +853,22 @@ export type Boot = z.infer<typeof BootSchema>;
 // the last `pnpm build:sandbox`), and that stays fully supported — the browser just compares the two sets so a
 // route the daemon predates surfaces as a named, explained gap instead of a bare 404 nobody can attribute.
 //
+// `shapes` answers the half `routes` structurally cannot: a route BOTH builds have, whose payload changed
+// between them. Names match, so nothing 404s — the call goes out and a field the browser expects is simply
+// missing from the answer. It is a map of route name → a fingerprint of that route's input and output schema
+// (see routes.ts), so a difference is a named route rather than "something, somewhere, moved". Beside `routes`
+// rather than folded into it: existence covers every route, shape covers only the ones that can be expressed.
+//
 // Every added field is optional: a daemon built before one simply says nothing, and the browser's fallback is
-// the pre-existing behaviour — routes all assumed present, the daemon assumed ready, the cache left alone.
+// the pre-existing behaviour — routes all assumed present, shapes all assumed to agree, the daemon assumed
+// ready, the cache left alone. That is also why `routes` keeps its bare-string-array shape: an image already in
+// the wild sends exactly that, and a breaking change here would fail the hello frame's own parse and take the
+// whole event stream down for precisely the skew this frame exists to describe.
 export const HelloSchema = z.object({
     kind: z.literal("hello"),
     workspaceId: z.string(),
     routes: z.array(z.string()).optional(),
+    shapes: z.record(z.string(), z.string()).optional(),
     build: z.string().optional(),
     boot: BootProgressSchema.optional(),
 });
@@ -562,6 +888,36 @@ export type ReposChanged = z.infer<typeof ReposChangedSchema>;
 export const WorkspaceChangedSchema = z.object({ kind: z.literal("workspaceChanged"), paths: z.array(z.string()) });
 export type WorkspaceChanged = z.infer<typeof WorkspaceChangedSchema>;
 
+/* THE REPOS WHOSE REFS JUST MOVED — a commit, a checkout, a branch or tag, a rebase started or aborted.
+ *
+ * A third push for the same reason as the two above, and the reason is structural: a repo's git dir does not
+ * live under /work at all (it is relocated onto /history so an isolated turn's worktree can stand in for the
+ * workspace root — see git/repo-git-dirs.ts), and the file watcher descent-ignores `.git` besides. So no
+ * `workspaceChanged` path can ever say "a ref moved", and a surface built on the commit graph would otherwise
+ * be exactly as fresh as the last thing the user clicked.
+ *
+ * It matters most for the work the user did NOT do: the agent commits, rebases and lands out-of-band, with no
+ * HTTP mutation in any browser to hang an invalidation on. Ids are root-relative, "root" being the /work repo.
+ * Diff-not-snapshot, unlike reposChanged: this names what moved, and a repo absent from a frame is a repo that
+ * did not move rather than one that stopped existing. */
+export const RefsChangedSchema = z.object({ kind: z.literal("refsChanged"), repos: z.array(z.string()) });
+export type RefsChanged = z.infer<typeof RefsChangedSchema>;
+
+/* WHICH RUNNING THINGS JUST MOVED — a session opened or exited, a dev server bound its port, a browser closed,
+ * a subagent reported in.
+ *
+ * The fourth push, and the one that covers what the other three structurally cannot: none of this state is on
+ * disk, so no `workspaceChanged` path can name it, and none of it is a ref or a repo. Before it, every view of a
+ * running thing polled on its own timer — which is to say each browser asked, forever, a question only the
+ * daemon could answer and almost always answered "no change".
+ *
+ * Diff-not-snapshot, and deliberately thin: the frame carries the DOMAIN that moved, never the roster itself.
+ * Invalidation only reaches a query something is observing, so a tab showing none of these pays a frame and no
+ * request — whereas a roster on the wire would bill every connected browser the full list whether or not
+ * anything on screen renders it. Which query keys a domain stands for is runtime-state.ts's table. */
+export const RuntimeChangedSchema = z.object({ kind: z.literal("runtimeChanged"), domains: z.array(z.string()) });
+export type RuntimeChanged = z.infer<typeof RuntimeChangedSchema>;
+
 // One connected browser tab of a sandbox member. Identity fields come from the caller's verified Google ID
 // token; activity fields from the tab's own /system/presence reports. No timestamps on the wire — an entry's
 // lifetime IS its /events connection's lifetime, so there is nothing to age out or compare clocks over.
@@ -571,6 +927,9 @@ export const PresenceUserSchema = z.object({
     email: z.string(),
     name: z.string().optional(),
     picture: z.string().optional(),
+    // The caller's trust tier, resolved by the authorizer at connection time. On the roster so every member
+    // can see who may do what — and so a tab knows its OWN role without an owner-only lookup.
+    role: MemberRoleSchema,
     idle: z.boolean(),
     // Route/view name the tab is on ("workspace", "automations", "ext:<id>/<key>", …).
     view: z.string().optional(),
@@ -596,14 +955,16 @@ export const AgentsSchema = z.object({ kind: z.literal("agents"), agents: z.arra
 export type Agents = z.infer<typeof AgentsSchema>;
 
 // The /events stream union: the hello identity frame, then liveness heartbeats interleaved with boot progress,
-// workspace-change batches, repo-set snapshots, 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, and presence + fleet
+// roster snapshots. oRPC validates every yielded frame against this, so all kinds must live here.
 export const SystemEventSchema = z.discriminatedUnion("kind", [
     HelloSchema,
     HeartbeatSchema,
     BootSchema,
     WorkspaceChangedSchema,
     ReposChangedSchema,
+    RefsChangedSchema,
+    RuntimeChangedSchema,
     PresenceSchema,
     AgentsSchema,
 ]);