garrytan
diff --git a/‎BROWSER.md‎
Lines changed: 1 addition & 0 deletions b/‎BROWSER.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 53 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 53 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 20 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 20 additions & 0 deletions
diff --git a/‎SKILL.md‎
Lines changed: 1 addition & 0 deletions b/‎SKILL.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎TODOS.md‎
Lines changed: 135 additions & 0 deletions b/‎TODOS.md‎
Lines changed: 135 additions & 0 deletions
diff --git a/‎VERSION‎
Lines changed: 1 addition & 1 deletion b/‎VERSION‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎browse/SKILL.md‎
Lines changed: 1 addition & 0 deletions b/‎browse/SKILL.md‎
Lines changed: 1 addition & 0 deletions
@@ -317,6 +317,7 @@ from `snapshot`, or `@c` refs from `snapshot -C`. Full table:
 | `disconnect` | Close headed Chrome, return to headless |
 | `focus [@ref]` | Bring headed Chrome to foreground (macOS); `@ref` also scrolls into view |
 | `state save\|load <name>` | Save or load browser state (cookies + URLs) |
+| `memory [--json]` | Snapshot Bun heap + per-tab JS heap + Chromium process tree + bounded buffer sizes. Use `--json` for programmatic consumers; text mode renders sorted top-10 tabs with "and N more" tail. |
 
 ### Handoff
 
 
@@ -1,5 +1,58 @@
 # Changelog
 
