canopy-ui 0.6.3 → 0.7.0

package/src/chat/SendBox.tsx

@@ -8,7 +8,15 @@ import {
 import type React from "react";
 
 import type { Draft } from "./protocol";
-import { isDraftIdle, msUntilDraftIdle } from "./drafts";
+import {
+  clearStoredDraft,
+  defaultDraftStorage,
+  isDraftIdle,
+  msUntilDraftIdle,
+  readStoredDraft,
+  writeStoredDraft,
+  type DraftStorage,
+} from "./drafts";
 import { Button } from "../ui/button";
 
 /** An attachment the composer is holding, uploaded but not yet sent. */
@@ -28,6 +36,10 @@ interface Props {
   connected: boolean;
   currentUserId: number;
   holderIsPresent: boolean;
+  /** Display name of the teammate holding the draft, when it is not you.
+   *  The composer is where their words appear, so it is where their name
+   *  belongs — it used to live only in a 28px chip in the opposite corner. */
+  holderName?: string | null;
   isStreaming: boolean;
   streamingMessageId: string | null;
   onUpdate: (body: string) => void;
@@ -36,6 +48,10 @@ interface Props {
    *  The server cancels every non-terminal turn regardless, so a null id is
    *  a valid cancel, not a no-op. */
   onStop: (messageId: string | null) => void;
+  /** Whether the stop the human asked for actually landed. Rendered next to the
+   *  button that asked for it, because that is where the person who pressed it
+   *  is looking. Undefined = no stop has been asked for on this turn. */
+  stopState?: "requested" | "stopped" | "failed";
   onTakeOver: () => void;
   /** Optional app-supplied banner rendered above the composer (e.g. an
    *  imported-session note). The kit itself has no CLI-auth banners. */
@@ -49,6 +65,13 @@ interface Props {
    *  paths); it re-renders `attachments` as they progress. */
   onAttach?: (files: File[]) => void;
   onRemoveAttachment?: (id: string) => void;
+  /** Persist what is typed under this key (the session id) so it survives
+   *  unmounting — routing away and back, or closing the tab. Omit to keep the
+   *  purely in-memory behaviour. */
+  persistKey?: string;
+  /** Storage backing `persistKey`. Defaults to localStorage; inject a fake in
+   *  tests, or sessionStorage for per-tab drafts. */
+  storage?: DraftStorage | null;
 }
 
 export function SendBox({
@@ -56,17 +79,21 @@ export function SendBox({
   connected,
   currentUserId,
   holderIsPresent,
+  holderName,
   isStreaming,
   streamingMessageId,
   onUpdate,
   onSend,
   onStop,
+  stopState,
   onTakeOver,
   banner,
   disabledReason,
   attachments,
   onAttach,
   onRemoveAttachment,
+  persistKey,
+  storage,
 }: Props) {
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   // Force a re-render when the lock transitions from live to idle.
@@ -94,7 +121,42 @@ export function SendBox({
   // wholesale), would rewind the composer to a body from 150ms ago. In
   // single-player that reconciliation protects against nothing at all, since
   // there is no co-editor whose edits could be lost.
-  const [localBody, setLocalBody] = useState(draft?.body ?? "");
+  //
+  // Seeded from persisted storage when there is one, because a body typed
+  // before an unmount exists NOWHERE else: single-player never mirrors it to
+  // the server (see drafts.shouldSyncDraftLive), and the adopt rule below
+  // deliberately ignores our own server draft. A stored body wins over
+  // `draft.body` — it is strictly newer, being what was in the box when we
+  // last left it.
+  const store = storage === undefined ? defaultDraftStorage() : storage;
+  const [localBody, setLocalBody] = useState(
+    () => readStoredDraft(store, persistKey ?? "") ?? draft?.body ?? "",
+  );
+
+  // Persistence is a synchronous localStorage write per keystroke — no
+  // debounce on purpose. The payload is a chat message, the write is
+  // microseconds, and every timer-based alternative has to solve flush-on-
+  // unmount and flush-on-tab-close to be correct at exactly the moments this
+  // feature exists for.
+  const persist = (body: string) => {
+    if (persistKey) writeStoredDraft(store, persistKey, body);
+  };
+  // Nothing persists a CO-EDITOR's text, deliberately: a draft someone else is
+  // editing is by definition being live-synced to the server, so the existing
+  // adopt rule below restores it from `session.state` on the way back in. The
+  // gap this whole mechanism closes is the single-player one, where the server
+  // is never told at all.
+
+  // The panel can swap sessions without remounting (same route, new :id), so
+  // the box must follow the key rather than carry one session's text into the
+  // next. Adjusted during render rather than in an effect — React's documented
+  // shape for "reset state when a prop changes", and the one that avoids a
+  // paint showing the previous session's text.
+  const [keyOnScreen, setKeyOnScreen] = useState(persistKey);
+  if (keyOnScreen !== persistKey) {
+    setKeyOnScreen(persistKey);
+    setLocalBody(readStoredDraft(store, persistKey ?? "") ?? "");
+  }
 
   // The ONE case where the server genuinely knows better than this client:
   // somebody ELSE edited the shared draft. Our own echo is ignored, which is
@@ -121,6 +183,10 @@ export function SendBox({
 
   const body = localBody;
   const blocked = Boolean(disabledReason);
+  // Locked BY SOMEONE ELSE, as opposed to blocked for an unrelated reason.
+  // The two look identical to `disabled` and want opposite treatments: a
+  // blocked box is inert, a co-edited one is showing you live content.
+  const lockedByTeammate = !canEdit && holderIsPresent && !holderIsIdle && !blocked;
   // Sending needs a draft (`chat.send` commits the SERVER's copy, so there must
   // be one) AND a live socket. The socket check is load-bearing now that the
   // composer clears optimistically: `send()` drops every frame but chat.stop
@@ -136,6 +202,7 @@ export function SendBox({
 
   const handleChange = (value: string) => {
     setLocalBody(value);
+    persist(value);
     onUpdate(value);
   };
 
@@ -163,6 +230,7 @@ export function SendBox({
     // echo back: that echo carries last_editor === us, which the adopt rule
     // above (correctly) ignores, so nothing else would empty the box.
     setLocalBody("");
+    if (persistKey) clearStoredDraft(store, persistKey);
     onSend();
   };
 
@@ -239,8 +307,37 @@ export function SendBox({
             ))}
           </ul>
         )}
+        {/* Co-edit attribution, at the box rather than across the screen.
+            Their text arrives INSIDE this textarea, and a disabled textarea
+            renders it in muted grey — pixel-identical to a placeholder. So the
+            single most important thing multiplayer does (showing you what your
+            teammate is writing) read as an EMPTY box with a hint in it. */}
+        {lockedByTeammate && (
+          <div
+            data-testid="coedit-banner"
+            className="mb-1.5 flex items-center gap-2 rounded-md border border-primary/30 bg-primary/10 px-2 py-1 text-xs"
+          >
+            <span className="relative flex h-1.5 w-1.5 shrink-0" aria-hidden="true">
+              <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-primary opacity-60" />
+              <span className="relative inline-flex h-1.5 w-1.5 rounded-full bg-primary" />
+            </span>
+            <span className="text-foreground">
+              <span className="font-medium">{holderName ?? "A teammate"}</span> is
+              writing — you are seeing their draft
+            </span>
+            <button
+              type="button"
+              data-testid="take-over"
+              onClick={onTakeOver}
+              className="ml-auto shrink-0 rounded border border-border px-1.5 py-0.5 font-medium text-foreground hover:bg-muted"
+            >
+              take over
+            </button>
+          </div>
+        )}
         <textarea
           ref={textareaRef}
+          data-testid="composer"
           value={body}
           disabled={!canEdit || blocked}
           onChange={(e) => handleChange(e.target.value)}
@@ -248,7 +345,18 @@ export function SendBox({
           onPaste={handlePaste}
           placeholder={placeholder}
           rows={3}
-          className="w-full resize-none rounded-md border border-input bg-transparent p-2 text-sm text-foreground shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:bg-muted disabled:text-muted-foreground"
+          className={[
+            "w-full resize-none rounded-md border bg-transparent p-2 text-sm shadow-sm",
+            "placeholder:text-muted-foreground focus-visible:outline-none",
+            "focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed",
+            // A teammate's draft is CONTENT, not a disabled control. Dimming it
+            // to `text-muted-foreground` made their sentence look like the
+            // placeholder it sits next to — the one styling choice that made
+            // co-editing appear not to work at all.
+            lockedByTeammate
+              ? "border-primary/40 bg-primary/5 text-foreground"
+              : "border-input text-foreground disabled:bg-muted disabled:text-muted-foreground",
+          ].join(" ")}
         />
         <div className="mt-1 flex items-center justify-end gap-2">
           {canAttach && (
@@ -281,6 +389,26 @@ export function SendBox({
               {disabledReason}
             </span>
           )}
+          {stopState === "failed" ? (
+            // The one state that MUST be loud. Everything else here is either
+            // self-evident (the reply stopped) or transient. A stop that did not
+            // take looks exactly like a stop that worked — the agent keeps
+            // running either way — so without this it is invisible, which is the
+            // whole reason Stop could not be trusted.
+            <span
+              role="status"
+              className="mr-auto text-xs font-medium text-destructive"
+              title="Escape was pressed and the agent is still running. Try again, or stop it in the terminal."
+            >
+              stop didn&rsquo;t take — still running
+            </span>
+          ) : null}
+          {/* Never DISABLED while a stop is in flight, only relabelled. If the
+              runner dies between the request and the verdict, `stopState` never
+              advances — and a button that latched off would leave the human with
+              no way to ask again, the exact trap #519 documents for the composer
+              lock. Pressing again is harmless: the runner dedupes by session_key,
+              so three impatient presses are still one Escape. */}
           {isStreaming ? (
             <Button
               type="button"
@@ -288,15 +416,16 @@ export function SendBox({
               size="sm"
               onClick={handleStopClick}
             >
-              stop
-            </Button>
-          ) : null}
-          {!canEdit && holderIsPresent && !holderIsIdle ? (
-            <Button type="button" variant="outline" size="sm" onClick={onTakeOver}>
-              take over
+              {stopState === "requested" ? "stopping…" : "stop"}
             </Button>
           ) : null}
-          <Button type="button" size="sm" disabled={!canSend} onClick={handleSend}>
+          <Button
+            type="button"
+            size="sm"
+            data-testid="send"
+            disabled={!canSend}
+            onClick={handleSend}
+          >
             send
           </Button>
         </div>

package/src/chat/drafts.test.ts

@@ -2,10 +2,15 @@ import { afterEach, describe, expect, it, vi } from "vitest"
 
 import type { Draft } from "./protocol"
 import {
+  DRAFT_STORAGE_TTL_MS,
   IDLE_THRESHOLD_MS,
+  clearStoredDraft,
+  draftStorageKey,
   isDraftIdle,
   msUntilDraftIdle,
+  readStoredDraft,
   shouldSyncDraftLive,
+  writeStoredDraft,
 } from "./drafts"
 
 const NOW = 1_700_000_000_000
@@ -88,3 +93,118 @@ describe("shouldSyncDraftLive", () => {
     expect(shouldSyncDraftLive([1, 2])).toBe(true)
   })
 })
+
+// ---------------------------------------------------------------------------
+// Composer persistence
+// ---------------------------------------------------------------------------
+
+function fakeStorage(seed: Record<string, string> = {}) {
+  const map = new Map(Object.entries(seed))
+  return {
+    map,
+    getItem: (k: string) => map.get(k) ?? null,
+    setItem: (k: string, v: string) => void map.set(k, v),
+    removeItem: (k: string) => void map.delete(k),
+  }
+}
+
+const KEY = "sess-1"
+
+describe("readStoredDraft", () => {
+  it("returns null when there is nothing stored", () => {
+    expect(readStoredDraft(fakeStorage(), KEY)).toBeNull()
+  })
+
+  it("round-trips a written body", () => {
+    const s = fakeStorage()
+    writeStoredDraft(s, KEY, "half a thought", NOW)
+    expect(readStoredDraft(s, KEY, NOW + 1000)).toBe("half a thought")
+  })
+
+  it("drops and prunes an entry past the TTL", () => {
+    const s = fakeStorage()
+    writeStoredDraft(s, KEY, "stale", NOW)
+    expect(readStoredDraft(s, KEY, NOW + DRAFT_STORAGE_TTL_MS + 1)).toBeNull()
+    expect(s.map.has(draftStorageKey(KEY))).toBe(false)
+  })
+
+  it("keeps an entry right up to the TTL boundary", () => {
+    const s = fakeStorage()
+    writeStoredDraft(s, KEY, "fresh enough", NOW)
+    expect(readStoredDraft(s, KEY, NOW + DRAFT_STORAGE_TTL_MS)).toBe("fresh enough")
+  })
+
+  it("drops and prunes malformed JSON", () => {
+    const s = fakeStorage({ [draftStorageKey(KEY)]: "{not json" })
+    expect(readStoredDraft(s, KEY, NOW)).toBeNull()
+    expect(s.map.has(draftStorageKey(KEY))).toBe(false)
+  })
+
+  it("drops an entry of the wrong shape", () => {
+    const s = fakeStorage({ [draftStorageKey(KEY)]: JSON.stringify({ body: 42 }) })
+    expect(readStoredDraft(s, KEY, NOW)).toBeNull()
+  })
+
+  it("reports an empty stored body as nothing to restore", () => {
+    // "" must not shadow a server draft the host does want rendered.
+    const s = fakeStorage({
+      [draftStorageKey(KEY)]: JSON.stringify({ body: "", at: NOW }),
+    })
+    expect(readStoredDraft(s, KEY, NOW)).toBeNull()
+  })
+
+  it("is inert without a storage or without a key", () => {
+    expect(readStoredDraft(null, KEY)).toBeNull()
+    expect(readStoredDraft(fakeStorage(), "")).toBeNull()
+  })
+
+  it("survives a storage that throws on read", () => {
+    // Safari private mode / blocked third-party storage.
+    const s = {
+      getItem: () => {
+        throw new Error("SecurityError")
+      },
+      setItem: () => {},
+      removeItem: () => {},
+    }
+    expect(() => readStoredDraft(s, KEY)).not.toThrow()
+    expect(readStoredDraft(s, KEY)).toBeNull()
+  })
+})
+
+describe("writeStoredDraft", () => {
+  it("clears the entry instead of storing an empty body", () => {
+    const s = fakeStorage()
+    writeStoredDraft(s, KEY, "typed", NOW)
+    writeStoredDraft(s, KEY, "", NOW)
+    expect(s.map.has(draftStorageKey(KEY))).toBe(false)
+  })
+
+  it("keeps one entry per session", () => {
+    const s = fakeStorage()
+    writeStoredDraft(s, "a", "for a", NOW)
+    writeStoredDraft(s, "b", "for b", NOW)
+    expect(readStoredDraft(s, "a", NOW)).toBe("for a")
+    expect(readStoredDraft(s, "b", NOW)).toBe("for b")
+  })
+
+  it("swallows a quota error rather than breaking a keystroke", () => {
+    const s = {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("QuotaExceededError")
+      },
+      removeItem: () => {},
+    }
+    expect(() => writeStoredDraft(s, KEY, "x")).not.toThrow()
+  })
+})
+
+describe("clearStoredDraft", () => {
+  it("removes a stored draft", () => {
+    const s = fakeStorage()
+    writeStoredDraft(s, KEY, "sent now", NOW)
+    clearStoredDraft(s, KEY)
+    expect(readStoredDraft(s, KEY, NOW)).toBeNull()
+  })
+})

package/src/chat/drafts.ts

@@ -35,3 +35,137 @@ export function msUntilDraftIdle(draft: Draft | null | undefined): number {
   const elapsed = Date.now() - new Date(draft.last_edit_at).getTime();
   return Math.max(0, IDLE_THRESHOLD_MS - elapsed);
 }
+
+// ---------------------------------------------------------------------------
+// Composer persistence — surviving a navigation the server never hears about.
+//
+// The composer is local-first (see SendBox) and, alone in a session,
+// `shouldSyncDraftLive` keeps it that way: nothing is mirrored to the server
+// until the moment before `chat.send`. Those two facts are right on their own
+// and, together, mean a half-typed message dies the instant SendBox unmounts —
+// route away from /chat/:id and back and the box is empty, with no copy of the
+// text anywhere. (Adopting your OWN server draft on mount wouldn't fix it:
+// single-player never put one there.)
+//
+// So the copy has to be local too. localStorage rather than sessionStorage
+// because "come back to it" includes closing the tab; per-browser, deliberately
+// not synced across devices.
+// ---------------------------------------------------------------------------
+
+/** Just the slice of `Storage` this needs — so tests can pass a plain fake and
+ *  a host can pass sessionStorage if it prefers per-tab drafts. */
+export interface DraftStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+const DRAFT_STORAGE_PREFIX = "canopy.chat.draft.";
+
+/** Drafts older than this are treated as gone. A month-old half-sentence is
+ *  not something you meant to come back to, and restoring it into a live
+ *  session is worse than losing it. */
+export const DRAFT_STORAGE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function draftStorageKey(persistKey: string): string {
+  return `${DRAFT_STORAGE_PREFIX}${persistKey}`;
+}
+
+/**
+ * `window.localStorage` when it is usable, else null.
+ *
+ * Merely TOUCHING the property throws in a sandboxed iframe or with
+ * third-party storage blocked, so this is a try/catch and not a truthiness
+ * check. Null disables persistence and changes nothing else — typing must
+ * never depend on storage being available.
+ */
+export function defaultDraftStorage(): DraftStorage | null {
+  try {
+    return typeof window === "undefined" ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The stored body for a session, or null when there is nothing worth
+ * restoring. Anything unreadable — absent, malformed, wrong shape, expired —
+ * is dropped and reported as null, and an expired or corrupt entry is pruned on
+ * the way past so it cannot accumulate.
+ */
+export function readStoredDraft(
+  storage: DraftStorage | null,
+  persistKey: string,
+  now: number = Date.now(),
+): string | null {
+  if (!storage || !persistKey) return null;
+  const key = draftStorageKey(persistKey);
+  let raw: string | null = null;
+  try {
+    raw = storage.getItem(key);
+  } catch {
+    return null;
+  }
+  if (raw == null) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    remove(storage, key);
+    return null;
+  }
+
+  const record = parsed as { body?: unknown; at?: unknown } | null;
+  const body = record?.body;
+  const at = record?.at;
+  if (typeof body !== "string" || typeof at !== "number") {
+    remove(storage, key);
+    return null;
+  }
+  if (now - at > DRAFT_STORAGE_TTL_MS) {
+    remove(storage, key);
+    return null;
+  }
+  // An empty body is not a draft. Returning "" would be indistinguishable from
+  // a real restore and would shadow a server draft the host DOES want shown.
+  return body === "" ? null : body;
+}
+
+/** Persist the composer body. Writing an empty body clears the entry rather
+ *  than storing one, so an emptied box leaves nothing behind to restore. */
+export function writeStoredDraft(
+  storage: DraftStorage | null,
+  persistKey: string,
+  body: string,
+  now: number = Date.now(),
+): void {
+  if (!storage || !persistKey) return;
+  const key = draftStorageKey(persistKey);
+  if (body === "") {
+    remove(storage, key);
+    return;
+  }
+  try {
+    storage.setItem(key, JSON.stringify({ body, at: now }));
+  } catch {
+    // Quota exceeded, or storage disabled mid-session. A dropped draft backup
+    // is not worth breaking a keystroke over.
+  }
+}
+
+export function clearStoredDraft(
+  storage: DraftStorage | null,
+  persistKey: string,
+): void {
+  if (!storage || !persistKey) return;
+  remove(storage, draftStorageKey(persistKey));
+}
+
+function remove(storage: DraftStorage, key: string): void {
+  try {
+    storage.removeItem(key);
+  } catch {
+    // same as above — best effort
+  }
+}

package/src/chat/index.ts

@@ -32,6 +32,17 @@ export { useStickyBottom } from "./useStickyBottom";
 // Draft idle helpers
 export { IDLE_THRESHOLD_MS, isDraftIdle, msUntilDraftIdle } from "./drafts";
 
+// Composer persistence (survives unmount / tab close)
+export {
+  DRAFT_STORAGE_TTL_MS,
+  clearStoredDraft,
+  defaultDraftStorage,
+  draftStorageKey,
+  readStoredDraft,
+  writeStoredDraft,
+  type DraftStorage,
+} from "./drafts";
+
 // Tool-message pairing helpers
 export {
   pairToolMessages,

package/src/chat/pairToolMessages.ts

@@ -12,7 +12,7 @@ import type { Message } from "./protocol";
  * has no other way to tell which result belongs to which call.
  *
  * Not every producer stamps ids yet: events already in the ledger predate
- * this field, and some runners (see `packages/canopy_runner`) don't emit it
+ * this field, and some runners (see `runner/canopy_runner`) don't emit it
  * until updated separately. When a ``tool_result`` carries no id at all, it
  * falls back to the FIRST still-open ``tool_use`` that *also* has no id
  * (oldest-first, FIFO) — today's pre-correlation pairing heuristic. That

package/src/chat/protocol.ts

@@ -60,16 +60,64 @@ export interface Participant {
   last_seen_at: string | null;
 }
 
-/** A dialog an agent is blocked on, read off its terminal.
+/** A dialog an agent is blocked on.
  *
  *  `title` and `body` are what makes it answerable away from the keyboard:
- *  "Do you want to proceed?" tells you nothing without the command it means. */
+ *  "Do you want to proceed?" tells you nothing without the command it means.
+ *
+ *  Two producers, one shape, so this never grows a second reader: the session
+ *  report derives it from the transcript (an `AskUserQuestion` tool call — what
+ *  actually blocks a fleet running `bypass permissions`), and the runner can
+ *  still read it off the rendered screen for the dialogs a transcript cannot
+ *  see. `source` says which, and a client is free to ignore it. */
+/** One question of an `AskUserQuestion`. The TUI draws these as TABS and will
+ *  not submit until each has an answer — so a surface that renders only the
+ *  first one cannot complete the ask no matter which button is pressed. That
+ *  was the bug: a two-question closeout showed one question, and a tap toggled
+ *  a checkbox on a dialog that then sat waiting for a Submit nobody could
+ *  reach (eva, 2026-08-12). */
+export interface MenuQuestion {
+  index: number;
+  question: string;
+  header?: string;
+  /** Whether this question takes ANY number of answers. The TUI renders it as
+   *  checkboxes and a number key TOGGLES one instead of answering, which is why
+   *  a client that cannot see this flag renders the wrong control AND the
+   *  runner presses the wrong key. */
+  multi_select?: boolean;
+  options: { number: number; label: string; description?: string }[];
+}
+
 export interface SessionMenu {
   question: string;
   title?: string;
   body?: string;
   selected?: number | null;
-  options: { number: number; label: string }[];
+  source?: string;
+  /** Every question in the ask, in declaration order. Absent on a dialog with
+   *  no tool call behind it (a permission prompt, a trust gate) and on a menu
+   *  from a producer older than this — in both cases the client falls back to
+   *  the single-question fields above, which still describe question 1. */
+  questions?: MenuQuestion[];
+  /** `description` is present on the transcript path and is often the only
+   *  thing that distinguishes two options — "Proceed to Phase 4" does not say
+   *  that Phase 4 is test-gated, and its description does. */
+  options: { number: number; label: string; description?: string }[];
+  /** Set when a human's tap was RELAYED to the runner and then refused there —
+   *  a stale dialog, a shell tab selected in emdash, an unreachable box. The
+   *  API answers `ok:true` the moment it relays the frame, so without this a
+   *  correct refusal is indistinguishable from a press that worked, and the
+   *  button reads as dead. `answer_note` is the sentence to show; the code is
+   *  for logs. The menu stays up alongside it, so there is something to retry. */
+  answer_error?: string;
+  answer_note?: string;
+  /** Carried across a runner restart rather than observed this process. Nothing
+   *  should branch on it — a tap verifies against the real screen either way. */
+  restored?: boolean;
+  /** Epoch seconds when a producer last SAW this dialog. The dialog lives on a
+   *  terminal; this object is a copy, and without an age the only way to find
+   *  out the copy is stale is to tap it and be refused. */
+  observed_at?: number;
 }
 
 export interface SessionState {
@@ -83,9 +131,20 @@ export interface SessionState {
    *  those apart — but it is the difference between "still thinking, wait" and
    *  "it is waiting on YOU", which previously rendered identically. */
   activity?: "working" | "idle" | "blocked";
-  /** The dialog the agent is waiting on, when one could be read off its screen.
-   *  Absent when the agent is not blocked, or when the runner has no way to look
-   *  (no CDP) — "blocked" still arrives, it just has no buttons. */
+  /** Whether a stop the human asked for actually landed. A SEPARATE axis from
+   *  `activity`, deliberately: a stop that failed leaves the agent `working`,
+   *  which is true and must stay true, so the outcome of the stop cannot be a
+   *  value of activity without either lying or being lost.
+   *
+   *  "requested" is set the moment the server publishes to the runner — nothing
+   *  has pressed Escape yet. Only the runner can say "stopped" or "failed", and
+   *  it only says so after verifying the terminal (see #649: an unverified
+   *  Escape reported as success is what made Stop untrustworthy). */
+  stopState?: "requested" | "stopped" | "failed";
+  /** The dialog the agent is waiting on. Carried in the CONNECT SNAPSHOT, not
+   *  only in live frames: `session.activity` is view-only and reaches a client
+   *  only if it was already connected when the agent blocked — which is exactly
+   *  the case that fails, because you go and look BECAUSE it stopped. */
   menu?: SessionMenu;
   active_draft: Draft | null;
   participants: Participant[];
@@ -113,6 +172,13 @@ export type WsEvent =
   // The agent started or finished a turn. Distinct from tool events: it fires
   // while Claude is THINKING, before any content exists to show.
   | { event: "session.activity"; data: { state: "working" | "idle" | "blocked"; menu?: SessionMenu } }
+  | { event: "session.stop"; data: { state: "requested" | "stopped" | "failed" } }
+  // The agent started, or stopped, waiting on a dialog. Its own frame rather
+  // than an overloaded `session.activity`: activity answers "is it producing",
+  // which the hook path owns on a much faster clock, and inventing a state here
+  // to carry a menu would report an agent as idle or blocked on the wrong one.
+  // `menu: null` is the retraction — somebody answered at the keyboard.
+  | { event: "session.menu"; data: { menu: SessionMenu | null } }
   // A human typed into emdash rather than into this page. No client echoed it,
   // so this is the only way it reaches the browser before a reload.
   | { event: "chat.user_message"; data: { message_id: string; turn_index: number; plaintext: string } }
@@ -129,5 +195,19 @@ export type WsEvent =
   | { event: "draft.lock_changed"; data: { draft_id: string; holder_user_id: number | null; expires_at: number | null } }
   | { event: "draft.committed"; data: { draft_id: string; user_message_id: string } }
   | { event: "draft.discarded"; data: { draft_id: string } }
-  | { event: "presence.joined"; data: { user_id: number; email?: string; display_name?: string } }
+  // `participant` carries WHO joined, so a client can add them to its
+  // participant list. Without it a first-time joiner has an id and no name,
+  // and the presence row (which renders participants filtered by presence)
+  // cannot show them at all. Optional so an older server degrades rather than
+  // breaks. The bare `email`/`display_name` below are the vestigial shape that
+  // was declared but never sent by anything.
+  | {
+      event: "presence.joined";
+      data: {
+        user_id: number;
+        participant?: Participant;
+        email?: string;
+        display_name?: string;
+      };
+    }
   | { event: "presence.left"; data: { user_id: number } };