canopy-ui 0.6.3 → 0.8.0

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

@@ -17,6 +17,10 @@ export type {
   WsEvent,
 } from "./protocol";
 
+// REST <-> kit conversion. Shared because both hosts that read a transcript over
+// REST were writing this out by hand, against this kit's own Message type.
+export { restToKitMessage, type RestMessage } from "./restMessage";
+
 // Reducer (pure)
 export { sessionReducer } from "./sessionReducer";
 export { prependHistory } from "./history";
@@ -32,6 +36,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,
@@ -56,3 +71,6 @@ export {
   type PlacementBannerProps,
   type PlacementRunner,
 } from "./PlacementBanner";
+// The AG-UI projection's inverse. Exported so a consumer can translate a stream
+// it obtained some other way — and so the round-trip test can reach it.
+export { fromAgui, resetAguiState, CUSTOM_PREFIX, METADATA_KEY } from "./agui";

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 } };

package/src/chat/restMessage.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import { prependHistory } from "./history";
+import { restToKitMessage, type RestMessage } from "./restMessage";
+import type { Message } from "./protocol";
+
+const row: RestMessage = {
+  turn_index: 7,
+  role: "assistant",
+  content: { text: "hello" },
+  plaintext: "hello",
+  created_at: "2026-09-16T10:00:00Z",
+};
+
+describe("restToKitMessage", () => {
+  it("maps a REST row onto the kit's Message shape", () => {
+    expect(restToKitMessage(row)).toEqual({
+      id: "t7",
+      turn_index: 7,
+      role: "assistant",
+      content: { text: "hello" },
+      plaintext: "hello",
+      status: "complete",
+      error_detail: null,
+      started_at: null,
+      completed_at: "2026-09-16T10:00:00Z",
+      created_at: "2026-09-16T10:00:00Z",
+    });
+  });
+
+  it("gives a row read back from REST no streaming history", () => {
+    // A REST row was never watched arriving, so claiming a `started_at` would
+    // invent a fact. `completed_at` is what the server does know.
+    const m = restToKitMessage(row);
+    expect(m.started_at).toBeNull();
+    expect(m.completed_at).toBe(row.created_at);
+  });
+
+  it("accepts a readonly generated row (what both hosts actually pass)", () => {
+    // openapi-typescript emits every field `readonly`. Property readonly-ness
+    // does not affect assignability, and this asserts that stays true — it is
+    // the reason `RestMessage` can be declared structurally instead of as
+    // either host's generated type.
+    const generated: { readonly [K in keyof RestMessage]: RestMessage[K] } = row;
+    expect(restToKitMessage(generated).id).toBe("t7");
+  });
+
+  it("does not collide with the live WS row for the same turn", () => {
+    // The synthetic `t<turn_index>` id is only safe because prependHistory
+    // dedupes on turn_index. If that ever changed to dedupe on id, this fails.
+    const live: Message = { ...restToKitMessage(row), id: "1234", status: "streaming" };
+    const merged = prependHistory([live], [restToKitMessage(row)]);
+    expect(merged).toHaveLength(1);
+    expect(merged[0].id).toBe("1234");
+  });
+});

package/src/chat/restMessage.ts

@@ -0,0 +1,54 @@
+/**
+ * One REST transcript row -> the kit's `Message`.
+ *
+ * This lived twice, written out by hand in both hosts that read a transcript
+ * over REST and then hand it to this kit: canopy-web's own
+ * `pages/chatPageLogic.ts` and ace-web's `canopy/CanopyChatPanel.tsx`, whose
+ * copy carried the comment "mirrors canopy-web's own
+ * `chatPageLogic.ts::restToKitMessage`" — an accurate description of a bug
+ * waiting to happen. It is a pure function OF this kit's own `Message` type
+ * against canopy's own `MessageOut` wire schema, so neither host was ever the
+ * right owner of it; both were translating between two shapes they had each
+ * imported from somewhere else.
+ *
+ * The input is declared structurally rather than as either host's generated
+ * type, because the hosts generate their own: canopy-web has
+ * `components["schemas"]["MessageOut"]`, ace-web casts an `unknown` row. Both
+ * are assignable to `RestMessage`, and a generated type's `readonly` property
+ * modifiers do not affect that.
+ */
+
+import type { Message } from "./protocol";
+
+/** canopy's `MessageOut` (apps/canopy_sessions/schemas.py), structurally. */
+export interface RestMessage {
+  turn_index: number;
+  role: string;
+  content: Record<string, unknown>;
+  plaintext: string;
+  created_at: string;
+}
+
+/**
+ * Synthetic id (`t<turn_index>`) + `status: "complete"`.
+ *
+ * `prependHistory` dedupes on `turn_index`, not on `id`, so a synthetic id can
+ * never collide with the live WS row for the same turn — which is the whole
+ * reason it is safe to invent one here. `started_at` is null because a row read
+ * back from REST has no streaming history to report; `completed_at` takes
+ * `created_at`, which is when the turn finished as far as the server records it.
+ */
+export function restToKitMessage(m: RestMessage): Message {
+  return {
+    id: `t${m.turn_index}`,
+    turn_index: m.turn_index,
+    role: m.role as Message["role"],
+    content: m.content,
+    plaintext: m.plaintext,
+    status: "complete",
+    error_detail: null,
+    started_at: null,
+    completed_at: m.created_at,
+    created_at: m.created_at,
+  };
+}