+## [1.51.0.0] - 2026-05-27
+
+## **Long-running browser sessions hold flat RSS on the Bun side. `$B memory` gives every future OOM receipts instead of a screenshot.** Four CDP-resource leak classes closed and pinned with tripwires; a structured diagnostic surfaces Bun heap + per-tab JS heap + Chromium process tree + bounded buffer sizes in real time.
+
+This release closes four leak classes in the browse server that compounded silently across long sidebar sessions: response-body materialization in the requestfinished listener (multi-GB/hour Buffer churn on media-heavy pages), three undetached CDP session call sites (cdp-bridge, write-commands archive, cdp-inspector), an unbounded modificationHistory array in the CSS inspector, and SSE subscriber cleanup that only fired on the abort edge — TCP-died-without-abort cases (Chromium MV3 service-worker suspend, intermediate proxy half-close) left subscribers in the Set forever holding the controller and any queued bytes. All four have invariant tests; a static-grep tripwire fails CI if a future refactor reintroduces direct `newCDPSession(...)` calls outside the helper module.
+
+Alongside the fixes, `$B memory` and `/memory` ship the diagnostic the original 160 GB OOM investigation was missing: Bun RSS + heap breakdown, per-tab JS heap via CDP `Performance.getMetrics`, Chromium process tree via `SystemInfo.getProcessInfo` (PID + type + CPU), and the bounded buffer sizes (modificationHistory, activity subscribers, inspector subscribers, console/network/dialog buffers, capture buffer bytes). The sidebar footer polls `/memory` every 30s with adaptive backoff (drops to 5min if response time exceeds 2s), and a tab-count guardrail fires soft-warn at 50 / hard-warn at 200 with a top-5-by-RAM toast offering one-click close. Single-tab JS heap above 4 GB triggers an immediate toast, catching the WebGL/video runaway case where one tab balloons without the count ever reaching 200.
+
+### The numbers that matter
+
+Source: this branch's 16 commits + the post-merge audit reports. Net diff: 23 files changed, +2251 / -143 = 2394 LOC across browse server (TypeScript), gstack extension (JS/HTML/CSS), and tests.
+
+| Capability | Before this PR | After this PR |
+|---|---|---|
+| `requestfinished` body handling | `await res.body()` on every response, allocates full body Buffer for one `.length` read | `req.sizes()` reads structured byte count from `Network.loadingFinished`, zero body materialization, accurate for chunked / gzip / streaming responses |
+| CDP session lifecycle (3 sites) | direct `newCDPSession`, detach missing or success-path-only | `withCdpSession` (try/finally detach) + `getOrCreateCdpSession` (cached + close-detach) helpers, all 3 sites migrated, static-grep tripwire prevents regression |
+| modificationHistory in CSS inspector | unbounded array, grew for every `$B css` edit across the session | bounded FIFO cap 200, evicted-count surfaced in the undo error so the user knows why their target index is gone |
+| SSE subscriber cleanup | abort-edge only; TCP-died-without-abort leaked subscriber + controller + queued bytes until process exit | `createSseEndpoint` helper with cleanup on abort + enqueue-throw + heartbeat-throw, idempotent (any edge fires once) |
+| Tab-count visibility | none — user could accumulate hundreds of tabs without warning | soft warn at 50 (activity entry), action toast at 200 (top 5 by RAM + Close-selected + Snooze), single-tab >4 GB triggers immediate toast |
+| Diagnostic command | not available | `$B memory` (text + `--json`), `/memory` endpoint (SSE-session-cookie gated), sidebar footer with adaptive backoff |
+| Net change in `server.ts` (SSE refactor) | 132 lines of inline ReadableStream wiring across two endpoints | 23 lines, both endpoints route through one helper |
+| Test pins for the leak class | none specific | 6 new test files, 45 new tests; static-grep tripwire fails CI on regression |
+
+### What this means for builders
+
+The next time you leave a gbrowser session running for days, the Bun side holds its RSS flat instead of churning on per-response Buffer allocations. If a tab does go rogue, the sidebar footer shows you in real time — `RSS: 5.6 GB · 12 tabs`, color-coded — and a 200-tab toast surfaces the top RAM consumers with one-click close before you hit the OS OOM killer. If the next OOM still fires, `$B memory` is there to give it receipts instead of theory: Activity Monitor says 160 GB; the diagnostic tells you which process tree, which tabs, and which in-memory structures are holding it. Every code path the diagnostic measures is also bounded — modificationHistory at 200, console/network/dialog buffers at 50K via the existing CircularBuffer, SSE subscribers via the new cleanup contract — so the bookkeeping itself can't leak.
+
+### Itemized changes
+
+#### Added
+- **`$B memory` command** in `browse/src/memory-command.ts` — text mode with sorted top-10 tabs + "and N more" tail; `--json` mode for programmatic consumers and the sidebar footer poll.
+- **`/memory` HTTP endpoint** in `browse/src/server.ts` — same SSE-session-cookie auth model as `/activity/stream`. Deliberately NOT extending `/health` (which already leaks AUTH_TOKEN in headed mode per TODOS.md "Audit /health token distribution").
+- **`BrowserManager.getMemorySnapshot()`** — collects Bun process memory + per-tab JS heap via `Performance.getMetrics` (lazy per tracked page, swallows target-died errors) + Chromium process tree via `Browser.newBrowserCDPSession()` + `SystemInfo.getProcessInfo`.
+- **`browse/src/memory-snapshot.ts`** — shared types (`MemorySnapshot`, `MemoryTabSnapshot`, `MemoryProcess`, `MemoryStructureStats`) plus `formatBytes()` renderer (4 tiers, 2 decimals at GB).
+- **`withCdpSession(page, fn)`** and **`getOrCreateCdpSession(page, cache)`** in `browse/src/cdp-bridge.ts` — lifecycle helpers for one-shot and cached CDP work. Every direct `newCDPSession` call site now routes through one of them.
+- **`createSseEndpoint(req, config)`** in `browse/src/sse-helpers.ts` — owns the SSE cleanup contract (abort + enqueue-throw + heartbeat-throw, all idempotent). Built-in lone-surrogate sanitization on every JSON.stringify.
+- **Sidebar footer RSS readout** in `extension/sidepanel.{html,js,css}` — polls `/memory` every 30s with 5-minute backoff if response time exceeds 2s. Color-coded thresholds: orange at 2 GB Bun RSS or 50 tabs, red at 8 GB or 200 tabs.
+- **Tab guardrail UX** in `extension/sidepanel.js` — top-5-by-RAM toast at 200 tabs OR any single tab over 4 GB JS heap, with checkboxes + Close-selected (via `$B closetab`) + Snooze persisted in `chrome.storage.session`. Snooze bumps the thresholds so the toast stays hidden until the user accumulates more tabs or one tab grows another 2 GB.
+- **Static-grep tripwire** (`browse/test/cdp-session-cleanup.test.ts`) — fails CI if any source file outside `cdp-bridge.ts` calls `newCDPSession(...)` directly.
+- **45 new tests across 6 files** pinning the leak-fix invariants: CDP session lifecycle (8), SSE cleanup contract (6), modificationHistory cap + evicted-aware error (7), tab guardrail fires-once + re-arms (6), body-materialization reproducer (1), `$B memory` formatter + byte renderer + JSON entry (17).
+- **4 follow-up entries in `TODOS.md`** (P2: MV3 SW memory profile, P2: native + GPU memory breakdown, P3: single-context CDP listener via `Target.setAutoAttach`, P3: real-Chromium peak-RSS reproducer for periodic tier).
+
+#### Changed
+- **`wirePageEvents.requestfinished` no longer materializes response bodies.** Pre-fix: `await res.body()` allocated a Bun `Buffer` of the full response on every fetch just to read `.length`. Post-fix: `req.sizes()` pulls the structured byte count from `Network.loadingFinished` without body fetch. Accurate for chunked transfer, gzip-encoded responses, and streaming media.
+- **`modificationHistory` capped at 200 entries with FIFO eviction.** `undoModification` error now reports `"No modification at index N. History has 200 entries (most recent 200 only — M earlier entries evicted at the cap)."` when the requested index is out of range AND the buffer has overflowed.
+- **`/activity/stream` and `/inspector/events` refactored through `createSseEndpoint`.** Both endpoints collapse from ~45 lines of inline `ReadableStream` wiring to ~8 lines of helper config; behavior preserved bit-for-bit.
+- **`memory` command classified under the `Server` category** in `COMMAND_DESCRIPTIONS` so it appears in the generated SKILL.md tables alongside `status` / `restart` / `handoff`.
+
+#### For contributors
+- Plan completion audit: 12 of 17 plan items DONE, 2 CHANGED (deliberate scope decisions documented in the relevant commits — `req.sizes()` swap simpler than a single-context CDP listener; tab guardrail action toast wired through `$B closetab` instead of a `chrome.tabs.remove` bridge), 1 deferred to periodic tier (UI E2E tests).
+- Coverage audit: 44% pre-diagnostic-tests → ~62% after adding the formatter coverage. Strong paths (CDP session lifecycle, body materialization, history cap, tab guardrail, SSE cleanup) all at 100% with invariant tests. Extension UI tests deferred (no extension test harness in this repo today).
+- The CDP-session cleanup tripwire is the most reusable artifact here — any future addition of CDP work should route through the two helpers. Trying to call `newCDPSession` outside `cdp-bridge.ts` fails CI immediately with a pointer to the right helper.
+
 ## [1.48.0.0] - 2026-05-26
 
 ## **Agents stop dropping AskUserQuestion options when there are 5+.** A new canonical preamble rule + runtime gate makes Conductor's 4-option cap a split-or-batch decision, not a silent trim.
 
