Merge remote-tracking branch 'origin/main' into aeolian

Tool rows interleaved with agent text now produce separate
collapsed groups instead of one per turn. The timeline reads
text → group → text → group, matching chronological order.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

crates/maestro-e2e/tests/e2e.rs

@@ -777,7 +777,7 @@ async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
         other => panic!("expected a kill_guarded refusal, got {other:?}"),
     }
 
-    // Force overrides the refusal and nothing else: session gone, tree kept.
+    // Force overrides the refusal: session gone, tree removed.
     client.kill_session_forced(s.id).await.expect("forced kill");
 
     assert!(
@@ -789,12 +789,12 @@ async fn unpushed_commits_block_kill_and_force_keeps_the_tree() {
             .any(|x| x.id == s.id),
         "the forced kill ends the session"
     );
-    assert!(wt.is_dir(), "a guarded worktree must stay on disk");
+    assert!(!wt.is_dir(), "a forced kill removes the worktree");
     assert!(
-        git_worktree_list(base.path())
+        !git_worktree_list(base.path())
             .iter()
             .any(|l| l.contains("feature/local")),
-        "the kept tree stays registered in git"
+        "the removed tree is unregistered from git"
     );
 }
 

docs/STRUCTURED-VIEW.md

@@ -189,20 +189,17 @@ choices, not daemon ones.
   presentation for `Notice`. `Plan` is the exception: both clients omit it
   from the transcript; the TUI may show the current plan in its status line,
   while the web client deliberately has no stats or plan rail.
-- The web client groups two or more tool rows after the same `User` row into
-  one collapsed turn activity block. `AgentText` and `AgentThought` rows that
-  appear *between* tool rows in the same turn are absorbed into the group
-  (intermediate narration); the last `AgentText` with no subsequent tool stays
-  outside as the prominent final answer. While a turn is still active
-  (responding or thinking), the most recent trailing text or thought row is
-  kept outside as visible narration — the operator always sees the agent's
-  latest reasoning without opening the group. It is replaced by the next text
-  row when one arrives, and absorbed into the group when the turn ends (unless
-  it is `AgentText`, which stays outside as the final answer). The collapsed
-  header reads "N tool calls · Label 'arg'" where the label and argument come
-  from the last tool row's `splitToolTitle` — the operator sees which command
-  is current at a glance. Opening the group reveals tools and intermediate
-  text in chronological order, with the text rendered in a subdued style.
+- The web client groups each contiguous run of two or more tool rows into a
+  collapsed activity block. An `AgentText` or `AgentThought` row between
+  tools splits them into separate groups, so the timeline reads
+  text → group → text → group rather than lumping every tool in a turn into
+  one box. Text and thought rows stay outside groups as standalone transcript
+  items — the operator sees all reasoning without expanding. Resolved
+  approval rows between tools within a run are absorbed into the group. The
+  collapsed header reads "N tool calls · Label 'arg'" where the label and
+  argument come from the last tool row's `splitToolTitle` — the operator
+  sees which command is current at a glance. Opening the group reveals tool
+  rows in chronological order.
 - The web client's user, agent, thought, tool-detail, and notice text blocks
   copy their complete source text when clicked or keyboard-activated.
 - The web client consumes `available_commands_update` notices as the live

web/src/components/layout/MultiView.test.tsx

@@ -105,7 +105,7 @@ describe("MultiView", () => {
       expect(screen.getByText("Tab 1 · 1")).toBeTruthy();
       const pane = document.querySelector('[data-session-id="s9"]');
       expect(pane).toBeTruthy();
-      expect(pane!.querySelector(".bg-preview-tint")).toBeTruthy();
+      expect(pane!.classList.contains("is-preview")).toBe(true);
       expect(screen.getByText("preview")).toBeTruthy();
     });
 

web/src/components/layout/MultiView.tsx