package/src/chat/sessionReducer.test.ts

@@ -617,7 +617,7 @@ describe("the dialog an agent is blocked on", () => {
     expect(after.menu).toBeUndefined();
   });
 
-  it("is cleared by a later activity frame that has no menu", () => {
+  it("is cleared by a later activity frame that says the agent is not waiting", () => {
     const blocked = sessionReducer(makeState(), {
       event: "session.activity",
       data: { state: "blocked", menu: MENU },
@@ -625,4 +625,105 @@ describe("the dialog an agent is blocked on", () => {
     const idle = sessionReducer(blocked, { event: "session.activity", data: { state: "idle" } });
     expect(idle.menu).toBeUndefined();
   });
+
+  it("survives a blocked frame that carries no menu", () => {
+    // The hook path reports `blocked` WITHOUT a menu — it deliberately does not
+    // read the screen (#510: doing so stole emdash's focus). Treating that as a
+    // retraction would erase a menu the snapshot or the session report had
+    // already supplied, which is every menu we now have.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked", menu: MENU },
+    });
+    const again = sessionReducer(blocked, { event: "session.activity", data: { state: "blocked" } });
+    expect(again.menu?.question).toBe("Do you want to proceed?");
+  });
+
+  it("arrives in the connect snapshot, not only in a live frame", () => {
+    // THE fix for "when I click on the session I don't see the menu". Activity
+    // frames are view-only and reach a client only if it was connected when
+    // they fired; you open the session precisely because it stopped.
+    const state = sessionReducer(makeState(), {
+      event: "session.state",
+      data: makeState({ activity: "blocked", menu: MENU }),
+    });
+    expect(state.menu?.question).toBe("Do you want to proceed?");
+  });
+
+  it("appears while you are already watching, via its own frame", () => {
+    const state = sessionReducer(makeState(), {
+      event: "session.menu",
+      data: { menu: MENU },
+    });
+    expect(state.menu?.options).toHaveLength(2);
+  });
+
+  it("is retracted when somebody answers at the keyboard", () => {
+    // `menu: null` from the session report. Buttons that outlive their dialog
+    // press a number into what is now an ordinary prompt, where the agent reads
+    // a bare "1" as an instruction.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.menu",
+      data: { menu: MENU },
+    });
+    const cleared = sessionReducer(blocked, { event: "session.menu", data: { menu: null } });
+    expect(cleared.menu).toBeUndefined();
+  });
+
+  it("keeps an option's description, which is often the whole difference", () => {
+    const state = sessionReducer(makeState(), {
+      event: "session.menu",
+      data: {
+        menu: {
+          question: "How should the run proceed?",
+          options: [
+            { number: 1, label: "Proceed to Phase 4", description: "nothing reaches a real LLO" },
+            { number: 2, label: "Stop the run here", description: "end at the Phase 3 boundary" },
+          ],
+        },
+      },
+    });
+    expect(state.menu?.options[0].description).toContain("real LLO");
+  });
+});
+
+describe("session.stop — whether the stop actually landed", () => {
+  const base = (over: Partial<SessionState> = {}): SessionState => ({
+    messages: [],
+    active_draft: null,
+    participants: [],
+    presence_user_ids: [],
+    current_user_id: 1,
+    ...over,
+  });
+
+  it("records a requested stop without claiming it worked", () => {
+    const out = sessionReducer(base(), {
+      event: "session.stop",
+      data: { state: "requested" },
+    } as WsEvent);
+    expect(out.stopState).toBe("requested");
+  });
+
+  it("keeps the agent WORKING when the stop failed", () => {
+    // The whole point of a separate axis. A failed stop leaves the agent running,
+    // and both facts have to survive together — collapsing them into `activity`
+    // loses whichever one loses the race, and it was always the stop.
+    const out = sessionReducer(base({ activity: "working" }), {
+      event: "session.stop",
+      data: { state: "failed" },
+    } as WsEvent);
+    expect(out.stopState).toBe("failed");
+    expect(out.activity).toBe("working");
+  });
+
+  it("a new turn clears a stale stop outcome", () => {
+    // "your stop did not take" pinned over fresh work is a warning about
+    // something the human has already moved on from.
+    const out = sessionReducer(base({ stopState: "failed" }), {
+      event: "chat.stream_start",
+      data: { message_id: "m1" },
+    } as WsEvent);
+    expect(out.stopState).toBeUndefined();
+  });
 });