@@ -294,6 +294,26 @@ response in `server.ts`, read
 `browse/test/server-sanitize-surrogates.test.ts` pins the wiring with invariant
 tests, so bypasses fail CI.
 
+**SSE endpoint helper** (v1.51.0.0+). New SSE endpoints in `server.ts` MUST route
+through `createSseEndpoint(req, config)` from `browse/src/sse-helpers.ts`. The
+helper owns the cleanup contract (abort + enqueue-throw + heartbeat-throw, all
+idempotent) and bakes in `sanitizeLoneSurrogates` on every JSON.stringify, so
+new subscribers can't accidentally regress either invariant. Inline
+`ReadableStream` wiring leaked subscribers when the TCP connection died without
+firing `req.signal.abort` (Chromium MV3 service-worker suspend, intermediate
+proxy half-close). `/activity/stream`, `/inspector/events`, and `/memory`
+(SSE-eligible) all route through it. `browse/test/sse-helpers.test.ts` pins the
+cleanup contract.
+
+**CDP session lifecycle** (v1.51.0.0+). Direct `page.context().newCDPSession(page)`
+calls outside `browse/src/cdp-bridge.ts` fail CI via the static-grep tripwire in
+`browse/test/cdp-session-cleanup.test.ts`. Use `withCdpSession(page, async (s) => {...})`
+for one-shot CDP work (try/finally detach) or `getOrCreateCdpSession(page, cache)`
+for cached sessions tied to a page's lifetime (close-detach via `Map<page, session>`).
+Three sites migrated: cdp-bridge frame events, write-commands archive capture,
+cdp-inspector. The helpers prevent the per-session leak class where successful-path
+detach happened but error-path detach was missed.
+
 **Setup symlink hardening** (v1.38.0.0+). Every link site in `setup` MUST route
 through the `_link_or_copy SRC DST` helper near the `IS_WINDOWS` detection. On
 Windows without Developer Mode, plain `ln -snf` produces frozen file copies that
 
