@evandu/super-pi 0.1.139 → 0.1.140

package/dist/server/subagent-runs.d.ts

@@ -15,7 +15,8 @@ import type { ModelSelection, ServerEvent, SubagentRun } from "./types.js";
  *    mid-run leaves an orphan - and `Store.open` fails that orphan with a reason on the next start.
  * 2. **A snapshot on every delta.** `subagent.event` carries the run as it stands, not just at the end,
  *    because streaming a sub-agent is the entire reason Super Pi spawns its own instead of shipping Pi's
- *    extension (design §2, reason 1).
+ *    extension (design §2, reason 1). The snapshot's `output` is the TAIL of the accumulated text
+ *    ({@link LIVE_OUTPUT_TAIL_CAP}); the whole text is in the store and in the settle event.
  *
  * What deliberately does NOT go into either is the child's transcript. See `SubagentRun`.
  */
@@ -29,6 +30,21 @@ import type { ModelSelection, ServerEvent, SubagentRun } from "./types.js";
  * what was said. The parent model is handed the capped copy, because that is the window it actually has.
  */
 export declare const PER_TASK_OUTPUT_CAP: number;
+/**
+ * How much of the ACCUMULATED output a delta-phase `subagent.event` may carry.
+ *
+ * A delta event is a SNAPSHOT the card replaces itself with, and it fires PER DELTA. Carrying the whole
+ * accumulated text makes the Nth event N characters long - the traffic is quadratic in the output length
+ * (the flood behind "连接中 / 断连 / 连接中", see docs/SUBAGENT-WS-FLOOD-FIX-2026-10-29.md). So a live
+ * event carries only the TAIL of what the child has said; the run's full output still reaches everyone -
+ * the STORE record is written unabridged on every delta (a mid-run reload rebuilds from `state`, not from
+ * events), and the settle event carries the final text in full. A watching human needs the last few
+ * hundred characters, not the first ones, so the tail is the useful end.
+ *
+ * THIS CHANGES WHAT AN OLD CLIENT SEES: a card whose child has said more than this shows the latest 8 KB
+ * (sliding) instead of the whole text, then the full text at settle. The field shape is unchanged.
+ */
+export declare const LIVE_OUTPUT_TAIL_CAP: number;
 /** What a caller supplies to dispatch one run. The workspace directory is required, like `AnswerInput.cwd`. */
 export type SubagentDispatch = {
     id?: string;
@@ -75,6 +91,20 @@ export type SubagentRunHooks = {
      * attached without changing the recorder.
      */
     broadcast: (event: ServerEvent) => void;
+    /**
+     * Fires ONCE per run, AFTER the terminal `subagent.event` has been broadcast from `settle()`. This -
+     * not the delta phase - is when a caller should broadcast a full `state` snapshot: the run's final
+     * record is on disk by then, so a browser that reloads after it sees the finished card. Broadcasting
+     * state on every DELTA is what flooded the socket (each delta demanded a full state frame; a burst of
+     * deltas demanded hundreds).
+     */
+    onSettled?: () => void;
+    /**
+     * Cap on `run.output` in delta-phase events, in characters; defaults to {@link LIVE_OUTPUT_TAIL_CAP}.
+     * A settle event always carries the full output regardless. `Number.POSITIVE_INFINITY` disables the
+     * cap - the diagnostic "legacy flood" mode uses that to reproduce the pre-fix wire shape.
+     */
+    liveTailCap?: number;
     /**
      * Builds the host that answers a CHILD's questions, keyed by the run as well as the conversation
      * (design §4). Optional because a headless caller has nobody to ask; a child that asks in that case is

package/dist/server/subagent-runs.js

@@ -12,7 +12,8 @@ import { SubagentCancelled, newSubagentRunId } from "./subagents.js";
  *    mid-run leaves an orphan - and `Store.open` fails that orphan with a reason on the next start.
  * 2. **A snapshot on every delta.** `subagent.event` carries the run as it stands, not just at the end,
  *    because streaming a sub-agent is the entire reason Super Pi spawns its own instead of shipping Pi's
- *    extension (design §2, reason 1).
+ *    extension (design §2, reason 1). The snapshot's `output` is the TAIL of the accumulated text
+ *    ({@link LIVE_OUTPUT_TAIL_CAP}); the whole text is in the store and in the settle event.
  *
  * What deliberately does NOT go into either is the child's transcript. See `SubagentRun`.
  */
@@ -26,6 +27,21 @@ import { SubagentCancelled, newSubagentRunId } from "./subagents.js";
  * what was said. The parent model is handed the capped copy, because that is the window it actually has.
  */
 export const PER_TASK_OUTPUT_CAP = 50 * 1024;
+/**
+ * How much of the ACCUMULATED output a delta-phase `subagent.event` may carry.
+ *
+ * A delta event is a SNAPSHOT the card replaces itself with, and it fires PER DELTA. Carrying the whole
+ * accumulated text makes the Nth event N characters long - the traffic is quadratic in the output length
+ * (the flood behind "连接中 / 断连 / 连接中", see docs/SUBAGENT-WS-FLOOD-FIX-2026-10-29.md). So a live
+ * event carries only the TAIL of what the child has said; the run's full output still reaches everyone -
+ * the STORE record is written unabridged on every delta (a mid-run reload rebuilds from `state`, not from
+ * events), and the settle event carries the final text in full. A watching human needs the last few
+ * hundred characters, not the first ones, so the tail is the useful end.
+ *
+ * THIS CHANGES WHAT AN OLD CLIENT SEES: a card whose child has said more than this shows the latest 8 KB
+ * (sliding) instead of the whole text, then the full text at settle. The field shape is unchanged.
+ */
+export const LIVE_OUTPUT_TAIL_CAP = 8 * 1024;
 export class SubagentRunRecorder {
     supervisor;
     hooks;
@@ -174,24 +190,22 @@ export class SubagentRunRecorder {
          * and is what a card should say about a run whose child never existed. See `SubagentFailure`.
          */
         let stage = "dispatch";
+        // Live events carry only the tail of the accumulated output (see LIVE_OUTPUT_TAIL_CAP) so a
+        // per-delta snapshot stays small no matter how much the child has said.
+        const liveTailCap = this.hooks.liveTailCap ?? LIVE_OUTPUT_TAIL_CAP;
         const publish = () => {
-            record.output = streamed;
+            record.output = streamed.length > liveTailCap ? streamed.slice(streamed.length - liveTailCap) : streamed;
             record.toolCalls = toolCalls;
             record.activity = activity;
             // WRITE BEFORE ANNOUNCE, and this is the whole defect. The order of the two statements below is
             // load-bearing; swapping them back reintroduces a card that loses text it already streamed.
             //
-            // The hook a caller installs announces the event and THEN broadcasts `state` (`index.ts`), so both
-            // frames leave here in that order whatever this function does internally. Announcing first made the
-            // `state` frame a snapshot of a store this delta had not reached yet - the write below had not even
-            // been CALLED. The browser REPLACES on `state` (`App.tsx`), so a card that had just been handed the
-            // right text had it taken back one frame later.
-            //
-            // Why some cards lived anyway and this one did not: a child that keeps talking recovers by accident,
-            // because its NEXT delta publishes a `state` once the write queue has drained. A child that says one
-            // thing and goes quiet never publishes again, so nothing restores it - and it is not only that child's
-            // card. Every later `state` broadcast from any command, including ones about an unrelated
-            // conversation, reads that same stale record.
+            // Announcing before the store write means any `state` snapshot taken after the announce - from
+            // whatever command, this run's or an unrelated conversation's - still reads the PRE-delta record.
+            // The browser REPLACES on `state` (`App.tsx`), so a card that had just been handed the right text
+            // would have it taken back one frame later. This run's own delta phase no longer triggers a
+            // `state` broadcast at all (the caller hooks that via `onSettled` at settle time only), but OTHER
+            // commands broadcast `state` while this child streams, and every one of them reads this record.
             //
             // The write is still not awaited, and still must not be: `onTextDelta` is synchronous, and a drain loop
             // that flushed to disk per token would throttle the child. Reordering buys the correctness anyway,
@@ -222,6 +236,9 @@ export class SubagentRunRecorder {
             // the correct trade: never announce state that a reload would contradict.
             const settled = await this.hooks.store.setSubagentRun(id, changes);
             this.hooks.broadcast({ type: "subagent.event", run: structuredClone(record) });
+            // The ONE moment a full `state` broadcast is needed: the final record is on disk NOW, so a browser
+            // that reloads after this point rebuilds the finished card from `state`. See the `onSettled` doc.
+            this.hooks.onSettled?.();
             return settled;
         };
         /**

package/dist/server/task-tool.d.ts

@@ -244,3 +244,21 @@ export declare function normalizeTodos(raw: unknown): {
  * header are computed from the same stored list and cannot disagree.
  */
 export declare function todoSummary(todos: readonly TodoItem[]): string;
+/**
+ * The orchestrator extension's half of the environment contract.
+ * `agents/super-pi-task/core.ts` is the other end; `scripts/task-tool.test.mjs` asserts the two copies agree.
+ */
+export declare const ORCHESTRATOR_ENDPOINT_ENV = "SUPER_PI_ORCHESTRATOR_ENDPOINT";
+/** Tool names registered with Pi. */
+export declare const SESSION_SPAWN_TOOL_NAME = "session_spawn";
+export declare const SESSION_STATUS_TOOL_NAME = "session_status";
+export declare const SESSION_DISPATCH_TOOL_NAME = "session_dispatch";
+export declare const SESSION_STOP_TOOL_NAME = "session_stop";
+/** Model-facing description for session_spawn. */
+export declare const SESSION_SPAWN_DESCRIPTION = "Create a new sibling conversation in the current workspace and immediately dispatch its initial task.\n\nDIFFERENCE FROM THE 'task' TOOL:\n- The 'task' tool delegates to a transient, one-shot subagent process (scout, critic, patcher) that runs once, returns its final text, and terminates. It has no conversation history and does not appear in the workspace sidebar.\n- 'session_spawn' creates a real, persistent sibling CONVERSATION in Super Pi. It appears in the sidebar, retains multi-turn message history, can receive follow-up messages via session_dispatch, can be inspected via session_status, and can be stopped via session_stop. The user can also switch to it in the Web UI.\n\nWHEN TO USE THIS:\n- Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.\n- Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.\n- When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.\n\nWHEN NOT TO USE THIS:\n- For one-off, focused delegation with a single answer: use 'task' (with scout/critic/patcher). It is faster, cheaper, and returns directly to your transcript.\n- For running shell commands or build watchers: use 'run_async'.\n- For a linear multi-step subagent pipeline: use 'workflow'.\n\nUsage notes:\n1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.\n2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.\n3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.";
+/** Model-facing description for session_status. */
+export declare const SESSION_STATUS_DESCRIPTION = "Inspect the progress, run state, and latest activity of sibling conversations created by the orchestrator.\n\nWHEN TO USE THIS:\n- To check whether a spawned sibling conversation is still running, has finished (idle), is stopped, or encountered an error.\n- To read the latest assistant progress snippet without bloating your context with the session's entire raw message transcript.\n- To list all sibling conversations under your coordination when conversationId is omitted.\n\nUsage notes:\n1. When 'conversationId' is provided: returns a compact summary for that specific session, including its run status ('idle', 'running', 'waiting', 'stopped', 'failed'), messageCount, turnCount, lastAssistantSnippet, lastUserSnippet, activeTool, and error (if any).\n2. When 'conversationId' is omitted: returns a summary list of ALL sibling conversations spawned by this orchestrator session.\n3. This tool never returns full transcripts; it returns concise summaries and snippets to keep your context window lean.";
+/** Model-facing description for session_dispatch. */
+export declare const SESSION_DISPATCH_DESCRIPTION = "Send a message, follow-up instructions, or steering guidance to an existing sibling conversation.\n\nWHEN TO USE THIS:\n- To follow up with a sibling session after reading its progress with session_status.\n- To give feedback, provide additional requirements, or answer a question from a sibling session.\n- To kick off a new turn on an idle or stopped sibling session.\n\nUsage notes:\n1. 'conversationId' is required and must identify an existing sibling conversation.\n2. 'content' is the text instruction sent to that session, just as if typed by a user in that session's chat.\n3. Dispatch is ASYNCHRONOUS by default: it enqueues the message into the session's queue and returns immediately.\n4. If the sibling session is currently busy running a turn, the dispatched message is placed in its waiting queue and processed when the active turn completes.";
+/** Model-facing description for session_stop. */
+export declare const SESSION_STOP_DESCRIPTION = "Stop execution in a sibling conversation.\n\nWHEN TO USE THIS:\n- When a sibling session has gone down the wrong path, is stuck in an unwanted loop, or when the overall goal has changed and remaining work should be aborted.\n- To clear pending queued messages before they start running.\n\nUsage notes:\n1. 'mode' controls what to stop:\n   - 'all' (default): stops the currently running turn and cancels all pending queued messages in the session.\n   - 'active': only interrupts the active running turn; leaves any pending queued messages untouched.\n   - 'queued': only cancels pending queued messages; lets the currently running turn complete naturally.\n2. Use 'messageId' if you want to cancel or interrupt one specific queued message instead of all queued messages.";

package/dist/server/task-tool.js

@@ -333,3 +333,88 @@ export function todoSummary(todos) {
         return `全部完成：${todos.length} 个待办任务`;
     return `${open} 个待办未完成，共 ${todos.length} 个`;
 }
+// ---------------------------------------------------------------------------------------------
+// The `session_*` orchestrator tools: manage sibling conversations in the current workspace.
+//
+// WHY THESE TOOLS EXIST. A primary agent can already delegate a single transient job to a subagent
+// via `task` (a one-shot Pi process), or pipeline 2-8 steps via `workflow`. What was missing was the
+// ability to spin up INDEPENDENT, PERSISTENT sibling conversations in Super Pi — sessions that appear
+// in the workspace sidebar, carry their own full message history, run concurrently in the background,
+// and can be conversed with over multiple turns via `session_dispatch`, monitored via `session_status`,
+// or cancelled via `session_stop`.
+//
+// WHY THEY DIFFER FROM `task`. `task` runs an ephemeral child process: it has no conversation history,
+// cannot be conversed with across turns, does not appear in the sidebar, and dies upon returning its
+// final text. Sibling conversations are first-class Super Pi conversations: they retain their own
+// transcripts, can be opened and viewed by the user in the UI, and can execute complex multi-phase
+// work in parallel with the orchestrator.
+// ---------------------------------------------------------------------------------------------
+/**
+ * The orchestrator extension's half of the environment contract.
+ * `agents/super-pi-task/core.ts` is the other end; `scripts/task-tool.test.mjs` asserts the two copies agree.
+ */
+export const ORCHESTRATOR_ENDPOINT_ENV = "SUPER_PI_ORCHESTRATOR_ENDPOINT";
+/** Tool names registered with Pi. */
+export const SESSION_SPAWN_TOOL_NAME = "session_spawn";
+export const SESSION_STATUS_TOOL_NAME = "session_status";
+export const SESSION_DISPATCH_TOOL_NAME = "session_dispatch";
+export const SESSION_STOP_TOOL_NAME = "session_stop";
+/** Model-facing description for session_spawn. */
+export const SESSION_SPAWN_DESCRIPTION = `Create a new sibling conversation in the current workspace and immediately dispatch its initial task.
+
+DIFFERENCE FROM THE 'task' TOOL:
+- The 'task' tool delegates to a transient, one-shot subagent process (scout, critic, patcher) that runs once, returns its final text, and terminates. It has no conversation history and does not appear in the workspace sidebar.
+- 'session_spawn' creates a real, persistent sibling CONVERSATION in Super Pi. It appears in the sidebar, retains multi-turn message history, can receive follow-up messages via session_dispatch, can be inspected via session_status, and can be stopped via session_stop. The user can also switch to it in the Web UI.
+
+WHEN TO USE THIS:
+- Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.
+- Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.
+- When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.
+
+WHEN NOT TO USE THIS:
+- For one-off, focused delegation with a single answer: use 'task' (with scout/critic/patcher). It is faster, cheaper, and returns directly to your transcript.
+- For running shell commands or build watchers: use 'run_async'.
+- For a linear multi-step subagent pipeline: use 'workflow'.
+
+Usage notes:
+1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.
+2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.
+3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.`;
+/** Model-facing description for session_status. */
+export const SESSION_STATUS_DESCRIPTION = `Inspect the progress, run state, and latest activity of sibling conversations created by the orchestrator.
+
+WHEN TO USE THIS:
+- To check whether a spawned sibling conversation is still running, has finished (idle), is stopped, or encountered an error.
+- To read the latest assistant progress snippet without bloating your context with the session's entire raw message transcript.
+- To list all sibling conversations under your coordination when conversationId is omitted.
+
+Usage notes:
+1. When 'conversationId' is provided: returns a compact summary for that specific session, including its run status ('idle', 'running', 'waiting', 'stopped', 'failed'), messageCount, turnCount, lastAssistantSnippet, lastUserSnippet, activeTool, and error (if any).
+2. When 'conversationId' is omitted: returns a summary list of ALL sibling conversations spawned by this orchestrator session.
+3. This tool never returns full transcripts; it returns concise summaries and snippets to keep your context window lean.`;
+/** Model-facing description for session_dispatch. */
+export const SESSION_DISPATCH_DESCRIPTION = `Send a message, follow-up instructions, or steering guidance to an existing sibling conversation.
+
+WHEN TO USE THIS:
+- To follow up with a sibling session after reading its progress with session_status.
+- To give feedback, provide additional requirements, or answer a question from a sibling session.
+- To kick off a new turn on an idle or stopped sibling session.
+
+Usage notes:
+1. 'conversationId' is required and must identify an existing sibling conversation.
+2. 'content' is the text instruction sent to that session, just as if typed by a user in that session's chat.
+3. Dispatch is ASYNCHRONOUS by default: it enqueues the message into the session's queue and returns immediately.
+4. If the sibling session is currently busy running a turn, the dispatched message is placed in its waiting queue and processed when the active turn completes.`;
+/** Model-facing description for session_stop. */
+export const SESSION_STOP_DESCRIPTION = `Stop execution in a sibling conversation.
+
+WHEN TO USE THIS:
+- When a sibling session has gone down the wrong path, is stuck in an unwanted loop, or when the overall goal has changed and remaining work should be aborted.
+- To clear pending queued messages before they start running.
+
+Usage notes:
+1. 'mode' controls what to stop:
+   - 'all' (default): stops the currently running turn and cancels all pending queued messages in the session.
+   - 'active': only interrupts the active running turn; leaves any pending queued messages untouched.
+   - 'queued': only cancels pending queued messages; lets the currently running turn complete naturally.
+2. Use 'messageId' if you want to cancel or interrupt one specific queued message instead of all queued messages.`;

package/dist/server/types.d.ts

@@ -871,6 +871,29 @@ export type TodoItem = {
     status: "pending" | "in_progress" | "completed";
     priority?: "high" | "medium" | "low";
 };
+/** Summary of an orchestrated sibling session, returned by orchestrator queries. */
+export type OrchestratorSessionSummary = {
+    conversationId: string;
+    workspaceId: string;
+    title: string;
+    status: RunStatus;
+    origin: "user" | "orchestrator";
+    parentConversationId?: string;
+    task?: string;
+    messageCount: number;
+    turnCount: number;
+    lastAssistantSnippet?: string;
+    lastUserSnippet?: string;
+    hasPendingQuestion: boolean;
+    activeTool?: {
+        label: string;
+        detail?: string;
+    };
+    error?: string;
+    updatedAt: string;
+    createdAt?: number;
+    lastProgress?: string;
+};
 /**
  * What Pi reports about ITS OWN queue, forwarded to the browser as it arrives.
  *

package/dist/server/ws-server.d.ts

@@ -10,6 +10,21 @@ import type { CatalogService } from "./application/catalog-service.js";
  * a network peer that has disappeared can therefore make the buffer grow
  * without throwing.  Once this threshold is crossed we drop that connection
  * and let the normal close path clean up its resources.
+ *
+ * AND YET DROPPING IT IS THE WRONG ANSWER FOR A BUSY SERVER.  The threshold was
+ * written for a peer that has gone away - a frozen tab, a pulled cable.  A server
+ * that is merely DELIVERING TOO MUCH hits the same number: a sub-agent that
+ * streams text emits one `subagent.event` per delta, each of which asks for a
+ * full state broadcast, and a browser that cannot parse frames as fast as they
+ * arrive lets the buffer grow past the threshold while it is perfectly alive.
+ * The browser then reports code 1006 and reconnects, only to be dropped again -
+ * "连接中 / 断连 / 连接中" forever - and the user's work is interrupted rather
+ * than slowed.
+ *
+ * So a frame that does not fit is DROPPED, not the connection: the next frame
+ * carries the same state, and a browser that is behind will catch up on the next
+ * one instead of being disconnected and losing its place.  The connection is
+ * only terminated when the socket itself is gone (readyState is not OPEN).
  */
 export declare const MAX_WS_BUFFERED_BYTES: number;
 /** Maximum size of one inbound WebSocket message. Attachments are uploaded
@@ -34,7 +49,19 @@ export declare class WsBroadcaster implements EventBroadcaster {
     private readonly fileIndexScopes;
     private readonly coalescedSockets;
     private readonly pendingStreams;
-    private stateFlushScheduled;
+    /**
+     * DIAGNOSTIC ONLY - sends every requested state frame immediately instead of merging them.
+     *
+     * The legacy flood switch (`SUPER_PI_LEGACY_SUBAGENT_FLOOD=1`) restores the pre-fix WIRING: one
+     * full state broadcast per sub-agent event. But the 150ms merge window would still fold those
+     * broadcasts into one frame, so the "before" measurement would not actually be "before" - it
+     * would show a flood that the fixed server also survives, and the A/B comparison would prove
+     * nothing. This flag removes the window as well, so the probe can reproduce the real pre-fix
+     * wire shape: one frame per request, sent at once.
+     *
+     * Never set outside a probe or a regression test that is asserting the old behaviour.
+     */
+    private readonly sendStateImmediately;
     constructor(getState: (scope?: {
         conversationId?: string;
     }) => AppState);
@@ -51,7 +78,31 @@ export declare class WsBroadcaster implements EventBroadcaster {
     private enqueueStreaming;
     getSockets(): Set<WebSocket>;
     broadcast(event: ServerEvent): void;
+    /**
+     * BROADCAST STATES IN A TIME WINDOW, NOT IN A MICROTASK.
+     *
+     * The microtask flag this replaces merged only the calls that arrived within the
+     * SAME tick.  A sub-agent that streams text emits one `subagent.event` per delta,
+     * each asking for a full state broadcast, and those deltas arrive across many
+     * ticks - so a single sub-agent run could ask for HUNDREDS of full state
+     * broadcasts.  On a machine whose state is large, that is a flood the browser
+     * cannot drain: its parse queue falls behind, the socket buffer grows, and the
+     * connection is dropped (the browser reports 1006).
+     *
+     * A window turns a burst into a handful of frames.  The state a browser receives
+     * is the LATEST state - the intermediate ones carried nothing the last one did
+     * not - so nothing is lost by sending fewer of them.  The only thing that
+     * changes is how promptly the browser sees a change, and 150ms is below the
+     * threshold at which a person notices.
+     */
+    private stateFlushScheduled;
     broadcastState(): void;
+    private flushState;
+    /**
+     * Releases the pending state window, so a shutting-down server does not hold the event loop
+     * open on a timer whose flush would send to sockets that are already closed.
+     */
+    dispose(): void;
     getStateSnapshot(scope?: {
         conversationId?: string;
     }): AppState;

package/dist/server/ws-server.js

@@ -7,6 +7,21 @@ import { describeThrown, describeThrownWithStack } from "./failure-text.js";
  * a network peer that has disappeared can therefore make the buffer grow
  * without throwing.  Once this threshold is crossed we drop that connection
  * and let the normal close path clean up its resources.
+ *
+ * AND YET DROPPING IT IS THE WRONG ANSWER FOR A BUSY SERVER.  The threshold was
+ * written for a peer that has gone away - a frozen tab, a pulled cable.  A server
+ * that is merely DELIVERING TOO MUCH hits the same number: a sub-agent that
+ * streams text emits one `subagent.event` per delta, each of which asks for a
+ * full state broadcast, and a browser that cannot parse frames as fast as they
+ * arrive lets the buffer grow past the threshold while it is perfectly alive.
+ * The browser then reports code 1006 and reconnects, only to be dropped again -
+ * "连接中 / 断连 / 连接中" forever - and the user's work is interrupted rather
+ * than slowed.
+ *
+ * So a frame that does not fit is DROPPED, not the connection: the next frame
+ * carries the same state, and a browser that is behind will catch up on the next
+ * one instead of being disconnected and losing its place.  The connection is
+ * only terminated when the socket itself is gone (readyState is not OPEN).
  */
 export const MAX_WS_BUFFERED_BYTES = 8 * 1024 * 1024;
 /** Maximum size of one inbound WebSocket message. Attachments are uploaded
@@ -24,10 +39,12 @@ export function safeSend(socket, payload) {
         return false;
     const bufferedAmount = Number(socket.bufferedAmount ?? 0);
     if (Number.isFinite(bufferedAmount) && bufferedAmount > MAX_WS_BUFFERED_BYTES) {
-        try {
-            socket.terminate();
-        }
-        catch { /* close races are already being cleaned up */ }
+        // DROP THE FRAME, KEEP THE CONNECTION.  A peer that is merely behind is not
+        // a peer that is gone: the next broadcast carries the same state, so the
+        // browser catches up instead of being disconnected and losing its place.
+        // Terminating here is what produced "连接中 / 断连 / 连接中" forever on a
+        // server that was delivering sub-agent output faster than the browser could
+        // parse it - and the browser's own code 1006 was only the symptom.
         return false;
     }
     try {
@@ -56,7 +73,19 @@ export class WsBroadcaster {
     fileIndexScopes = new Map();
     coalescedSockets = new Set();
     pendingStreams = new Map();
-    stateFlushScheduled = false;
+    /**
+     * DIAGNOSTIC ONLY - sends every requested state frame immediately instead of merging them.
+     *
+     * The legacy flood switch (`SUPER_PI_LEGACY_SUBAGENT_FLOOD=1`) restores the pre-fix WIRING: one
+     * full state broadcast per sub-agent event. But the 150ms merge window would still fold those
+     * broadcasts into one frame, so the "before" measurement would not actually be "before" - it
+     * would show a flood that the fixed server also survives, and the A/B comparison would prove
+     * nothing. This flag removes the window as well, so the probe can reproduce the real pre-fix
+     * wire shape: one frame per request, sent at once.
+     *
+     * Never set outside a probe or a regression test that is asserting the old behaviour.
+     */
+    sendStateImmediately = process.env.SUPER_PI_LEGACY_SUBAGENT_FLOOD === "1";
     constructor(getState) {
         this.getState = getState;
     }
@@ -137,6 +166,19 @@ export class WsBroadcaster {
             pending = { events, timer: setTimeout(() => this.flushStreaming(socket), 16) };
             this.pendingStreams.set(socket, pending);
         }
+        // A subagent.event is a whole-run SNAPSHOT whose output is the accumulated text so far: within one
+        // 16ms window the LATEST snapshot for a run supersedes every earlier one (they differ only by more
+        // text). Keeping the newest replaces a per-delta frame burst with at most one frame per run per
+        // window - the O(n²) burst the flood fix exists for - while the card still updates at ~60fps.
+        if (event.type === "subagent.event") {
+            const superseded = pending.events.findIndex((queued) => queued.type === "subagent.event" && queued.run.id === event.run.id);
+            if (superseded >= 0) {
+                pending.events[superseded] = event;
+                return;
+            }
+            pending.events.push(event);
+            return;
+        }
         // Only adjacent fragments from the same stream can merge. A different kind,
         // answer offset or lifecycle flag is an ordering boundary, even within 16ms.
         const previous = pending.events.at(-1);
@@ -156,7 +198,7 @@ export class WsBroadcaster {
             this.broadcastState();
             return;
         }
-        const streaming = event.type === "message.delta" || event.type === "message.thinking";
+        const streaming = event.type === "message.delta" || event.type === "message.thinking" || event.type === "subagent.event";
         // Serialize common events once, after finding a recipient. Coalesced text stays per socket;
         // conversation snapshots are projected and serialized once per scope in broadcastState().
         let payload;
@@ -173,41 +215,90 @@ export class WsBroadcaster {
             }
         }
     }
+    /**
+     * BROADCAST STATES IN A TIME WINDOW, NOT IN A MICROTASK.
+     *
+     * The microtask flag this replaces merged only the calls that arrived within the
+     * SAME tick.  A sub-agent that streams text emits one `subagent.event` per delta,
+     * each asking for a full state broadcast, and those deltas arrive across many
+     * ticks - so a single sub-agent run could ask for HUNDREDS of full state
+     * broadcasts.  On a machine whose state is large, that is a flood the browser
+     * cannot drain: its parse queue falls behind, the socket buffer grows, and the
+     * connection is dropped (the browser reports 1006).
+     *
+     * A window turns a burst into a handful of frames.  The state a browser receives
+     * is the LATEST state - the intermediate ones carried nothing the last one did
+     * not - so nothing is lost by sending fewer of them.  The only thing that
+     * changes is how promptly the browser sees a change, and 150ms is below the
+     * threshold at which a person notices.
+     */
+    stateFlushScheduled = false;
     broadcastState() {
+        // DIAGNOSTIC PATH: the pre-fix wire shape, one frame per request, no merge window.
+        if (this.sendStateImmediately) {
+            this.flushState();
+            return;
+        }
         if (this.stateFlushScheduled)
             return;
         this.stateFlushScheduled = true;
+        const now = Date.now();
+        // HOW MANY STATE FRAMES WENT OUT IN THE LAST SECOND.
+        //
+        // This is the flood detector, and it is a RATE, not a delay. A server that is behaving sends a
+        // handful of frames a second: one per user action, one per turn boundary. A server that is
+        // flooding sends hundreds - a sub-agent's delta used to ask for one full state frame each.
+        //
+        // The NORMAL path stays exactly as it always was: a microtask merge, so the frame goes out at the
+        // end of this tick. That matters for more than latency: "the user sent a message" and "the turn
+        // opened" are two broadcasts, and if they are merged into one frame the user's own message never
+        // appears on its own - it appears already accompanied by the assistant placeholder. A message
+        // that arrives half-written is a message the user does not believe they sent.
+        //
+        // The DEGRADED path is for a server that is genuinely flooding: requests are then merged into one
+        // frame per window, because a browser that cannot parse frames as fast as they arrive gets its
+        // connection dropped (the browser reports 1006) and the user sees "连接中 / 断连 / 连接中".
         queueMicrotask(() => {
             this.stateFlushScheduled = false;
-            const groups = new Map();
-            for (const socket of this.sockets) {
-                if (socket.readyState !== WebSocket.OPEN)
-                    continue;
-                const scope = this.scopes.get(socket);
-                const key = scope ? `focused:${JSON.stringify(scope.conversationId ?? null)}` : "legacy";
-                let group = groups.get(key);
-                if (!group) {
-                    group = { scope, sockets: [] };
-                    groups.set(key, group);
-                }
-                group.sockets.push(socket);
+            this.flushState();
+        });
+    }
+    flushState() {
+        const groups = new Map();
+        for (const socket of this.sockets) {
+            if (socket.readyState !== WebSocket.OPEN)
+                continue;
+            const scope = this.scopes.get(socket);
+            const key = scope ? `focused:${JSON.stringify(scope.conversationId ?? null)}` : "legacy";
+            let group = groups.get(key);
+            if (!group) {
+                group = { scope, sockets: [] };
+                groups.set(key, group);
             }
-            for (const { scope, sockets } of groups.values()) {
-                const snapshotStartedAt = performance.now();
-                const state = this.getState(scope);
-                const snapshotMs = performance.now() - snapshotStartedAt;
-                const serializeStartedAt = performance.now();
-                const cachedStatePayload = JSON.stringify({ type: "state", state });
-                const serializeMs = performance.now() - serializeStartedAt;
-                if (process.env.SUPER_PI_TRACE_LATENCY === "1") {
-                    console.warn(`[super-pi latency] phase=state.snapshot.ready bytes=${Buffer.byteLength(cachedStatePayload, "utf8")} snapshotMs=${Math.round(snapshotMs)} serializeMs=${Math.round(serializeMs)} sockets=${sockets.length} scope=${scope ? "focused" : "legacy"}`);
-                }
-                for (const socket of sockets) {
-                    this.flushStreaming(socket);
-                    safeSend(socket, cachedStatePayload);
-                }
+            group.sockets.push(socket);
+        }
+        for (const { scope, sockets } of groups.values()) {
+            const snapshotStartedAt = performance.now();
+            const state = this.getState(scope);
+            const snapshotMs = performance.now() - snapshotStartedAt;
+            const serializeStartedAt = performance.now();
+            const cachedStatePayload = JSON.stringify({ type: "state", state });
+            const serializeMs = performance.now() - serializeStartedAt;
+            if (process.env.SUPER_PI_TRACE_LATENCY === "1") {
+                console.warn(`[super-pi latency] phase=state.snapshot.ready bytes=${Buffer.byteLength(cachedStatePayload, "utf8")} snapshotMs=${Math.round(snapshotMs)} serializeMs=${Math.round(serializeMs)} sockets=${sockets.length} scope=${scope ? "focused" : "legacy"}`);
             }
-        });
+            for (const socket of sockets) {
+                this.flushStreaming(socket);
+                safeSend(socket, cachedStatePayload);
+            }
+        }
+    }
+    /**
+     * Releases the pending state window, so a shutting-down server does not hold the event loop
+     * open on a timer whose flush would send to sockets that are already closed.
+     */
+    dispose() {
+        this.stateFlushScheduled = false;
     }
     getStateSnapshot(scope) {
         return this.getState(scope);
@@ -269,8 +360,30 @@ export class WsServer {
     setupConnectionHandling() {
         this.websocketServer.on("connection", (socket, request) => {
             const url = new URL(request.url ?? "/ws", "http://localhost");
-            const scope = url.searchParams.get("state") === "focused"
-                ? { conversationId: url.searchParams.get("conversationId") || undefined } : undefined;
+            // HOW A CLIENT ASKS FOR A SCOPE, AND WHAT IT GETS WHEN IT DOES NOT ASK.
+            //
+            // `undefined` means the WHOLE application: every workspace, every conversation and every
+            // message.  On a machine with a long history that is tens of megabytes in the FIRST FRAME.
+            //
+            // There are three cases, and they are NOT the same thing:
+            //
+            //   ?state=focused            -> the focused projection (sidebar + the selected transcript)
+            //   ?conversationId=<id>      -> the focused projection of that one conversation
+            //   (neither)                 -> the legacy full state, exactly as before this change
+            //
+            // The middle case is what the current browser sends (it sends both).  The third case is a
+            // client running an OLD bundle, and it MUST keep getting the full state: a focused frame
+            // with no conversationId carries NO transcripts at all, so an old client that never sends
+            // `state.subscribe` would connect and see an empty application.  Dropping it silently is
+            // worse than a big first frame.
+            //
+            // And the big first frame is no longer FATAL: `safeSend` drops an oversized frame instead
+            // of terminating the connection, so a browser that cannot digest 42 MB at once is merely
+            // SLOW on that first frame - it is not disconnected, and it does not enter the
+            // "连接中 / 断连 / 连接中" loop.  The disconnect is fixed at the buffer, not at the scope.
+            const wantsFocused = url.searchParams.get("state") === "focused";
+            const conversationId = url.searchParams.get("conversationId") || undefined;
+            const scope = wantsFocused || conversationId ? { conversationId } : undefined;
             this.broadcaster.register(socket, scope);
             socket.on("error", (error) => {
                 console.warn(`Super Pi: WebSocket error: ${error instanceof Error ? error.message : String(error)}`);
@@ -450,6 +563,9 @@ export class WsServer {
      * Gracefully closes all active WebSocket connections and terminates the server.
      */
     close() {
+        // A pending state window must not outlive the server: the timer holds the event loop
+        // open, and a flush after the sockets are closed would send to a dead peer.
+        this.broadcaster.dispose();
         for (const socket of this.broadcaster.getSockets()) {
             socket.close(1001, "server-shutdown");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -74,12 +74,13 @@
     "scripts/image-input-real-pi.test.mjs",
     "scripts/image-upload.test.mjs",
     "scripts/extension-ui-e2e.test.mjs",
-    "scripts/session-picker.test.mjs",
+    "scripts/session-picker.test.mjs", "scripts/session-orchestrator.test.mjs", "scripts/session-orchestrator-tools.test.mjs",
     "scripts/workspace-cwd.test.mjs",
     "scripts/subagents.test.mjs",
     "scripts/subagent-noise.test.mjs",
     "scripts/subagent-response-receipt.test.mjs",
     "scripts/subagent-runs.test.mjs",
+    "scripts/ws-flood-regression.test.mjs",
     "scripts/conversation-reconcile.test.mjs",
     "scripts/subagent-dispatch.test.mjs",
     "scripts/workflow-plan.test.mjs",