@somewhatintelligent/cc-ws-client 0.1.0 → 0.1.4

package/README.md

@@ -12,5 +12,3 @@ session.sendMessage("Hello");
 // - @somewhatintelligent/cc-ws-react
 // - @somewhatintelligent/cc-ws-svelte (workspace-only for now)
 ```
-
-See `LIB-DESIGN.md` in the source repo for the wire protocol.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somewhatintelligent/cc-ws-client",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Framework-agnostic reactive WebSocket client for the cc-ws Claude Code bridge protocol.",
   "license": "MIT",
   "type": "module",

package/src/controls.ts

@@ -1,8 +1,3 @@
-// Control-request layer. Tracks every outbound control_request by request_id
-// and resolves a Promise when its matching control_response arrives. Higher
-// layers (session.ts) compose this for set_permission_mode / set_model /
-// get_settings / file_suggestions / interrupt / end_session.
-
 import {
   isControlResponse,
   makeRequestId,
@@ -11,9 +6,7 @@ import {
 } from "./protocol";
 import type { WsClient } from "./ws";
 
-// The wrapper carries the canonical control_response payload (we hand
-// both back so callers that need the request_id or subtype can dig in;
-// most just read .inner).
+// Callers that need request_id/subtype use .wrapper; most just read .inner
 export type ControlResponseResult = {
   inner: unknown;
   wrapper: { subtype: "success"; request_id: string; response?: unknown };
@@ -30,14 +23,9 @@ export type ControlsClient = {
     request: OutboundControlRequestSubtype,
     opts?: { timeoutMs?: number },
   ) => Promise<ControlResponseResult>;
-  // For frames we DIDN'T initiate (can_use_tool comes IN as control_request).
-  // Returns true if the frame was handled (we matched it to an in-flight
-  // request).
   ingest: (frame: InboundFrame) => boolean;
-  // Reject every in-flight request with `reason`. Called from session
-  // respawn/disconnect — the bridge kills the old claude child the
-  // moment we send respawn, so any outstanding control_request would
-  // otherwise hang against a dead pipe until its timeoutMs fires.
+  // Bridge kills the claude child on respawn, so in-flight requests would
+  // otherwise hang against a dead pipe until timeoutMs fires
   abortAll: (reason: string) => void;
 };
 
@@ -67,8 +55,7 @@ export function createControlsClient(ws: WsClient): ControlsClient {
 
   function ingest(frame: InboundFrame): boolean {
     if (!isControlResponse(frame)) return false;
-    // Real binary wire format may put request_id either at the outer
-    // envelope OR inside response. Check both before giving up.
+    // Real binary may put request_id on outer envelope OR inside response
     const id = frame.response.request_id ?? frame.request_id;
     if (!id) return false;
     const r = inflight.get(id);

package/src/messages.ts

@@ -1,12 +1,6 @@
-// Conversation log. Holds:
-//   - Local user echoes (sent prompts mirrored into the chat).
-//   - Raw inbound frames (assistant, user, result, control_*, etc).
-//   - In-flight assistant messages reconstructed from `stream_event` deltas.
-//
-// The `messages` atom is the canonical timeline. Streaming messages live as
-// entries with kind:"streaming"; when the canonical `assistant` envelope
-// arrives, the streaming entry is removed and replaced by the final
-// `frame` entry (the renderer treats the assistant frame as authoritative).
+// Streaming entries (rebuilt from stream_event deltas) are replaced by
+// the canonical `frame` entry once the `assistant` envelope arrives —
+// the envelope is authoritative.
 
 import { atom, type WritableAtom } from "nanostores";
 import type { InboundFrame, StreamEvent } from "./protocol";
@@ -19,11 +13,10 @@ export type ToolUseBlock = {
   id: string;
   name: string;
   input: unknown;
-  // partial_json deltas accumulate here, parsed into `input` on
-  // content_block_stop. _parsed flips true once parsed (or on empty input
-  // close).
-  _partialJson: string;
-  _parsed: boolean;
+  // Renderers read partialJson before content_block_stop to show
+  // streaming tool inputs while the JSON is still open
+  partialJson: string;
+  parsed: boolean;
 };
 export type ThinkingBlock = { type: "thinking"; thinking: string };
 export type StreamingBlock = TextBlock | ToolUseBlock | ThinkingBlock;
@@ -65,21 +58,16 @@ export type MessageEntry = LocalUserEntry | FrameEntry | StreamingEntry;
 export type MessagesController = {
   messages: WritableAtom<MessageEntry[]>;
   activeStreamId: WritableAtom<string | null>;
-  // Bumps on every non-streaming change (pushFrame / pushLocalUser /
-  // dropStreaming / reset / hydrate). Stays still during streaming
-  // deltas. Persistence and other "save on stable change" consumers
-  // should subscribe to this rather than `messages` to avoid paying
-  // a serialization tax once per 250ms while a turn is streaming.
+  // Bumps on non-streaming changes only; subscribe to this (not
+  // `messages`) for save-on-stable-change to skip the per-token churn
   revision: WritableAtom<number>;
   pushLocalUser: (text: string) => void;
   pushFrame: (frame: InboundFrame) => void;
-  // Returns true if the frame was consumed by the streaming machinery and
-  // should NOT be appended to the timeline as a frame entry.
+  // Returns true when the streaming machinery consumed the frame; the
+  // caller MUST NOT also append it as a frame entry
   ingest: (frame: InboundFrame) => boolean;
   reset: () => void;
-  // Replace the timeline with a saved snapshot (used by persistence on
-  // reload). Streaming entries are dropped — they're transient and don't
-  // round-trip through serialization.
+  // Streaming entries are dropped — they don't round-trip through serialization
   hydrate: (entries: MessageEntry[]) => void;
 };
 
@@ -90,11 +78,9 @@ export function createMessagesController(): MessagesController {
   function bumpRevision() {
     revision.set(revision.get() + 1);
   }
-  // Streaming reconstructions, keyed by message id. Mutated in place; each
-  // delta bumps the messages atom by emitting a new array reference so
-  // subscribers re-render. We accept the array-replacement cost for the
-  // simpler reactivity contract — there's typically ≤1 active streaming
-  // message at a time.
+  // Mutated in place — there's typically ≤1 active streaming message,
+  // so the array-replace-per-delta cost beats a more complex reactivity
+  // contract
   const streaming = new Map<string, InFlightMessage>();
   let arrivalCounter = 0;
 
@@ -138,10 +124,9 @@ export function createMessagesController(): MessagesController {
   }
 
   function bumpStreaming(id: string) {
-    // Per-token rebump. Replace just the streaming entry's identity so
-    // subscribers re-render — the streaming entry always lives at the
-    // tail (we never push frames after a stream starts until message_stop)
-    // so we can mutate the array in place rather than scan with .map.
+    // The streaming entry lives at the tail until message_stop (no
+    // frames are pushed during a stream), so we can mutate the array
+    // in place rather than scan with .map
     const msg = streaming.get(id);
     if (!msg) return;
     const arr = messages.get();
@@ -194,8 +179,8 @@ export function createMessagesController(): MessagesController {
           id: cb.id ?? "",
           name: cb.name ?? "",
           input: cb.input ?? {},
-          _partialJson: "",
-          _parsed: false,
+          partialJson: "",
+          parsed: false,
         };
       } else if (cb.type === "thinking") {
         block = { type: "thinking", thinking: cb.thinking ?? "" };
@@ -219,7 +204,7 @@ export function createMessagesController(): MessagesController {
         delta.type === "input_json_delta" &&
         typeof delta.partial_json === "string"
       ) {
-        block._partialJson += delta.partial_json;
+        block.partialJson += delta.partial_json;
       } else if (
         block?.type === "thinking" &&
         delta.type === "thinking_delta" &&
@@ -235,16 +220,16 @@ export function createMessagesController(): MessagesController {
       const msg = id ? streaming.get(id) : null;
       if (!msg) return;
       const block = msg.content[ev.index];
-      if (block?.type === "tool_use" && !block._parsed) {
-        if (block._partialJson) {
+      if (block?.type === "tool_use" && !block.parsed) {
+        if (block.partialJson) {
           try {
-            block.input = JSON.parse(block._partialJson);
-            block._parsed = true;
+            block.input = JSON.parse(block.partialJson);
+            block.parsed = true;
           } catch (err) {
-            console.warn("[stream_event] tool_use partial_json parse failed", err, block._partialJson);
+            console.warn("[stream_event] tool_use partial_json parse failed", err, block.partialJson);
           }
         } else {
-          block._parsed = true;
+          block.parsed = true;
         }
       }
       bumpStreaming(id!);
@@ -260,13 +245,10 @@ export function createMessagesController(): MessagesController {
 
   function ingest(frame: InboundFrame): boolean {
     if (!("type" in frame)) return false;
-    // Streaming deltas: consume and never append the raw frame.
     if (frame.type === "stream_event" && frame.event) {
       applyStreamEvent(frame.event);
       return true;
     }
-    // Canonical assistant envelope: drop any matching streaming reconstruction
-    // (the envelope is authoritative), then append the frame.
     if (frame.type === "assistant" && frame.message?.id) {
       const id = frame.message.id;
       if (streaming.has(id)) dropStreaming(id);
@@ -282,8 +264,8 @@ export function createMessagesController(): MessagesController {
     const filtered = entries.filter(
       (e): e is LocalUserEntry | FrameEntry => e.kind === "frame" || e.kind === "local_user",
     );
-    // Reseat arrivalCounter past the last hydrated entry so subsequent
-    // pushes don't collide with restored ids in render order.
+    // Reseat past the last hydrated entry so subsequent pushes don't
+    // collide with restored ids in render order
     arrivalCounter = filtered.length > 0
       ? Math.max(...filtered.map((e) => e.arrivalIdx)) + 1
       : 0;

package/src/permissions.ts

@@ -1,15 +1,7 @@
-// can_use_tool gate. The binary sends INBOUND control_request frames with
-// subtype:"can_use_tool" when --permission-prompt-tool=stdio is set. We must
-// reply with a CanUseToolResponseFrame (nested envelope) carrying either an
-// allow or a deny.
-//
-// Two consumer surfaces share the same machinery:
-//   1. promise callback — pass `onCanUseTool` to createCcSession; we resolve
-//      it for each request and dispatch the result.
-//   2. queue + respondToPermission — subscribe to the `pendingPermissions`
-//      atom, render UI, call respondToPermission(id, decision).
-// If `onCanUseTool` is provided it wins; the queue is then transient and
-// callers should not consume it from UI.
+// With --permission-prompt-tool=stdio the binary sends inbound
+// control_request{subtype:"can_use_tool"} and waits for a nested
+// control_response. If onCanUseTool is provided it wins; the queue
+// is then transient and callers should not consume it from UI.
 
 import { atom, type WritableAtom } from "nanostores";
 import {
@@ -24,7 +16,7 @@ export type PermissionDecision =
   | { behavior: "deny"; message?: string };
 
 export type PendingPermission = {
-  id: string;          // request_id we'll reply to
+  id: string;
   toolName: string;
   input: unknown;
   raw: CanUseToolRequest;
@@ -38,9 +30,8 @@ export type PermissionsController = {
   pendingPermissions: WritableAtom<PendingPermission[]>;
   ingest: (frame: InboundFrame) => boolean;
   respond: (id: string, decision: PermissionDecision) => void;
-  // Drop every queued can_use_tool request without replying. Called by
-  // session respawn/disconnect — the issuing claude is dead, so any reply
-  // would go nowhere; the queue is stale UI clutter.
+  // After respawn/disconnect the issuing claude is dead, so replies
+  // would go nowhere; queue is stale UI clutter
   clearQueue: () => void;
 };
 
@@ -83,7 +74,6 @@ export function createPermissionsController(opts: {
       raw: cr,
     };
     if (opts.onCanUseTool) {
-      // Promise-style: resolve immediately, never enqueue.
       Promise.resolve(opts.onCanUseTool(entry))
         .then((decision) => reply(entry.id, decision, entry.input))
         .catch((err) => {
@@ -91,7 +81,6 @@ export function createPermissionsController(opts: {
           reply(entry.id, { behavior: "deny", message: "handler error" }, entry.input);
         });
     } else {
-      // Queue-style: append for the consumer to handle via respond().
       pendingPermissions.set([...pendingPermissions.get(), entry]);
     }
     return true;

package/src/persistence.ts

@@ -1,7 +1,6 @@
-// Local-storage persistence: sessionId + visible message timeline + active
-// mode/model/effort. Without this, --continue restores claude's internal
-// context but doesn't restream prior turns over stream-json — refresh would
-// land on an empty bubble list.
+// --continue restores claude's internal context but doesn't restream
+// prior turns over stream-json, so without local persistence a refresh
+// lands on an empty bubble list.
 
 import type { MessagesController, MessageEntry } from "./messages";
 import type { Effort, PermissionMode } from "./modes";
@@ -17,8 +16,6 @@ export type CcPersistenceOptions = {
   enabled?: boolean;
   storage?: StorageLike;
   key?: string;
-  // Cap on serialized message entries. Streaming entries are never
-  // persisted (transient by definition).
   maxMessages?: number;
 };
 
@@ -40,8 +37,7 @@ export function resolvePersistence(
   opt: CcPersistenceOptions | false | undefined,
 ): PersistenceConfig | null {
   if (opt === false) return null;
-  // Default to localStorage in browsers; null on the server so SSR doesn't
-  // crash on missing globals.
+  // Null on server keeps SSR off the missing-globals cliff
   const g = globalThis as { localStorage?: StorageLike };
   const defaultStorage: StorageLike | null = g.localStorage ?? null;
   const storage = opt?.storage ?? defaultStorage;
@@ -68,8 +64,8 @@ export function loadPersisted(cfg: PersistenceConfig): PersistedShape | null {
 
 export function savePersisted(cfg: PersistenceConfig, payload: PersistedShape): void {
   try {
-    // Streaming entries are transient; serializing would resurrect a
-    // half-decoded message on reload. Keep frame + local_user only.
+    // Serializing streaming entries would resurrect a half-decoded
+    // message on reload; keep frame + local_user only
     const trimmed: PersistedShape = { ...payload };
     if (Array.isArray(payload.messages)) {
       const filtered = payload.messages.filter(
@@ -79,16 +75,14 @@ export function savePersisted(cfg: PersistenceConfig, payload: PersistedShape):
     }
     cfg.storage.setItem(cfg.key, JSON.stringify(trimmed));
   } catch {
-    // Persistence is best-effort UX, not a correctness requirement.
+    // Best-effort UX, not a correctness requirement
   }
 }
 
-// Wires up debounced save-on-change for the relevant atoms. We subscribe
-// to messagesCtrl.revision (only bumps on non-streaming changes) rather
-// than `messages` directly — otherwise every streaming token kicks the
-// 250ms timer and we serialize the entire timeline every 250ms during a
-// turn for changes that are about to be discarded by the streaming-entry
-// filter in savePersisted anyway.
+// Subscribe to messagesCtrl.revision (bumps only on non-streaming changes),
+// not `messages` directly — otherwise every streaming token kicks the
+// 250ms timer to re-serialize a timeline that the streaming-entry filter
+// in savePersisted would discard anyway.
 export function installPersistenceWriter(args: {
   persistence: PersistenceConfig;
   init: ReadableAtom<{ sessionId: string | null }>;

package/src/protocol.ts

@@ -1,15 +1,10 @@
-// Wire protocol — every JSON shape exchanged between the browser and the
-// bridge. Two channels share the same WS:
-//   1. Claude Code stream-json frames (forwarded verbatim to/from the child).
-//   2. _local frames (intercepted by the bridge, never reach the child).
-//
-// Field sets are pulled from the binary's own runtime Zod schemas. Run
-// `bun packages/client/scripts/extract-claude-schemas.ts extract` against
-// the active `claude` binary to reproduce — see scripts/README.md for the
-// runbook + drift-detection workflow. Variants we don't actively consume
-// still ride the same discriminated union so consumers can narrow
-// without `as any` escape hatches. Unknown system subtypes fall through
-// to UnknownSystemFrame. Pinned to v2.1.129 (2026-05-05).
+// Field sets pulled from the binary's runtime Zod schemas via
+// scripts/extract-claude-schemas.ts (see scripts/README.md). Pinned to
+// v2.1.129 (2026-05-05). Unknown system subtypes fall through to
+// UnknownSystemFrame so unmodelled variants don't break narrowing.
+// Two channels share the WS: Claude Code stream-json frames forwarded
+// verbatim to/from the child, and `_local` frames intercepted by the
+// bridge.
 
 // ---------- shared ----------
 
@@ -184,8 +179,7 @@ export type SystemTaskNotification = {
   session_id?: string;
 };
 
-// task_updated.patch is a wire-safe subset of TaskState fields that changed.
-// Mergeable into the local task map. Excludes abortController/messages/result.
+// Wire-safe subset of TaskState; excludes abortController/messages/result
 export type TaskUpdatedPatch = {
   status?: "running" | "completed" | "failed" | "killed" | "stopped" | string;
   description?: string;
@@ -258,10 +252,8 @@ export type SystemFrame =
   | SystemLocalCommandOutput
   | SystemCompactBoundary;
 
-// Catch-all for system subtypes the binary may emit but the lib doesn't
-// model. Sits OUTSIDE SystemFrame so narrowing on a known subtype yields
-// a single specific variant; consumers that need the broad case (e.g.
-// renderers showing every system frame) accept SystemFrame | UnknownSystemFrame.
+// Outside SystemFrame so narrowing on a known subtype yields a single
+// specific variant; broad consumers accept SystemFrame | UnknownSystemFrame
 export type UnknownSystemFrame = {
   type: "system";
   subtype: string;
@@ -341,8 +333,6 @@ export type CanUseToolControlRequest = {
   permission_suggestions?: unknown[];
 };
 
-// Other inbound control_request subtypes the lib may receive but doesn't
-// drive UI off of. We accept them with subtype + an opaque payload.
 export type UnknownControlRequest = {
   subtype: string;
 };
@@ -372,8 +362,7 @@ export type ControlResponseError = {
 export type ControlResponseFrame = {
   type: "control_response";
   response: ControlResponseSuccess | ControlResponseError;
-  // Some bridge variants put request_id at the outer level. Keep optional
-  // for forward compatibility; consumers should prefer response.request_id.
+  // Some bridges put request_id outside; prefer response.request_id
   request_id?: string;
 };
 
@@ -412,7 +401,6 @@ export type BashCommandFrame = {
   command: string;
 };
 
-// Outbound control_request subtypes we use. Nested envelope.
 export type OutboundControlRequestSubtype =
   | { subtype: "interrupt" }
   | { subtype: "set_permission_mode"; mode: string }
@@ -429,7 +417,6 @@ export type OutboundControlRequestFrame = {
   request: OutboundControlRequestSubtype;
 };
 
-// Reply to a can_use_tool control_request. Nested envelope.
 export type CanUseToolResponseFrame = {
   type: "control_response";
   response: {
@@ -460,10 +447,8 @@ export function makeRequestId(): string {
   return crypto.randomUUID();
 }
 
-// Translate a SessionMode + extras into the CLI flag list for the spawn
-// (consumed by the bridge via _local:respawn). Effort and model are spawn-
-// time only at present (no set_effort control_request exists; --model picks
-// the launch model and set_model can change it later).
+// Effort is spawn-time only (no set_effort control_request); --model
+// picks the launch model and set_model can change it later
 export function buildSpawnArgs(opts: {
   mode: SessionMode;
   effort?: string;
@@ -485,8 +470,6 @@ export function buildSpawnArgs(opts: {
   return args;
 }
 
-// Discriminator helpers — narrow once, reuse the type guard.
-
 export function isSystemFrame(f: InboundFrame): f is SystemFrame | UnknownSystemFrame {
   return (f as { type?: unknown }).type === "system";
 }
@@ -519,7 +502,6 @@ export function isLocalRespawnResult(f: InboundFrame): f is LocalRespawnResultFr
   return (f as { _local?: unknown })._local === "respawnResult";
 }
 
-// Backwards-compat: existing call sites expect this name.
 export type CanUseToolRequest = ControlRequestFrame & {
   request: CanUseToolControlRequest;
 };

package/src/session.ts

@@ -1,6 +1,3 @@
-// Session controller — composes ws + messages + controls + permissions into a
-// single reactive client. See LIB-DESIGN.md for the full API contract.
-
 import { atom, type ReadableAtom } from "nanostores";
 import { createControlsClient } from "./controls";
 import { createMessagesController, type MessageEntry } from "./messages";
@@ -48,16 +45,14 @@ export type HookEntry = {
 export type { ShellEntry, ShellSource } from "./shell";
 export type { TaskEntry, TaskStatus, TaskUsage } from "./tasks";
 
-// hookEvents is plain FIFO drop-oldest — long-running sessions with chatty
-// hooks accumulate thousands of entries otherwise.
+// Long-running sessions with chatty hooks would otherwise accumulate
+// thousands of entries
 const HOOK_EVENTS_CAP = 200;
 
 function capRingFifo<T>(arr: T[], cap: number): T[] {
   return arr.length > cap ? arr.slice(arr.length - cap) : arr;
 }
 
-// session_state_changed: tracks whether claude is mid-turn or idle. Useful
-// for UI affordances (show / hide spinner; prevent send while busy).
 export type SessionState = "idle" | "running" | "requires_action" | "unknown";
 
 export type InitData = {
@@ -107,9 +102,7 @@ export type CcSessionOptions = {
   onCanUseTool?: OnCanUseTool;
   onTrace?: (dir: "in" | "out", line: string) => void;
   persistence?: CcPersistenceOptions | false;
-  // Test seam: inject a pre-built WS client (e.g. an in-memory fake) instead
-  // of constructing one from `url`. The injected client must satisfy the
-  // same WsClient contract.
+  // Test seam — injected client must satisfy the WsClient contract
   wsClient?: WsClient;
 };
 
@@ -130,9 +123,7 @@ export type CcSession = {
   newSession: () => Promise<void>;
   continueSession: () => Promise<void>;
   resumeSession: (sessionId: string) => Promise<void>;
-  // Stop a single task by id (any type — bash, agent, teammate). Maps to
-  // the stop_task control_request. Use over interrupt() when you want to
-  // kill a specific bg task without ending the whole turn.
+  // Use over interrupt() to kill one bg task without ending the whole turn
   stopTask: (taskId: string) => Promise<void>;
   respondToPermission: (id: string, decision: PermissionDecision) => void;
   fetchFileSuggestions: (query: string) => Promise<Array<{ path: string; score?: number }>>;
@@ -147,27 +138,22 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   const messagesCtrl = createMessagesController();
   const permissions = createPermissionsController({ ws, onCanUseTool: opts.onCanUseTool });
   const tasksCtrl = createTasksController();
-  // Shell controller takes a thunk for sendMessage because both the
-  // controller and sendMessage live inside this factory; the thunk lets
-  // the controller's queued follow-up text fire sendMessage() after the
-  // bash exchange XML lands in the buffer.
+  // Thunk because sendMessage is defined later in this factory; the
+  // controller's queued follow-up needs to fire sendMessage() after the
+  // bash exchange XML lands in the buffer
   const shellCtrl = createShellController({
     ws,
     sendMessage: (text: string) => sendMessage(text),
   });
 
   // ---- persistence ----
-  // We hydrate from storage BEFORE constructing initial state so saved
-  // values feed the atoms' initial values rather than overwriting them
-  // after subscribers have already rendered.
+  // Hydrate BEFORE constructing initial atom state so saved values feed
+  // the initial values, not overwrite them post-render
   const persistence = resolvePersistence(opts.persistence);
   const persisted = persistence ? loadPersisted(persistence) : null;
 
-  // Spawn args, kept up-to-date as the user changes mode/model/effort. Used
-  // when respawning (effort change, session lifecycle change) so the new
-  // child inherits the user's selections. If persistence has a stored
-  // sessionId, the initial mode becomes resume(stored) — this is the
-  // post-refresh path that brings the user back to their last thread.
+  // Persisted sessionId routes the initial spawn through resume(stored) —
+  // this is the post-refresh path back to the user's last thread
   const initialMode: SessionMode = opts.args?.mode
     ?? (persisted?.sessionId ? { kind: "resume", sessionId: persisted.sessionId } : { kind: "continue" });
   let currentArgs: NonNullable<CcSessionOptions["args"]> = {
@@ -203,9 +189,7 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   const tasks = tasksCtrl.tasks;
   const sessionState = atom<SessionState>("unknown");
 
-  // Hydrate the message timeline from persisted snapshot if any. Doing
-  // this BEFORE wiring the atom listener avoids a feedback loop where
-  // hydration triggers a save (it's idempotent but wasteful).
+  // BEFORE installPersistenceWriter so hydration doesn't kick a save
   if (persisted?.messages && Array.isArray(persisted.messages)) {
     messagesCtrl.hydrate(persisted.messages);
   }
@@ -221,8 +205,8 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
     });
   }
 
-  // Transient errors auto-clear after 5s. Each pending update cancels the
-  // previous timer so back-to-back failures don't get prematurely cleared.
+  // Each new message cancels the previous timer so back-to-back failures
+  // don't get prematurely cleared
   function makeAutoClear(target: { set: (v: string | null) => void }, ttlMs = 5000) {
     let timer: ReturnType<typeof setTimeout> | null = null;
     return (msg: string | null) => {
@@ -239,46 +223,48 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   let initSeen = false;
 
   ws.onFrame((frame) => {
-    // 1. _local frames (respawn ack).
+    // _local frames have no `type`, so check before any type-based dispatch
     if (handleLocalFrame(frame)) return;
 
-    // 2. controls layer (control_response → resolve in-flight requests).
-    if (controls.ingest(frame)) return;
+    // Branch system vs non-system once: the hot path (stream_event /
+    // assistant at token rate) is non-system, so this avoids walking
+    // ~5 system handlers before reaching messagesCtrl.ingest
+    if (isSystemFrame(frame)) {
+      switch (frame.subtype) {
+        case "init":
+          if (handleSystemInit(frame)) return;
+          break;
+        case "local_command_output":
+          if (shellCtrl.handleLocalCommandOutput(frame)) return;
+          break;
+        case "hook_started":
+        case "hook_progress":
+        case "hook_response":
+          if (handleHookEvent(frame)) return;
+          break;
+        case "task_started":
+        case "task_progress":
+        case "task_updated":
+        case "task_notification":
+          if (tasksCtrl.handleTaskEvent(frame)) return;
+          break;
+        case "session_state_changed":
+          if (handleSessionStateChanged(frame)) return;
+          break;
+      }
+      // Unknown / opted-out system subtypes still land on the timeline
+      messagesCtrl.pushFrame(frame);
+      return;
+    }
 
-    // 3. permissions gate (inbound control_request:can_use_tool).
+    if (controls.ingest(frame)) return;
     if (permissions.ingest(frame)) return;
-
-    // 4. system:init — capture once per spawn.
-    if (handleSystemInit(frame)) return;
-
-    // 5. user/isReplay shell echo / output. Side-effect-only: builds bash
-    //    XML for next-send buffer, falls through so the frame still lands
-    //    in the chat as a normal user bubble.
     shellCtrl.handleShellReplay(frame);
-
-    // 6. system:local_command_output (rare).
-    if (shellCtrl.handleLocalCommandOutput(frame)) return;
-
-    // 7. hooks.
-    if (handleHookEvent(frame)) return;
-
-    // 8. task lifecycle (system:task_started / task_progress / task_notification).
-    if (tasksCtrl.handleTaskEvent(frame)) return;
-
-    // 9. session_state_changed.
-    if (handleSessionStateChanged(frame)) return;
-
-    // 10. Sub-agent frames (parent_tool_use_id set) MUST run BEFORE
-    //     messagesCtrl — the messages controller eats stream_event /
-    //     assistant unconditionally, which would otherwise pollute the
-    //     main timeline with sub-agent bubbles and starve the per-task
-    //     transcript.
+    // MUST run before messagesCtrl — messages eats stream_event/assistant
+    // unconditionally and would pollute the main timeline with sub-agent
+    // bubbles, starving the per-task transcript
     if (tasksCtrl.handleSubAgentFrame(frame)) return;
-
-    // 11. streaming + canonical assistant — let messages controller decide.
     if (messagesCtrl.ingest(frame)) return;
-
-    // 12. fall-through: drop noisy frames; otherwise append to timeline.
     if ("type" in frame && frame.type === "rate_limit_event") return;
     messagesCtrl.pushFrame(frame);
   });
@@ -297,7 +283,6 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
 
   function handleSystemInit(frame: InboundFrame): boolean {
     if (initSeen) return false;
-    if (!isSystemFrame(frame) || frame.subtype !== "init") return false;
     initSeen = true;
     const f = frame as SystemInit;
     const m = f.permissionMode ?? f.permission_mode;
@@ -318,47 +303,55 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
       slashCommands: f.slash_commands ?? [],
       skills: f.skills ?? [],
     });
-    void controls
-      .request({ subtype: "get_settings" }, { timeoutMs: 10_000 })
-      .then(({ inner }) => {
-        const probes: unknown[] = [
-          inner,
-          (inner as Record<string, unknown> | null)?.applied,
-          (inner as Record<string, unknown> | null)?.effective,
-          (inner as Record<string, unknown> | null)?.settings,
-          (inner as Record<string, unknown> | null)?.permissions,
-          (inner as Record<string, unknown> | null)?.inferenceConfig,
-        ];
-        let found: string | undefined;
-        for (const p of probes) {
-          if (!p || typeof p !== "object") continue;
-          const r = p as Record<string, unknown>;
-          const cand =
-            (typeof r.effortLevel === "string" && r.effortLevel) ||
-            (typeof r.effort_level === "string" && r.effort_level) ||
-            (typeof r.effort === "string" && r.effort) ||
-            undefined;
-          if (cand) { found = cand; break; }
-        }
-        if (found && (KNOWN_EFFORTS as readonly string[]).includes(found)) {
-          activeEffort.set(found as Effort);
-          currentArgs.effort = found as Effort;
-        }
-      })
-      .catch(() => { /* silent */ });
+    // system:init doesn't carry effort. Skip the probe if we already
+    // know it (we spawned with --effort or restored from persistence) —
+    // the binary honours the spawn flag, so currentArgs.effort is the
+    // ground truth in that case.
+    if (!currentArgs.effort) {
+      void controls
+        .request({ subtype: "get_settings" }, { timeoutMs: 10_000 })
+        .then(({ inner }) => {
+          const probes: unknown[] = [
+            inner,
+            (inner as Record<string, unknown> | null)?.applied,
+            (inner as Record<string, unknown> | null)?.effective,
+            (inner as Record<string, unknown> | null)?.settings,
+            (inner as Record<string, unknown> | null)?.permissions,
+            (inner as Record<string, unknown> | null)?.inferenceConfig,
+          ];
+          let found: string | undefined;
+          for (const p of probes) {
+            if (!p || typeof p !== "object") continue;
+            const r = p as Record<string, unknown>;
+            const cand =
+              (typeof r.effortLevel === "string" && r.effortLevel) ||
+              (typeof r.effort_level === "string" && r.effort_level) ||
+              (typeof r.effort === "string" && r.effort) ||
+              undefined;
+            if (cand) { found = cand; break; }
+          }
+          if (found && (KNOWN_EFFORTS as readonly string[]).includes(found)) {
+            activeEffort.set(found as Effort);
+            currentArgs.effort = found as Effort;
+          }
+        })
+        .catch((err) => {
+          // Surface the probe failure so the UI shows we don't actually
+          // know what effort the binary picked, instead of silently
+          // displaying "default".
+          setEffortErr(`could not read effort from get_settings: ${String(err)}`);
+        });
+    }
     messagesCtrl.pushFrame(frame);
     return true;
   }
 
   function handleHookEvent(frame: InboundFrame): boolean {
-    if (!isSystemFrame(frame)) return false;
-    const sub = frame.subtype;
-    if (sub !== "hook_started" && sub !== "hook_progress" && sub !== "hook_response") return false;
-    const hookFrame = frame as Extract<typeof frame, { subtype: typeof sub }>;
+    const hookFrame = frame as SystemHook;
     const entry: HookEntry = {
       id: crypto.randomUUID(),
       ts: Date.now(),
-      subtype: sub,
+      subtype: hookFrame.subtype,
       hookName: hookFrame.hook_event_name ?? hookFrame.hookEventName,
       raw: hookFrame,
     };
@@ -367,7 +360,6 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   }
 
   function handleSessionStateChanged(frame: InboundFrame): boolean {
-    if (!isSystemFrame(frame) || frame.subtype !== "session_state_changed") return false;
     const f = frame as SystemSessionStateChanged;
     if (f.state === "idle" || f.state === "running" || f.state === "requires_action") {
       sessionState.set(f.state);
@@ -390,16 +382,13 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
       effort: currentArgs.effort,
       model: currentArgs.model,
     });
-    // Reset BEFORE the wire send so the new claude's system:init is
-    // accepted no matter whether respawnResult or system:init lands first.
-    // (Prior bug: setEffort relied on respawnResult to clear initSeen, but
-    // the bridge spawns the new child synchronously, so its first stdout
-    // line could beat the local respawnResult on the wire.)
+    // Reset before the wire send: the bridge spawns the new child
+    // synchronously, so the new system:init can beat the local
+    // respawnResult on the wire (prior bug: setEffort relied on
+    // respawnResult to clear this)
     initSeen = false;
-    // Cancel any control_request promises that were in flight against the
-    // about-to-die child. The bridge kills the old child the moment it
-    // receives _local:respawn; outstanding requests would otherwise hang
-    // until their timeouts fire against a dead pipe.
+    // Bridge kills the old child the instant it receives _local:respawn;
+    // outstanding controls would otherwise hang against a dead pipe
     controls.abortAll("respawn");
     permissions.clearQueue();
     return new Promise<void>((resolve, reject) => {
@@ -415,12 +404,17 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
 
   // ---- public methods ----
 
+  // One initial respawn per connect/disconnect cycle. Repeat connect()
+  // calls without an intervening disconnect() are no-ops; otherwise a
+  // duplicate connect would re-spawn against an already-running child.
+  let connectStarted = false;
   function connect() {
+    if (connectStarted) return;
+    connectStarted = true;
     ws.connect();
-    // nanostores subscribe() fires synchronously with the current value
-    // BEFORE returning the unsubscribe — using `const off = subscribe(...)`
-    // and referencing `off` inside the callback TDZ-throws if status is
-    // already "open" at subscribe time. `let` + null-guard handles it.
+    // nanostores subscribe fires synchronously with the current value
+    // before returning the unsubscribe; `let` + null-guard avoids the
+    // TDZ throw if status is already "open" at subscribe time
     let offStatus: (() => void) | null = null;
     let fired = false;
     offStatus = ws.status.subscribe((s) => {
@@ -433,13 +427,11 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   }
 
   function disconnect() {
-    // Reject in-flight controls and clear the permission queue before
-    // closing the socket so consumers don't see UI buttons hang for
-    // 30 seconds against a torn-down connection.
+    connectStarted = false;
+    // Reject before close so UI buttons don't hang 30s on a torn-down conn
     controls.abortAll("disconnected");
     permissions.clearQueue();
-    // Reject any pending respawn, too — a respawn issued just before
-    // disconnect would otherwise sit until its 60s timeout.
+    // A respawn issued just before disconnect would otherwise sit 60s
     for (const [id, r] of pendingRespawns) {
       clearTimeout(r.timeoutId);
       r.reject("disconnected");
@@ -482,12 +474,11 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
     } catch (err) {
       pendingMode.set(null);
       const msg = String(err);
-      // Auto-skip: if the failed mode is in the cycle, jump to the next
-      // cycle slot so cycling doesn't get stuck on a forbidden mode.
+      // Skip a forbidden mode in the cycle so cycling doesn't get stuck
       if (CYCLE_ORDER.includes(next)) {
         const skip = nextCycleMode(next);
         setModeErr(`${next} not allowed (${msg}) — skipping to ${skip}`);
-        // Defer one tick so atom subscribers commit pendingMode=null first.
+        // Defer so atom subscribers commit pendingMode=null first
         setTimeout(() => { void setPermissionMode(skip); }, 0);
       } else {
         setModeErr(`could not change to ${next}: ${msg}`);
@@ -538,17 +529,15 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   async function changeSession(mode: SessionMode, opts: { resetTimeline: boolean }) {
     currentArgs.mode = mode;
     if (opts.resetTimeline) {
-      // Switching to a different conversation thread — wipe local state so
-      // stale bubbles from the previous session don't bleed into the new one.
+      // Different thread; previous-session bubbles must not bleed in
       messagesCtrl.reset();
       hookEvents.set([]);
       shellCtrl.reset();
       tasksCtrl.reset();
-      // Clear init too, otherwise the OLD sessionId / cwd / agents stay
-      // visible in the UI until the new system:init lands (the wire round-
-      // trip can be tens of ms but the visual flicker is jarring). Effort/
-      // model respawns intentionally don't clear init — the same session
-      // is preserved by --continue and gets the same sessionId back.
+      // Otherwise old sessionId/cwd/agents stay visible until the new
+      // system:init lands (jarring tens-of-ms flicker). Effort/model
+      // respawns intentionally don't clear init — --continue preserves
+      // the session and reuses the same sessionId
       init.set({
         sessionId: null,
         model: null,
@@ -557,31 +546,25 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
         slashCommands: [],
         skills: [],
       });
-      // Also clear the persisted snapshot so a refresh after New/Resume
-      // doesn't fall back to the previous session's saved sessionId. The
-      // post-respawn system:init will write the new id back in.
+      // Otherwise a refresh after New/Resume falls back to the previous
+      // session's saved sessionId; post-respawn system:init writes the
+      // new id back in
       if (persistence) {
         try { persistence.storage.removeItem(persistence.key); } catch {}
       }
     }
-    // respawn() resets initSeen + aborts in-flight controls/permissions.
     await respawn();
   }
 
-  // newSession = brand-new conversation, wipe.
   async function newSession() {
     await changeSession({ kind: "new" }, { resetTimeline: true });
   }
-  // continueSession = pick up the most recent thread. Don't wipe local
-  // state: the CLI's --continue restores claude's internal context but
-  // does NOT restream prior turns over stream-json, so wiping would leave
-  // a permanently empty timeline. Calling continue when you're already on
-  // the current session means "stay here," and the user's bubbles stay.
+  // --continue restores claude's internal context but does NOT restream
+  // prior turns, so wiping would leave a permanently empty timeline.
+  // Calling continue on the current session means "stay here"
   async function continueSession() {
     await changeSession({ kind: "continue" }, { resetTimeline: false });
   }
-  // resumeSession = jump to a specific session by id; almost always means
-  // a different thread.
   async function resumeSession(sessionId: string) {
     await changeSession({ kind: "resume", sessionId }, { resetTimeline: true });
   }
@@ -606,7 +589,7 @@ export function createCcSession(opts: CcSessionOptions): CcSession {
   }
 
   async function stopTask(taskId: string) {
-    // stop_task is decorative for local_agent — only interrupt halts it.
+    // For local_agent stop_task is a no-op; only interrupt actually halts it
     const task = tasks.get().find((t) => t.taskId === taskId);
     if (task?.taskType === "local_agent") return interrupt();
     await controls.request({ subtype: "stop_task", task_id: taskId }, { timeoutMs: 10_000 });

package/src/shell.ts

@@ -1,12 +1,7 @@
-// Bash exchange XML — single source of truth for the format the bridge
-// replays back when a `bash_command` frame runs. Three shapes ride the
-// `user` content channel:
+// Bash-replay XML on the user content channel. Three shapes:
 //   input-only   <bash-input>cmd</bash-input>
 //   output-only  <bash-stdout>…</bash-stdout><bash-stderr>…</bash-stderr><bash-exit-code>0</bash-exit-code>
 //   merged       both, plus arbitrary trailing user text (drain-synthesis)
-// Both the lib's outbound writer (handleShellReplay) and any UI that
-// renders bash exchanges parse the same shape — keep them in lockstep
-// here.
 
 import { atom, type WritableAtom } from "nanostores";
 import { isSystemFrame, isUserFrame, type InboundFrame } from "./protocol";
@@ -65,9 +60,7 @@ export function parseBashFrame(text: string): BashFrame | null {
   };
 }
 
-// Reconstruct the merged-frame XML the lib drains into the next user
-// message. Encoding mirrors what the binary sends back so the round-trip
-// is lossless.
+// Encoding mirrors what the binary emits so the round-trip is lossless
 export function buildBashXml(command: string, stdoutXml: string, stderrXml: string): string {
   return (
     `<bash-input>${escapeXml(command)}</bash-input>\n` +
@@ -85,25 +78,19 @@ export type ShellEntry = {
   command: string;
   source: ShellSource;
   chunks: string[];
-  // For context-shell: the exchange has run on the bridge but the
-  // <bash-input>/<bash-stdout> XML hasn't been sent to claude yet — it
-  // gets prepended to the user's next sendMessage() (matches the TUI's
-  // shouldQuery:false flow). Cleared when drained.
+  // True between bridge-run and the drain into the next sendMessage —
+  // matches the TUI's shouldQuery:false flow
   pending?: boolean;
 };
 
 export type ShellController = {
   shellEntries: WritableAtom<ShellEntry[]>;
-  // Frame ingestion side-effects (return false intentionally for the
-  // user-replay path — see handleShellReplay below).
+  // Returns false on the replay path so the frame still flows into messagesCtrl
   handleShellReplay: (frame: InboundFrame) => boolean;
   handleLocalCommandOutput: (frame: InboundFrame) => boolean;
-  // Public ops.
   sendShellContext: (command: string, followUp?: string) => void;
   sendBashSideChannel: (command: string) => void;
   dismissShellEntry: (id: string) => void;
-  // Drain pending bash exchanges into outbound text + clear their entries.
-  // Returns the rewritten payload for sendMessage to wire-send.
   drainPending: (text: string) => string;
   hasPending: () => boolean;
   reset: () => void;
@@ -111,42 +98,32 @@ export type ShellController = {
 
 export function createShellController(args: {
   ws: WsClient;
-  // sendMessage is back-injected because a queued follow-up text fires
-  // sendMessage(followUp) after the bash exchange's XML is buffered, and
-  // sendMessage in turn drains via drainPending().
+  // Back-injected: queued follow-ups fire sendMessage after buffering,
+  // and sendMessage in turn drains via drainPending
   sendMessage: (text: string) => void;
 }): ShellController {
   const { ws, sendMessage } = args;
   const shellEntries = atom<ShellEntry[]>([]);
 
-  // bash_command replay frames don't carry a correlation id, but the
-  // binary processes them in the order received and replies in the same
-  // order. So we keep a FIFO of in-flight captures: each call to
-  // sendShellContext / sendBashSideChannel pushes; each output-replay
-  // frame shifts. Two bash sends in quick succession used to clobber
-  // each other when we tracked a single `activeShellId` global.
+  // bash_command replays carry no correlation id, but the binary replies
+  // in send-order — so we FIFO-track in-flight captures. Two bash sends
+  // in quick succession used to clobber each other when we tracked a
+  // single `activeShellId` global.
   const captureQueue: {
     entryId: string;
     command: string;
     source: ShellSource;
     sawInputEcho: boolean;
   }[] = [];
-  // Buffered <bash-input>/<bash-stdout>/<bash-stderr> XML, FIFO. Filled
-  // when a context-shell capture's output replay arrives; drained by
-  // sendMessage() which prepends to the user's next prompt. The TUI-`!cmd`
-  // parity workaround: bash_command's replay frames are NOT injected
-  // into claude's transcript by the binary (verified empirically).
+  // Empirically the binary does NOT auto-inject bash_command replay
+  // frames into claude's transcript, so we buffer the XML here and
+  // prepend it to the user's next sendMessage to achieve TUI-`!cmd` parity
   const pendingBashExchanges: { entryId: string; xml: string }[] = [];
-  // Optional follow-up user prompts queued from sendShellContext (the
-  // multi-line `!cmd\n<followup>` form). Fires sendMessage(followUp)
-  // after the bash exchange's XML is buffered, so the followUp goes out
-  // as the user message that drains the buffer.
+  // Multi-line `!cmd\n<followup>` form: the followUp must go out as the
+  // user message that drains the buffer, not before it
   const pendingFollowUps = new Map<string, string>();
 
-  // Side-effect-only: scrape bash-* replay frames for shellEntries chunks
-  // + build the buffered XML that rides out on the next sendMessage.
-  // Always returns false so the frame still flows into messagesCtrl for
-  // chat-side rendering.
+  // Always returns false so the frame still reaches messagesCtrl for chat rendering
   function handleShellReplay(frame: InboundFrame): boolean {
     if (!isUserFrame(frame) || !frame.isReplay) return false;
     const c = frame.message.content;
@@ -155,14 +132,11 @@ export function createShellController(args: {
     if (!parsed) return false;
 
     if (parsed.kind === "input") {
-      // First replay frame for the head capture: the binary acked the
-      // command. Output is still pending.
       const head = captureQueue[0];
       if (head) head.sawInputEcho = true;
       return false;
     }
-    // Both "output" (output-only replay) and "merged" (some bridges emit
-    // input + output in one frame) close the head capture in FIFO order.
+    // Both "output" and "merged" close the head capture in FIFO order
     const cap = captureQueue.shift();
     if (!cap) return false;
     const parts: string[] = [];
@@ -174,8 +148,7 @@ export function createShellController(args: {
       shellEntries.get().map((s) => (s.id === cap.entryId ? { ...s, chunks: [...s.chunks, chunk] } : s)),
     );
     if (cap.source === "context") {
-      // Re-encode for the buffered XML — parseBashFrame decodes the
-      // entities; the outbound payload needs them re-escaped.
+      // parseBashFrame decoded the entities; the outbound payload needs them re-escaped
       const stdoutXml = escapeXml(parsed.stdout);
       const stderrXml = escapeXml(parsed.stderr);
       pendingBashExchanges.push({
@@ -203,19 +176,10 @@ export function createShellController(args: {
   }
 
   function sendShellContext(command: string, followUp = "") {
-    // Route `!cmd` to the binary via the bash_command wire frame: the
-    // binary runs it (with its own bounds, sandboxing, etc) and replays
-    // <bash-input>/<bash-stdout>/<bash-stderr>/<bash-exit-code> as
-    // user/isReplay frames over the wire. Empirically these replay
-    // frames are NOT auto-injected into claude's transcript — we have
-    // to ride them out ourselves on the next user message.
     const id = crypto.randomUUID();
     shellEntries.set([...shellEntries.get(), { id, command, source: "context", chunks: [], pending: true }]);
     captureQueue.push({ entryId: id, command, source: "context", sawInputEcho: false });
     ws.send({ type: "bash_command", command });
-    // If the user typed a follow-up prompt on subsequent lines of the
-    // !cmd input, fire it right after the bash exchange completes — the
-    // drain in sendMessage will prepend the XML to the followUp text.
     if (followUp.trim()) {
       pendingFollowUps.set(id, followUp);
     }
@@ -236,10 +200,8 @@ export function createShellController(args: {
     return pendingBashExchanges.length > 0;
   }
 
-  // Drain buffered context-shell exchanges. Drained shell entries get
-  // removed from shellEntries — the panel acts as a "queued exchange"
-  // indicator that empties when the user fires the message that flushes
-  // the buffer. The exchange remains visible in the chat scrollback.
+  // shellEntries empties on drain (it's a "queued exchange" indicator);
+  // the exchange itself remains visible in chat scrollback
   function drainPending(text: string): string {
     if (pendingBashExchanges.length === 0) return text;
     const xml = pendingBashExchanges.map((p) => p.xml).join("\n");

package/src/tasks.ts

@@ -1,7 +1,5 @@
-// Task lifecycle: system:task_started / task_progress / task_updated /
-// task_notification, plus sub-agent fan-out (frames carrying a non-null
-// parent_tool_use_id are routed to the matching task's transcript instead
-// of the main timeline).
+// Frames carrying a non-null parent_tool_use_id are routed to the
+// matching task's transcript instead of the main timeline.
 
 import { atom, type WritableAtom } from "nanostores";
 import type { MessageEntry } from "./messages";
@@ -15,10 +13,9 @@ import {
   type TaskUsageBlock,
 } from "./protocol";
 
-// task_id is the binary's local registry id and the value to pass to
-// stopTask(). tool_use_id ties the task back to the tool_use block that
-// spawned it (Bash, Agent, Task, etc) — used to render task progress
-// alongside / inside the parent's tool_use card.
+// task_id is the value stopTask() takes; tool_use_id matches the
+// spawning tool_use block (Bash, Agent, Task) so UI can nest progress
+// inside the parent card
 export type TaskStatus = "running" | "completed" | "failed" | "stopped";
 
 export type TaskUsage = {
@@ -41,9 +38,8 @@ export type TaskEntry = {
   summary?: string;
   outputFile?: string;
   usage?: TaskUsage;
-  // Sub-agent transcript (frames received with parent_tool_use_id matching
-  // toolUseId). Populated only for tasks that emit their own frames —
-  // bash tasks won't have these.
+  // Frames whose parent_tool_use_id matches toolUseId; bash tasks
+  // emit none and stay empty
   transcript: MessageEntry[];
 };
 
@@ -51,7 +47,7 @@ const TASKS_CAP = 100;
 
 export function capTasksKeepRunning<T extends { status: string }>(arr: T[], cap: number): T[] {
   if (arr.length <= cap) return arr;
-  // Evict oldest non-running entries first; if all are running, keep all.
+  // Evict oldest non-running first; if all are running, exceed the cap
   const overflow = arr.length - cap;
   const out: T[] = [];
   let evictBudget = overflow;
@@ -81,8 +77,55 @@ export type TasksController = {
   reset: () => void;
 };
 
+// Real binary ordering puts task_started ahead of fan-out frames,
+// so anything still orphaned past the TTL is a wire-protocol bug
+// worth surfacing in the console
+const ORPHAN_TTL_MS = 5000;
+
+type PendingFrame = { frame: InboundFrame; addedAt: number };
+
 export function createTasksController(): TasksController {
   const tasks = atom<TaskEntry[]>([]);
+  const pendingByParent = new Map<string, PendingFrame[]>();
+
+  function gcPending(now: number) {
+    for (const [parent, buf] of pendingByParent) {
+      const kept = buf.filter((p) => now - p.addedAt < ORPHAN_TTL_MS);
+      if (kept.length === buf.length) continue;
+      const dropped = buf.length - kept.length;
+      if (dropped > 0) {
+        console.warn("[tasks] orphan sub-agent frame dropped after TTL", parent, dropped);
+      }
+      if (kept.length === 0) {
+        pendingByParent.delete(parent);
+      } else {
+        pendingByParent.set(parent, kept);
+      }
+    }
+  }
+
+  function flushPendingFor(parent: string) {
+    const buf = pendingByParent.get(parent);
+    if (!buf || buf.length === 0) return;
+    pendingByParent.delete(parent);
+    const arr = tasks.get();
+    const idx = arr.findIndex((t) => t.toolUseId === parent);
+    if (idx === -1) return;
+    const next = arr.slice();
+    const cur = arr[idx]!;
+    const appended: MessageEntry[] = buf.map((p, i) => ({
+      kind: "frame" as const,
+      id: crypto.randomUUID(),
+      frame: p.frame,
+      arrivalIdx: cur.transcript.length + i,
+    }));
+    next[idx] = {
+      ...cur,
+      transcript: [...cur.transcript, ...appended],
+      lastUpdate: Date.now(),
+    };
+    tasks.set(next);
+  }
 
   function upsertTask(taskId: string, mut: (t: TaskEntry) => TaskEntry, init?: () => TaskEntry) {
     const arr = tasks.get();
@@ -97,8 +140,6 @@ export function createTasksController(): TasksController {
     }
   }
 
-  // task_started bookend opens a task; progress updates the running entry;
-  // task_notification closes it with terminal status.
   function handleTaskEvent(frame: InboundFrame): boolean {
     if (!isSystemFrame(frame)) return false;
 
@@ -131,6 +172,7 @@ export function createTasksController(): TasksController {
           transcript: [],
         }),
       );
+      if (f.tool_use_id) flushPendingFor(f.tool_use_id);
       return true;
     }
 
@@ -148,9 +190,9 @@ export function createTasksController(): TasksController {
       return true;
     }
 
-    // task_updated is the binary's immediate state-change frame (stop_task
-    // → status:"killed"). The bookend task_notification arrives later;
-    // flip status NOW so a killed task doesn't render as still-running.
+    // task_updated lands immediately on stop_task; the closing
+    // task_notification arrives later, so we must flip status now
+    // to avoid rendering a killed task as still-running
     if (frame.subtype === "task_updated") {
       const f = frame as SystemTaskUpdated;
       if (!f.task_id || !f.patch) return false;
@@ -199,21 +241,28 @@ export function createTasksController(): TasksController {
     return false;
   }
 
-  // Sub-agent frames must be checked BEFORE messagesCtrl.ingest in the
-  // dispatch chain — the messages controller eats stream_event / assistant
-  // unconditionally, which would otherwise pollute the main timeline with
-  // sub-agent bubbles and starve the per-task transcript.
+  // MUST run before messagesCtrl.ingest in the dispatch chain — messages
+  // eats stream_event/assistant unconditionally and would pollute the
+  // main timeline with sub-agent bubbles. Returning true claims the
+  // frame: appended to the task transcript, buffered until task_started
+  // arrives, or dropped after ORPHAN_TTL_MS.
   function handleSubAgentFrame(frame: InboundFrame): boolean {
     const parent =
       "parent_tool_use_id" in frame && typeof frame.parent_tool_use_id === "string"
         ? frame.parent_tool_use_id
         : null;
     if (!parent) return false;
+    const now = Date.now();
+    gcPending(now);
     const arr = tasks.get();
     const idx = arr.findIndex((t) => t.toolUseId === parent);
-    // Race: task_started not yet observed. Fall through so the frame still
-    // appears somewhere — visible-but-misplaced beats dropped.
-    if (idx === -1) return false;
+    if (idx === -1) {
+      // task_started not yet observed; buffer until it lands
+      const buf = pendingByParent.get(parent) ?? [];
+      buf.push({ frame, addedAt: now });
+      pendingByParent.set(parent, buf);
+      return true;
+    }
     const next = arr.slice();
     const cur = arr[idx]!;
     next[idx] = {
@@ -227,7 +276,7 @@ export function createTasksController(): TasksController {
           arrivalIdx: cur.transcript.length,
         },
       ],
-      lastUpdate: Date.now(),
+      lastUpdate: now,
     };
     tasks.set(next);
     return true;
@@ -235,6 +284,7 @@ export function createTasksController(): TasksController {
 
   function reset() {
     tasks.set([]);
+    pendingByParent.clear();
   }
 
   return {

package/src/ws.ts

@@ -1,6 +1,5 @@
-// Thin WS wrapper. Does NOT auto-reconnect (deferred per LIB-DESIGN). One
-// connection per createCcSession. NDJSON framing on the wire — every send is
-// already a single JSON object; the bridge splits inbound on `\n`.
+// Does NOT auto-reconnect. NDJSON on the wire: each send is a single JSON
+// object; bridge splits inbound on `\n`.
 
 import { atom, type WritableAtom } from "nanostores";
 import type { InboundFrame, OutboundFrame } from "./protocol";
@@ -19,9 +18,7 @@ export type WsClient = {
   connect: () => void;
   disconnect: () => void;
   send: (frame: OutboundFrame) => void;
-  // Internal: subscribers register here to receive parsed inbound frames.
-  // Avoids forcing a fan-out atom that would re-render every subscriber on
-  // every frame.
+  // Direct fan-out instead of atom — avoids re-rendering every subscriber per frame
   onFrame: (handler: (frame: InboundFrame) => void) => () => void;
 };
 
@@ -58,14 +55,14 @@ export function createWsClient(opts: {
       try {
         parsed = JSON.parse(text);
       } catch {
-        // Bad frame — drop. We don't want one bad frame to take down the session.
+        // One bad frame must not take down the session
         return;
       }
       for (const h of handlers) {
         try {
           h(parsed);
         } catch (err) {
-          // A handler throwing should not stop other handlers.
+          // One handler throwing must not stop the others
           console.error("[ws] handler error", err);
         }
       }