@@ -963,6 +963,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 | `disconnect` | Disconnect headed browser, return to headless mode |
 | `focus [@ref]` | Bring headed browser window to foreground (macOS) |
 | `handoff [message]` | Open visible Chrome at current page for user takeover |
+| `memory [--json]` | Snapshot Bun heap + per-tab JS heap + Chromium process tree + bounded buffer sizes. JSON output with --json. |
 | `restart` | Restart server |
 | `resume` | Re-snapshot after user takeover, return control to AI |
 | `state save|load <name>` | Save/load browser state (cookies + URLs) |
 
@@ -1,5 +1,140 @@
 # TODOS
 
+## gbrowser memory follow-ups (filed via /plan-eng-review + /codex on the v1.49 leak-fix PR)
+
+These four items came out of the memory-leak investigation that shipped
+the `$B memory` diagnostic + the four leak fixes. They were
+deliberately deferred from that PR (already 14 commits / ~12 files);
+each stands alone and any one could ship independently.
+
+### P2: MV3 extension service worker memory profile
+
+**What:** The `/memory` endpoint snapshot enumerates pages but does
+not enumerate the gstack baked-in extension's service-worker target.
+A long-running MV3 service worker can leak through retained DOM
+snapshots, message ports that never close, alarms that re-arm, and
+caches that grow without bound. The diagnostic should call
+`Target.getTargets` with a filter for `service_worker` and include
+each one in `tabs[]` (or a sibling `serviceWorkers[]` array) with the
+same `Performance.getMetrics` data.
+
+**Why:** Codex's outside-voice review on the eng-review surfaced this
+class of leak (the extension is part of the gbrowser process tree but
+invisible to today's snapshot). Until we surface it, a SW leak shows
+up only in the parent process RSS with no per-target attribution.
+
+**Pros:** Closes the per-target attribution gap for the
+single-most-likely future leak source (our own extension).
+**Cons:** Extension SW lifecycle is asymmetric vs page lifecycle;
+auto-attach + filter is one more piece of CDP plumbing.
+
+**Context:** Codex finding #4 on the eng-review outside voice. Not
+in scope of the v1.49 PR; deliberately deferred to keep the PR to
+the four highest-confidence leak fixes.
+
+**Priority:** P2. **Effort:** M.
+
+---
+
+### P2: Native + GPU memory breakdown in `$B memory`
+
+**What:** `$B memory` shows Bun RSS + per-tab JS heap + Chromium
+process tree (PIDs + types + CPU time) but the per-process RSS is
+absent — `SystemInfo.getProcessInfo` doesn't expose RSS and the eng
+review (D2 USE_CDP) explicitly chose CDP over shelling to `ps`. The
+honest next step is to surface what CDP DOES give for the other
+memory categories: `Memory.getDOMCounters` per target (node + listener
+counts), `SystemInfo.getInfo` for GPU memory, `Memory.getAllTimeSamplingProfile`
+for a sampled native estimate.
+
+**Why:** Codex's outside-voice review flagged that
+`Performance.getMetrics` misses native memory, GPU memory, video
+buffers, Skia, network cache, extension process RSS, and
+browser-process RSS — all the categories where a 160 GB leak would
+actually live. A diagnostic that misses the categories where the
+leak class lives undersells itself.
+
+**Pros:** Per-process category breakdown closes the gap between
+"Activity Monitor says 160 GB" and what the diagnostic shows.
+**Cons:** Each CDP method has its own quirks; this is a real
+implementation pass, not a one-line addition.
+
+**Context:** Codex finding #5 on the eng-review outside voice. Not
+in scope of the v1.49 PR; deliberately deferred.
+
+**Priority:** P2. **Effort:** M.
+
+---
+
+### P3: Single-context CDP listener for Network.loadingFinished
+
+**What:** `wirePageEvents` attaches a `page.on('requestfinished')`
+listener PER PAGE. The D10 fix removed the body-materialization leak
+inside that listener but kept the per-page listener architecture
+(7 listeners attached per tab — close, framenavigated, dialog,
+console, request, response, requestfinished). The stretch goal from
+D10 was to replace the per-page `requestfinished` listener with a
+single context-level CDP listener via
+`Target.setAutoAttach({autoAttach: true, waitForDebuggerOnStart: false,
+flatten: true})` and a browser-wide `Network.loadingFinished` event
+handler.
+
+**Why:** Going from N to 1 listener for the request-size capture is
+structurally the right architecture and removes one piece of per-tab
+memory pressure. The body-materialization fix already addressed the
+acute leak; this is the architectural cleanup that prevents similar
+leaks in the same class.
+
+**Pros:** One listener per browser instead of one per tab.
+**Cons:** `Target.setAutoAttach` plumbing is more code than the
+straight per-page listener; the marginal memory win is small on top
+of the body-fetch fix that already landed.
+
+**Context:** D10 stretch goal on the eng-review. The minimal-risk
+fix shipped in v1.49 (replaces `await res.body()` with
+`await req.sizes()`, preserving the per-page listener); this is the
+architectural follow-up.
+
+**Priority:** P3. **Effort:** M-L.
+
+---
+
+### P3: Real-Chromium peak-RSS reproducer (periodic tier)
+
+**What:** The gate-tier reproducer
+(`browse/test/memory-leak-reproducer.test.ts`) pins the invariant
+that `res.body()` is never called during a burst of
+`requestfinished` events. It uses a fake page; it does NOT spin up a
+real Chromium nor measure peak Bun RSS during a real concurrent fetch
+burst. A periodic-tier follow-up should: spin up a real headless
+Chromium, navigate to a fixture page that concurrently fetches 500
+mixed responses (small JSON, 100 KB images, 10 MB chunked,
+gzip-compressed 2 MB), sample `process.memoryUsage().heapUsed` every
+100 ms during the burst, assert `peak_heap < 200 MB above baseline`
+AND `post-gc_heap < 30 MB above baseline`. Also include a single-tab
+WebGL canvas variant that grows to >4 GB and asserts the per-tab RSS
+toast fires.
+
+**Why:** Codex flagged that the leak's real failure mode is transient
+amplification under concurrent burst, not retained leak — a steady-state
+heap test misses it. The fake-page gate-tier test catches the
+listener-architecture regression; the periodic real-browser test
+catches the actual peak-RSS class.
+
+**Pros:** Closes the "did we actually demonstrate the OOM is fixed"
+question with hard numbers. Feeds the ANGLE_B_NUMBERS CHANGELOG
+release-summary table.
+**Cons:** Periodic tier costs minutes of CI time and money per run;
+real-browser memory tests are inherently flaky.
+
+**Context:** Codex outside-voice finding on the eng-review; D7
+ANGLE_B_NUMBERS CHANGELOG framing needs this reproducer's numbers
+before /ship time.
+
+**Priority:** P3. **Effort:** M.
+
+---
+
 ## design daemon: follow-ups (filed v1.45.0.0 via /ship review army)
 
 ### ✅ DONE (v1.45.0.0): Tighten daemon test coverage
 
@@ -1 +1 @@
-1.48.0.0
+1.51.0.0
@@ -921,6 +921,7 @@ $B prettyscreenshot --cleanup --scroll-to ".pricing" --width 1440 ~/Desktop/hero
 | `disconnect` | Disconnect headed browser, return to headless mode |
 | `focus [@ref]` | Bring headed browser window to foreground (macOS) |
 | `handoff [message]` | Open visible Chrome at current page for user takeover |
+| `memory [--json]` | Snapshot Bun heap + per-tab JS heap + Chromium process tree + bounded buffer sizes. JSON output with --json. |
 | `restart` | Restart server |
 | `resume` | Re-snapshot after user takeover, return control to AI |
 | `state save|load <name>` | Save/load browser state (cookies + URLs) |