@@ -188,8 +188,9 @@ function Pane({
   return (
     <div
       className={
-        "mv-pane flex h-full min-h-0 min-w-0 flex-col border " +
-        (isFocused && !isPreview ? "border-accent" : "border-border-strong")
+        "mv-pane flex h-full min-h-0 min-w-0 flex-col" +
+        (isFocused ? " is-focused" : "") +
+        (isPreview ? " is-preview" : "")
       }
       data-leaf-id={leaf.id}
       data-session-id={leaf.sessionId ?? undefined}
@@ -201,10 +202,7 @@ function Pane({
       }}
     >
       <div
-        className={
-          "mv-pane-header flex items-center justify-between gap-sp-2 border-b border-border-strong px-sp-2 py-sp-1 text-fs-12 " +
-          (isPreview ? "bg-preview-tint text-preview" : "bg-surface")
-        }
+        className="mv-pane-header attach-header flex items-center justify-between gap-sp-2 border-b border-border-strong px-sp-2 py-sp-1 text-fs-12"
       >
         {leaf.sessionId ? (
           <PaneTitle sessionId={leaf.sessionId} session={session} />

web/src/components/layout/PaneTitle.tsx

@@ -15,7 +15,7 @@ export interface PaneTitleProps {
 export function PaneTitle({ sessionId, session, className }: PaneTitleProps) {
   if (!session) {
     return (
-      <span className={className ?? "at-title"} title={sessionId}>
+      <span className={className ?? "attach-title"} title={sessionId}>
         session <span className="sid">{sessionId.slice(0, 8)}</span>
       </span>
     );
@@ -27,7 +27,7 @@ export function PaneTitle({ sessionId, session, className }: PaneTitleProps) {
   const icon = tool ? toolIconSvg(tool) : null;
 
   return (
-    <span className={className ?? "at-title"} title={`${name} · ${session.command}  (${sessionId})`}>
+    <span className={className ?? "attach-title"} title={`${name} · ${session.command}  (${sessionId})`}>
       <span className="at-name">{name}</span>
       {showCommand && (
         <span className="at-cmd">

web/src/components/sidebar/SessionCard.tsx

@@ -44,14 +44,17 @@ export interface SessionCardProps {
   onRenameCancel(): void;
 }
 
-/** The fill ladder from docs/SIDEBAR.md "Which row is filled", furthest down
- * wins. Written as one ordered run so the precedence is the order it reads in. */
-function rowFill(p: SessionCardProps): string {
-  if (p.active) return "bg-accent-fill";
-  if (p.previewing) return "bg-preview-tint";
-  if (p.open) return "bg-accent/[0.06]";
-  if (p.highlighted) return "bg-preview-tint";
-  return "";
+/** The fill ladder from docs/SIDEBAR.md "Which row is filled" — the CSS
+ * cascade in styles.css carries the actual fills via `.is-active`, `.is-open`,
+ * `.is-previewing` (all inside `:where()` so source order is the precedence).
+ * We just apply the right class names here. */
+function rowClasses(p: SessionCardProps): string {
+  const cls: string[] = [];
+  if (p.active) cls.push("is-active");
+  if (p.open) cls.push("is-open");
+  if (p.previewing) cls.push("is-previewing");
+  if (p.highlighted) cls.push("is-highlighted");
+  return cls.join(" ");
 }
 
 export function SessionCard(props: SessionCardProps) {
@@ -62,7 +65,7 @@ export function SessionCard(props: SessionCardProps) {
 
   return (
     <a
-      className={`session-card tree-leaf no-underline ${rowFill(props)} ${
+      className={`session-card tree-leaf no-underline ${rowClasses(props)} ${
         running ? "" : "opacity-60"
       }`}
       href={`#/attach/${encodeURIComponent(s.id)}`}

web/src/components/structured/StructuredPane.test.tsx

@@ -323,6 +323,26 @@ describe("prompt and cancel", () => {
     await waitFor(() => expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "next up"));
   });
 
+  it("concatenates multiple queued messages into a single prompt", async () => {
+    const { socket } = mount();
+    snapshot(socket, [], busy);
+    const input = document.querySelector<HTMLTextAreaElement>(".structured-input")!;
+    const form = document.querySelector("form.structured-composer")!;
+
+    fireEvent.change(input, { target: { value: "first" } });
+    fireEvent.submit(form);
+    fireEvent.change(input, { target: { value: "second" } });
+    fireEvent.submit(form);
+
+    expect(sendStructuredPrompt).not.toHaveBeenCalled();
+    const queued = document.querySelectorAll(".st-row-queued");
+    expect(queued).toHaveLength(2);
+
+    socket.emit({ type: "reduced_state", state: idle });
+    await waitFor(() => expect(sendStructuredPrompt).toHaveBeenCalledWith("s1", "first\n\nsecond"));
+    expect(sendStructuredPrompt).toHaveBeenCalledTimes(1);
+  });
+
   it("hands a failed send's draft back to the operator", async () => {
     vi.mocked(sendStructuredPrompt).mockRejectedValueOnce(new Error("boom"));
     const { socket } = mount();

web/src/components/structured/StructuredPane.tsx

@@ -251,14 +251,16 @@ export const StructuredPane = forwardRef<StructuredPaneHandle, StructuredPanePro
     [sessionId, socketGeneration, session],
   );
 
-  // A queued message goes out as soon as the projected turn is idle — the
-  // daemon answers a second prompt `409 turn_in_flight`, so the queue is
-  // client-local (docs/STRUCTURED-VIEW.md).
+  // Queued messages are concatenated into a single prompt so the agent sees
+  // one user turn instead of N back-to-back turns. The daemon rejects a
+  // second prompt while a turn is in flight (`409 turn_in_flight`), so the
+  // queue is client-local (docs/STRUCTURED-VIEW.md).
   useEffect(() => {
     if (active || promptPending.current || queue.length === 0) return;
-    const [next, ...rest] = queue;
-    setQueue(rest);
-    dispatchPrompt(next.text, next.attachments);
+    const text = queue.map((q) => q.text).join("\n\n");
+    const files = queue.flatMap((q) => q.attachments);
+    setQueue([]);
+    dispatchPrompt(text, files);
   }, [active, queue, dispatchPrompt]);
 
   const submit = (text: string, files: File[]) => {

web/src/components/structured/model.test.ts

@@ -115,8 +115,8 @@ describe("activity grouping", () => {
   it("groups a turn's tools once there are two of them", () => {
     const rows = [text("user:1", "user", "go"), tool("tool:1"), tool("tool:2")];
     const groups = activityGroupsByTurn(rows, null, false);
-    expect([...groups.keys()]).toEqual(["turn:user:1"]);
-    expect(groups.get("turn:user:1")).toMatchObject({ toolCount: 2 });
+    expect([...groups.keys()]).toEqual(["turn:user:1:0"]);
+    expect(groups.get("turn:user:1:0")).toMatchObject({ toolCount: 2 });
   });
 
   it("leaves a single tool call standalone", () => {
@@ -124,7 +124,7 @@ describe("activity grouping", () => {
     expect(activityGroupsByTurn(rows, null, false).size).toBe(0);
   });
 
-  it("absorbs intermediate narration but keeps the final answer outside", () => {
+  it("splits tools into separate runs when text appears between them", () => {
     const rows = [
       text("user:1", "user", "go"),
       tool("tool:1"),
@@ -132,12 +132,26 @@ describe("activity grouping", () => {
       tool("tool:2"),
       text("agent:2", "agent_text", "done"),
     ];
-    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
-    expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "agent:1", "tool:2"]);
-    expect(group.toolCount).toBe(2);
+    // Each run has only one tool, so neither qualifies for grouping.
+    expect(activityGroupsByTurn(rows, null, false).size).toBe(0);
   });
 
-  it("keeps the newest thought outside while the turn is still live", () => {
+  it("groups contiguous tools separated by text into distinct groups", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      tool("tool:2"),
+      text("agent:1", "agent_text", "working"),
+      tool("tool:3"),
+      tool("tool:4"),
+    ];
+    const groups = activityGroupsByTurn(rows, null, false);
+    expect([...groups.keys()]).toEqual(["turn:user:1:0", "turn:user:1:1"]);
+    expect(groups.get("turn:user:1:0")!.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2"]);
+    expect(groups.get("turn:user:1:1")!.rows.map((r) => r.id)).toEqual(["tool:3", "tool:4"]);
+  });
+
+  it("keeps thoughts outside the group as standalone items", () => {
     const rows = [
       text("user:1", "user", "go"),
       tool("tool:1"),
@@ -145,26 +159,8 @@ describe("activity grouping", () => {
       text("thought:1", "agent_thought", "hmm"),
       text("thought:2", "agent_thought", "aha"),
     ];
-    const live = activityGroupsByTurn(rows, null, true).get("turn:user:1")!;
-    expect(live.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2", "thought:1"]);
-    const ended = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
-    expect(ended.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2", "thought:1", "thought:2"]);
-  });
-
-  it("keeps the newest agent_text outside while the turn is still live", () => {
-    const rows = [
-      text("user:1", "user", "go"),
-      tool("tool:1"),
-      text("agent:1", "agent_text", "working on it"),
-      tool("tool:2"),
-      text("agent:2", "agent_text", "almost done"),
-    ];
-    const live = activityGroupsByTurn(rows, null, true).get("turn:user:1")!;
-    // "almost done" stays outside as visible narration while the turn is live
-    expect(live.rows.map((r) => r.id)).toEqual(["tool:1", "agent:1", "tool:2"]);
-    const ended = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
-    // Once ended, the final agent_text stays outside as the answer
-    expect(ended.rows.map((r) => r.id)).toEqual(["tool:1", "agent:1", "tool:2"]);
+    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1:0")!;
+    expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "tool:2"]);
   });
 
   it("tracks the last tool's label and argument for the collapsed header", () => {
@@ -173,7 +169,7 @@ describe("activity grouping", () => {
       row("tool:1", "tool_call", { title: "Read(src/main.ts)", status: "completed" }),
       row("tool:2", "tool_call", { title: "Execute(git status)", kind: "execute", status: "completed" }),
     ];
-    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1")!;
+    const group = activityGroupsByTurn(rows, null, false).get("turn:user:1:0")!;
     expect(group.lastToolLabel).toBe("Execute");
     expect(group.lastToolArg).toBe("git status");
   });
@@ -187,7 +183,7 @@ describe("activity grouping", () => {
       row("approval:2", "approval"),
       tool("tool:3"),
     ];
-    const group = activityGroupsByTurn(rows, "approval:2", false).get("turn:user:1")!;
+    const group = activityGroupsByTurn(rows, "approval:2", false).get("turn:user:1:0")!;
     expect(group.rows.map((r) => r.id)).toEqual(["tool:1", "approval:1", "tool:2", "tool:3"]);
   });
 });
@@ -198,11 +194,31 @@ describe("transcript render list", () => {
     const items = transcriptItems(rows, null, false);
     expect(items.map((item) => (item.type === "row" ? item.row.id : item.id))).toEqual([
       "user:1",
-      "turn:user:1",
+      "turn:user:1:0",
       "agent:1",
     ]);
   });
 
+  it("interleaves groups and text in timeline order", () => {
+    const rows = [
+      text("user:1", "user", "go"),
+      tool("tool:1"),
+      tool("tool:2"),
+      text("agent:1", "agent_text", "working"),
+      tool("tool:3"),
+      tool("tool:4"),
+      text("agent:2", "agent_text", "done"),
+    ];
+    const items = transcriptItems(rows, null, false);
+    expect(items.map((item) => (item.type === "row" ? item.row.id : item.id))).toEqual([
+      "user:1",
+      "turn:user:1:0",
+      "agent:1",
+      "turn:user:1:1",
+      "agent:2",
+    ]);
+  });
+
   it("omits plan rows, state-only notices and standalone resolved approvals", () => {
     const rows = [
       text("user:1", "user", "go"),

web/src/components/structured/model.ts

@@ -144,9 +144,10 @@ export function turnIsActive(state: ReducedState): boolean {
 }
 
 export interface ActivityGroup {
-  /** Header label count — tool rows only, never absorbed text. */
+  /** Header label count — tool rows only. */
   toolCount: number;
-  /** Tools plus absorbed intermediate text/approvals, in transcript order. */
+  /** Tool rows and resolved approvals, in transcript order. Text/thought
+   *  rows stay outside the group as standalone transcript items. */
   rows: TranscriptRow[];
   /** `splitToolTitle` of the last tool row — the collapsed header shows it. */
   lastToolLabel: string;
@@ -154,87 +155,68 @@ export interface ActivityGroup {
 }
 
 /**
- * Group tool rows (and intermediate agent text / resolved approvals between
- * them) by turn. An agent_text/agent_thought row is "intermediate" when a tool
- * row follows it in the same turn — it gets absorbed into the group so the
- * collapsed block preserves chronological order. Resolved approval rows (not
- * the currently pending one) are absorbed the same way. The *last* agent text
- * with no subsequent tool stays standalone (the prominent final answer).
+ * Group contiguous tool rows (and resolved approvals between them) into
+ * collapsible blocks. An `AgentText` or `AgentThought` row between tools
+ * splits the run — each contiguous stretch of tools becomes its own group,
+ * so the timeline reads text → group → text → group rather than lumping
+ * every tool in a turn into one box.
  *
- * While a turn is still live, the most recent text or thought row trailing the
- * group also stays outside as visible narration — the operator always sees the
- * agent's latest reasoning without opening the group.
- *
- * Returns groups keyed by `turn:<userId>`.
+ * A group must contain at least two tools to qualify; a single tool stays
+ * standalone. Returns groups keyed by `turn:<userId>:<seq>`.
  */
 export function activityGroupsByTurn(
   rows: TranscriptRow[],
   pendingApprovalId: string | null,
-  turnActive: boolean,
+  _turnActive: boolean,
 ): Map<string, ActivityGroup> {
-  // First: count tools per turn to know which turns qualify for grouping.
-  const toolCounts = new Map<string, number>();
-  let turnId = "before-first-message";
-  for (const row of rows) {
-    if (row.kind === "user") turnId = row.id;
-    if (row.kind !== "tool_call" && row.kind !== "tool_diff") continue;
-    const gid = `turn:${turnId}`;
-    toolCounts.set(gid, (toolCounts.get(gid) ?? 0) + 1);
-  }
-  // Second: build groups with interleaved text for turns with 2+ tools.
   const groups = new Map<string, ActivityGroup>();
-  turnId = "before-first-message";
-  // Pending rows that might be intermediate (not yet confirmed by a following
-  // tool). If no tool follows, they stay standalone.
-  let pending: TranscriptRow[] = [];
-  let currentGid = `turn:${turnId}`;
+  let turnId = "before-first-message";
+  let runSeq = 0;
+  let runTools: TranscriptRow[] = [];
+  let runPending: TranscriptRow[] = [];
+
+  const flushRun = () => {
+    if (runTools.length >= 2) {
+      const gid = `turn:${turnId}:${runSeq}`;
+      const tool = (runTools[runTools.length - 1].data ?? {}) as { title?: string; name?: string | null; kind?: string };
+      const { label, arg } = splitToolTitle(tool.title, tool.name ?? undefined, tool.kind);
+      groups.set(gid, {
+        toolCount: runTools.length,
+        rows: [...runTools],
+        lastToolLabel: label,
+        lastToolArg: arg,
+      });
+      runSeq++;
+    }
+    runTools = [];
+    runPending = [];
+  };
+
   for (const row of rows) {
     if (row.kind === "user") {
+      flushRun();
       turnId = row.id;
-      currentGid = `turn:${turnId}`;
-      pending = [];
+      runSeq = 0;
+      continue;
+    }
+    // Text and thought rows break the current tool run.
+    if (row.kind === "agent_text" || row.kind === "agent_thought") {
+      flushRun();
       continue;
     }
-    const count = toolCounts.get(currentGid) ?? 0;
-    if (count < 2) continue;
-    const isIntermediateText = row.kind === "agent_text" || row.kind === "agent_thought";
     const isResolvedApproval = row.kind === "approval" && row.id !== pendingApprovalId;
-    if (isIntermediateText || isResolvedApproval) {
-      pending.push(row);
+    if (isResolvedApproval) {
+      runPending.push(row);
       continue;
     }
     if (row.kind === "tool_call" || row.kind === "tool_diff") {
-      const group = groups.get(currentGid) ?? { toolCount: count, rows: [], lastToolLabel: "", lastToolArg: "" };
-      // Flush any pending rows — a tool follows, so they're intermediate.
-      group.rows.push(...pending);
-      pending = [];
-      group.rows.push(row);
-      const tool = (row.data ?? {}) as { title?: string; name?: string | null; kind?: string };
-      const { label, arg } = splitToolTitle(tool.title, tool.name ?? undefined, tool.kind);
-      group.lastToolLabel = label;
-      group.lastToolArg = arg;
-      groups.set(currentGid, group);
+      // Flush any pending resolved approvals into the run before this tool.
+      runTools.push(...runPending);
+      runPending = [];
+      runTools.push(row);
     }
   }
-  // Trailing text/thought rows after the last tool in this turn.
-  // While the turn is still live, the newest one stays outside as visible
-  // narration — the operator always sees the agent's latest reasoning.
-  // A final agent_text (the "answer") stays outside regardless.
-  const lastGroup = groups.get(currentGid);
-  if (lastGroup && pending.length > 0) {
-    const allThoughts = pending.every((row) => row.kind === "agent_thought");
-    if (allThoughts) {
-      // Pure thoughts: absorb all when done, keep the newest outside while live.
-      const absorb = turnActive ? pending.slice(0, -1) : pending;
-      lastGroup.rows.push(...absorb);
-    } else if (turnActive) {
-      // Mixed or agent_text trailing: keep the very last row outside while live,
-      // absorb the rest.
-      lastGroup.rows.push(...pending.slice(0, -1));
-    }
-    // When the turn ends with agent_text last, nothing extra is absorbed — the
-    // text stays outside as the final answer.
-  }
+  flushRun();
 
   return groups;
 }
@@ -246,10 +228,10 @@ export type TranscriptItem =
   | { type: "group"; id: string; group: ActivityGroup };
 
 /**
- * The transcript in render order: rows, with each turn's tool activity folded
- * into a single group item where one exists. Resolved approvals not absorbed
- * into a group are dropped — the tool row itself already identifies the
- * action. `plan` rows and state-only notices are dropped too (both clients
+ * The transcript in render order: rows, with each contiguous tool stretch
+ * folded into a single group item where one exists. Resolved approvals not
+ * absorbed into a group are dropped — the tool row itself already identifies
+ * the action. `plan` rows and state-only notices are dropped too (both clients
  * omit `Plan` from the transcript). A turn footer only survives as the final
  * item, so old footers stop reading like transcript content.
  */
@@ -259,21 +241,19 @@ export function transcriptItems(
   turnActive: boolean,
 ): TranscriptItem[] {
   const groups = activityGroupsByTurn(rows, pendingApprovalId, turnActive);
-  const grouped = new Set<string>();
-  for (const group of groups.values()) for (const row of group.rows) grouped.add(row.id);
+  // Reverse index: row id → group id that contains it.
+  const rowToGroup = new Map<string, string>();
+  for (const [groupId, group] of groups) for (const r of group.rows) rowToGroup.set(r.id, groupId);
 
   const items: TranscriptItem[] = [];
-  let turnId = "before-first-message";
   const emitted = new Set<string>();
   for (const row of rows) {
-    if (row.kind === "user") turnId = row.id;
-    const groupId = `turn:${turnId}`;
-    const group = groups.get(groupId);
-    if (group && grouped.has(row.id)) {
+    const groupId = rowToGroup.get(row.id);
+    if (groupId !== undefined) {
       // The group renders once, at its first member's position.
       if (!emitted.has(groupId)) {
         emitted.add(groupId);
-        items.push({ type: "group", id: groupId, group });
+        items.push({ type: "group", id: groupId, group: groups.get(groupId)! });
       }
       continue;
     }

web/src/components/structured/useStructuredSession.ts

@@ -196,12 +196,24 @@ export function useStructuredSession(
       connect();
     };
 
+    // Mobile browsers suspend timers and silently kill WebSockets in the
+    // background. Kick a fresh connect when the page becomes visible again.
+    const onVisibility = () => {
+      if (document.visibilityState !== "visible" || disposed) return;
+      if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) return;
+      cancelTimer();
+      setStatus("reconnecting");
+      connect();
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+
     setStatus("connecting");
     connect();
 
     return () => {
       disposed = true;
       reconnectRef.current = () => {};
+      document.removeEventListener("visibilitychange", onVisibility);
       cancelTimer();
       closeSocket();
     };

web/src/components/terminal/TerminalPane.tsx

@@ -302,6 +302,24 @@ export const TerminalPane = forwardRef<TerminalPaneHandle, TerminalPaneProps>(
       ta?.addEventListener("focus", onTaFocus);
       ta?.addEventListener("blur", onTaBlur);
 
+      // Mobile browsers (Android especially) suspend timers and silently kill
+      // WebSockets when the app goes to background. The backoff timer set by
+      // onclose is frozen too, so recovery stalls until visibility returns. Kick
+      // a fresh connect immediately when the page becomes visible again.
+      const onVisibility = () => {
+        if (document.visibilityState !== "visible" || disposed) return;
+        if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) return;
+        // Cancel any pending backoff — we're reconnecting right now.
+        if (reconnectTimer !== null) {
+          window.clearTimeout(reconnectTimer);
+          reconnectTimer = null;
+        }
+        reconnectMs = INITIAL_RECONNECT_MS;
+        onStatusChange?.("reconnecting");
+        connect();
+      };
+      document.addEventListener("visibilitychange", onVisibility);
+
       window.addEventListener("resize", onResize);
       const visual = window.visualViewport ?? null;
       visual?.addEventListener("resize", onResize);
@@ -326,6 +344,7 @@ export const TerminalPane = forwardRef<TerminalPaneHandle, TerminalPaneProps>(
           reconnectTimer = null;
         }
         ro.disconnect();
+        document.removeEventListener("visibilitychange", onVisibility);
         window.removeEventListener("resize", onResize);
         visual?.removeEventListener("resize", onResize);
         ta?.removeEventListener("focus", onTaFocus);