tab guardrail (50/200 thresholds) + sidebar action toast

Server side (browser-manager.ts):
Idempotent threshold tracker fires an activity entry exactly once at
each upward crossing of 50 (soft warn) and 200 (hard warn). Re-arms
when the count drops below. Activity-feed surface gives the
audit-trail invariant even with the sidebar closed; the toast UX
lives in the sidebar.

Sidebar side (extension/sidepanel.{html,css,js}):
Every /memory poll evaluates two trigger conditions:
  - Any single tab > 4 GB JS heap (catches the WebGL/video runaway
    case Codex flagged on the eng review).
  - Tab count >= 200.
Toast shows top 5 tabs ranked by max(jsHeap, nodes*1KB + listeners*200)
so a WebGL-heavy tab with small JS heap still surfaces. Default-selected
checkboxes + "Close selected" run \`\$B closetab <id>\` through the
existing /command path — no chrome.tabs.remove bridge needed. "Snooze"
bumps tabsAbove/heapAbove thresholds in chrome.storage.session so the
toast stays hidden until the user accumulates more tabs OR one tab
grows another 2 GB.

Tests: browse/test/tab-guardrail.test.ts pins the server-side
fires-once + re-arms invariants without spinning up Chromium.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan 2026-05-27 07:32:26 -07:00
parent 78afd75e72
commit 50387c350c
No known key found for this signature in database
GPG Key ID: C1F69E85C74EFE1D
5 changed files with 458 additions and 0 deletions

View File

@ -18,6 +18,7 @@
import { chromium, type Browser, type BrowserContext, type BrowserContextOptions, type Page, type Locator, type Cookie } from 'playwright';
import { writeSecureFile, mkdirSecure } from './file-permissions';
import { addConsoleEntry, addNetworkEntry, addDialogEntry, networkBuffer, type DialogEntry } from './buffers';
import { emitActivity } from './activity';
import { validateNavigationUrl } from './url-validation';
import { TabSession, type RefEntry } from './tab-session';
import { resolveChromiumProfile, cleanSingletonLocks } from './config';
@ -196,6 +197,51 @@ export class BrowserManager {
private connectionMode: 'launched' | 'headed' = 'launched';
private intentionalDisconnect = false;
// ─── Tab Count Guardrail (D5 + Codex single-tab flag) ───────
// Idempotent threshold trackers: each guardrail fires exactly once per
// upward crossing of its threshold and re-arms when the tab count drops
// back below. Pre-guardrail, nothing tracked tab count growth and a
// user could accumulate hundreds of tabs (each holding 50300 MB of
// Chromium-side RSS) without warning until the OS OOM-killer fired.
// The toast UX lives in the sidebar (extension/sidepanel.js); the
// server-side responsibility is the audit-trail activity entry that
// appears in the activity feed even when the sidebar is closed.
private static readonly TAB_GUARDRAIL_SOFT = 50;
private static readonly TAB_GUARDRAIL_HARD = 200;
private tabGuardrailSoftHit = false;
private tabGuardrailHardHit = false;
/**
* Called from context.on('page') after a new tab is tracked. Emits at
* most one activity entry per upward crossing of each threshold.
*/
private checkTabGuardrails(): void {
const total = this.pages.size;
if (!this.tabGuardrailSoftHit && total >= BrowserManager.TAB_GUARDRAIL_SOFT) {
this.tabGuardrailSoftHit = true;
const msg = `Tab count crossed ${BrowserManager.TAB_GUARDRAIL_SOFT} (now ${total}). Consider closing unused tabs — each Chromium tab holds 50300 MB.`;
console.warn(`[browse] ${msg}`);
emitActivity({ type: 'error', command: 'tab-guardrail', error: msg, tabs: total });
}
if (!this.tabGuardrailHardHit && total >= BrowserManager.TAB_GUARDRAIL_HARD) {
this.tabGuardrailHardHit = true;
const msg = `Tab count crossed ${BrowserManager.TAB_GUARDRAIL_HARD} (now ${total}). OOM risk imminent. Open the sidebar to see top RAM consumers.`;
console.error(`[browse] ${msg}`);
emitActivity({ type: 'error', command: 'tab-guardrail', error: msg, tabs: total });
}
}
/** Called from page.on('close') so the guardrails re-arm. */
private recheckTabGuardrailsOnClose(): void {
const total = this.pages.size;
if (this.tabGuardrailSoftHit && total < BrowserManager.TAB_GUARDRAIL_SOFT) {
this.tabGuardrailSoftHit = false;
}
if (this.tabGuardrailHardHit && total < BrowserManager.TAB_GUARDRAIL_HARD) {
this.tabGuardrailHardHit = false;
}
}
// Called when the headed browser disconnects without intentional teardown
// (user closed the window). Wired up by server.ts to run full cleanup
// (sidebar-agent, state file, profile locks) before exiting with code 2.
@ -622,6 +668,7 @@ export class BrowserManager {
// Inject indicator on the new tab
page.evaluate(indicatorScript).catch(() => {});
console.log(`[browse] New tab detected (id=${id}, total=${this.pages.size})`);
this.checkTabGuardrails();
});
// Persistent context opens a default page — adopt it instead of creating a new one
@ -1642,6 +1689,7 @@ export class BrowserManager {
break;
}
}
this.recheckTabGuardrailsOnClose();
});
// Clear ref map on navigation — refs point to stale elements after page change

View File

@ -0,0 +1,118 @@
import { describe, test, expect, beforeEach } from 'bun:test';
import { BrowserManager } from '../src/browser-manager';
import { subscribe } from '../src/activity';
// Tests for the tab-count guardrail. Each threshold fires exactly once per
// upward crossing and re-arms when the count drops back below. The toast
// UX lives in the sidebar; this exercises the server-side audit-trail
// invariant that an activity entry is emitted at each crossing.
interface CapturedEntry {
type: string;
command?: string;
error?: string;
tabs?: number;
}
function captureGuardrailEntries(): { entries: CapturedEntry[]; unsubscribe: () => void } {
const entries: CapturedEntry[] = [];
const unsubscribe = subscribe((entry) => {
if (entry.command === 'tab-guardrail') {
entries.push({
type: entry.type,
command: entry.command,
error: entry.error,
tabs: entry.tabs,
});
}
});
return { entries, unsubscribe };
}
/** Drive the guardrail by writing directly into the manager's pages map. */
async function setTabCount(bm: BrowserManager, n: number): Promise<void> {
// Reach into private state via index access — test-only manipulation that
// avoids spinning up a real Chromium just to verify the threshold math.
const inner = bm as unknown as {
pages: Map<number, unknown>;
checkTabGuardrails: () => void;
recheckTabGuardrailsOnClose: () => void;
};
inner.pages.clear();
for (let i = 0; i < n; i++) inner.pages.set(i, { fakeTab: true });
// Drive whichever direction matches the count change.
inner.checkTabGuardrails();
inner.recheckTabGuardrailsOnClose();
// emitActivity dispatches subscribers via queueMicrotask, so let the
// microtask queue drain before the test assertion runs.
await new Promise((r) => setTimeout(r, 0));
}
describe('tab-count guardrail', () => {
let bm: BrowserManager;
let capture: ReturnType<typeof captureGuardrailEntries>;
beforeEach(() => {
bm = new BrowserManager();
capture = captureGuardrailEntries();
});
test('1. no entry fires under the soft threshold', async () => {
await setTabCount(bm, 10);
await setTabCount(bm, 49);
expect(capture.entries).toEqual([]);
capture.unsubscribe();
});
test('2. soft threshold (50) fires exactly once on upward crossing', async () => {
await setTabCount(bm, 49);
await setTabCount(bm, 50);
await setTabCount(bm, 51);
await setTabCount(bm, 60);
expect(capture.entries.length).toBe(1);
expect(capture.entries[0].tabs).toBe(50);
expect(capture.entries[0].error).toContain('crossed 50');
capture.unsubscribe();
});
test('3. hard threshold (200) fires exactly once on upward crossing', async () => {
await setTabCount(bm, 199);
await setTabCount(bm, 200);
await setTabCount(bm, 201);
await setTabCount(bm, 220);
// 0 → 199 fired the soft threshold; 199 → 200 fires the hard one once.
const hardEntries = capture.entries.filter((e) => e.error?.includes('crossed 200'));
expect(hardEntries.length).toBe(1);
expect(hardEntries[0].tabs).toBe(200);
capture.unsubscribe();
});
test('4. both thresholds fire in order when count jumps from 0 → 250', async () => {
await setTabCount(bm, 250);
expect(capture.entries.length).toBe(2);
expect(capture.entries[0].error).toContain('crossed 50');
expect(capture.entries[1].error).toContain('crossed 200');
capture.unsubscribe();
});
test('5. soft threshold re-arms when tab count drops below it', async () => {
await setTabCount(bm, 60);
expect(capture.entries.length).toBe(1);
await setTabCount(bm, 30);
await setTabCount(bm, 55);
expect(capture.entries.length).toBe(2);
expect(capture.entries[1].error).toContain('crossed 50');
capture.unsubscribe();
});
test('6. hard threshold re-arms when tab count drops below it', async () => {
await setTabCount(bm, 210);
const beforeReArm = capture.entries.filter((e) => e.error?.includes('crossed 200')).length;
expect(beforeReArm).toBe(1);
await setTabCount(bm, 150);
await setTabCount(bm, 220);
const afterReArm = capture.entries.filter((e) => e.error?.includes('crossed 200')).length;
expect(afterReArm).toBe(2);
capture.unsubscribe();
});
});

View File

@ -1152,6 +1152,88 @@ footer {
.footer-mem.bad {
color: #ef4444;
}
/* ─── Memory pressure toast ─────────────────────────────────── */
.mem-toast {
position: fixed;
left: 12px;
right: 12px;
bottom: 44px;
z-index: 9999;
background: var(--bg-elevated, #1f1f23);
border: 1px solid #ef4444;
border-radius: var(--radius-md, 6px);
padding: 12px;
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
font-family: var(--font-sans);
font-size: 12px;
}
.mem-toast-header {
display: flex;
align-items: center;
justify-content: space-between;
margin-bottom: 8px;
}
.mem-toast-header strong {
color: var(--text-heading);
font-size: 13px;
}
.mem-toast-close {
background: transparent;
border: none;
color: var(--text-meta);
cursor: pointer;
font-size: 18px;
line-height: 1;
padding: 0 4px;
}
.mem-toast-close:hover { color: var(--text-heading); }
.mem-toast-body {
margin-bottom: 8px;
color: var(--text-body);
line-height: 1.4;
}
.mem-toast-body .mem-toast-row {
display: flex;
align-items: center;
gap: 8px;
padding: 4px 0;
}
.mem-toast-body .mem-toast-row label {
flex: 1;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
cursor: pointer;
}
.mem-toast-body .mem-toast-size {
font-family: var(--font-mono);
font-size: 11px;
color: var(--text-meta);
width: 70px;
text-align: right;
}
.mem-toast-actions {
display: flex;
gap: 8px;
justify-content: flex-end;
}
.mem-toast-btn {
background: var(--bg-base);
border: 1px solid var(--zinc-600);
border-radius: var(--radius-sm, 4px);
color: var(--text-body);
cursor: pointer;
font-size: 12px;
padding: 4px 12px;
}
.mem-toast-btn:hover { background: var(--zinc-700); }
.mem-toast-btn.primary {
background: #ef4444;
border-color: #ef4444;
color: #fff;
}
.mem-toast-btn.primary:hover { background: #dc2626; }
.port-input {
width: 56px;
padding: 2px 6px;

View File

@ -159,6 +159,19 @@
</div>
</main>
<!-- Tab guardrail toast (hidden until /memory poll trips a threshold) -->
<div class="mem-toast" id="mem-toast" role="dialog" aria-label="Memory pressure warning" style="display:none">
<div class="mem-toast-header">
<strong id="mem-toast-title">High memory pressure</strong>
<button class="mem-toast-close" id="mem-toast-close" aria-label="Dismiss">&times;</button>
</div>
<div class="mem-toast-body" id="mem-toast-body"></div>
<div class="mem-toast-actions">
<button class="mem-toast-btn primary" id="mem-toast-close-selected">Close selected</button>
<button class="mem-toast-btn" id="mem-toast-snooze">Snooze</button>
</div>
</div>
<!-- Footer with connection + debug toggle -->
<footer>
<div class="footer-left">

View File

@ -341,6 +341,11 @@ async function pollMemoryOnce() {
if (!resp.ok) return { ok: false, slow: elapsed > MEM_POLL_SLOW_THRESHOLD_MS };
const snapshot = await resp.json();
renderMemFooter(snapshot);
// Evaluate guardrail triggers (single-heavy-tab OR tab-count crossing 200).
// Toast is hidden when no trigger fires; snooze state suppresses re-fire.
try { evaluateMemToast(snapshot); } catch (err) {
console.debug('[gstack sidebar] mem-toast evaluation failed:', err && err.message);
}
return { ok: true, slow: elapsed > MEM_POLL_SLOW_THRESHOLD_MS };
} catch (err) {
const elapsed = Date.now() - start;
@ -383,6 +388,198 @@ function stopMemPolling() {
}
}
// ─── Tab guardrail toast (D5 + Codex single-tab flag) ───────
//
// Each /memory poll evaluates two trigger conditions:
// 1. Tab count crossed 200 — show "top 5 tabs by max(jsHeap, ...)" with
// Close-selected + Snooze.
// 2. Any single tab over 4 GB JS heap — show one-tab toast (catches the
// Codex case where a runaway WebGL/video page balloons one tab).
// Snooze persists in chrome.storage.session: next warn fires at tabCount +
// snoozeBumpTabs OR when a single tab crosses (snoozedJsHeapBytes + 1).
//
// "Close selected" runs $B closetab <id> via the existing /command path —
// no chrome.tabs.remove bridge needed.
const HEAVY_TAB_HEAP_BYTES = 4 * 1024 * 1024 * 1024; // 4 GB per Codex flag
const TOAST_SNOOZE_TAB_BUMP = 50; // re-warn at 200+50
const TOAST_SNOOZE_HEAP_BUMP = 2 * 1024 * 1024 * 1024;
const memToastSnooze = {
tabsAbove: 0, // suppress the count-toast until tabs strictly exceeds this
heapAbove: 0, // suppress the single-tab toast until heap strictly exceeds this
};
async function loadSnoozeState() {
if (!chrome?.storage?.session) return;
try {
const stored = await chrome.storage.session.get(['memToastSnooze']);
if (stored?.memToastSnooze) {
memToastSnooze.tabsAbove = stored.memToastSnooze.tabsAbove | 0;
memToastSnooze.heapAbove = stored.memToastSnooze.heapAbove | 0;
}
} catch (err) {
console.debug('[gstack sidebar] mem-toast snooze load failed:', err && err.message);
}
}
async function saveSnoozeState() {
if (!chrome?.storage?.session) return;
try {
await chrome.storage.session.set({ memToastSnooze: { ...memToastSnooze } });
} catch (err) {
console.debug('[gstack sidebar] mem-toast snooze save failed:', err && err.message);
}
}
function dismissMemToast() {
const toast = document.getElementById('mem-toast');
if (toast) toast.style.display = 'none';
}
/**
* Sort key for "RAM-heavy" tabs. JS heap × 4 is a rough proxy for total
* tab footprint (renderers tend to spend ~4× their JS heap on native +
* Skia + cache); when a tab is heavy via WebGL/video the JS heap is
* small but listeners/nodes spike. Take the max.
*/
function tabRamScore(tab) {
const heap = tab?.jsHeapUsed || 0;
const nodes = tab?.nodes || 0;
const listeners = tab?.listeners || 0;
// ~1 KB per DOM node + ~200 bytes per listener as a back-of-envelope
// native-memory estimate. Keeps the sort meaningful when JS heap is small.
const nativeEstimate = nodes * 1024 + listeners * 200;
return Math.max(heap, nativeEstimate);
}
function showMemToast(title, body, tabsForClose) {
const toast = document.getElementById('mem-toast');
const titleEl = document.getElementById('mem-toast-title');
const bodyEl = document.getElementById('mem-toast-body');
const closeBtn = document.getElementById('mem-toast-close-selected');
if (!toast || !titleEl || !bodyEl || !closeBtn) return;
titleEl.textContent = title;
bodyEl.innerHTML = '';
for (const t of tabsForClose) {
const row = document.createElement('div');
row.className = 'mem-toast-row';
const cb = document.createElement('input');
cb.type = 'checkbox';
cb.id = `mem-toast-tab-${t.id}`;
cb.value = String(t.id);
cb.checked = true; // default-selected so a fast user just hits Close
const label = document.createElement('label');
label.htmlFor = cb.id;
const urlShort = (t.url || '').length > 50 ? t.url.slice(0, 47) + '...' : (t.url || '(no url)');
label.textContent = `tab #${t.id}${urlShort}`;
const size = document.createElement('span');
size.className = 'mem-toast-size';
size.textContent = fmtBytesShort(tabRamScore(t));
row.appendChild(cb);
row.appendChild(label);
row.appendChild(size);
bodyEl.appendChild(row);
}
toast.style.display = '';
closeBtn.onclick = async () => {
const ids = tabsForClose
.filter((t) => document.getElementById(`mem-toast-tab-${t.id}`)?.checked)
.map((t) => t.id);
dismissMemToast();
for (const id of ids) {
try {
await fetch(`${serverUrl}/command`, {
method: 'POST',
headers: authHeaders(),
body: JSON.stringify({ command: 'closetab', args: [String(id)] }),
});
} catch (err) {
console.warn('[gstack sidebar] mem-toast closetab failed:', id, err && err.message);
}
}
};
}
/**
* Driven by every successful /memory poll. Decides whether to surface
* the toast and which payload to show.
*/
function evaluateMemToast(snapshot) {
if (!snapshot || !Array.isArray(snapshot.tabs)) return;
const tabs = snapshot.tabs;
// Trigger 1: any single tab over 4 GB JS heap. Catches the WebGL/video
// case before the tab count threshold ever fires.
const heavyTab = tabs.find((t) => (t.jsHeapUsed || 0) > HEAVY_TAB_HEAP_BYTES);
if (heavyTab && (heavyTab.jsHeapUsed || 0) > memToastSnooze.heapAbove) {
showMemToast(
`Heavy tab: ${fmtBytesShort(heavyTab.jsHeapUsed)} JS heap`,
'',
[heavyTab],
);
return;
}
// Trigger 2: tab count crossed the hard guardrail (200) and isn't snoozed.
if (tabs.length >= 200 && tabs.length > memToastSnooze.tabsAbove) {
const top5 = [...tabs].sort((a, b) => tabRamScore(b) - tabRamScore(a)).slice(0, 5);
showMemToast(
`${tabs.length} tabs open — close some?`,
'',
top5,
);
return;
}
// No trigger: keep toast hidden.
}
function setupMemToastWiring() {
const close = document.getElementById('mem-toast-close');
if (close) close.addEventListener('click', dismissMemToast);
const snooze = document.getElementById('mem-toast-snooze');
if (snooze) {
snooze.addEventListener('click', async () => {
// Snooze logic: bump the thresholds above the current snapshot so the
// toast won't re-fire until the user has accumulated MORE tabs or one
// tab has grown ANOTHER 2 GB beyond what we just warned about. Stored
// in chrome.storage.session so a sidebar reload doesn't lose the
// snooze (but a Chrome restart does).
try {
const resp = await fetch(`${serverUrl}/memory`, {
headers: { 'Authorization': `Bearer ${serverToken}` },
signal: AbortSignal.timeout(MEM_POLL_TIMEOUT_MS),
credentials: 'include',
});
if (resp.ok) {
const snap = await resp.json();
const tabs = Array.isArray(snap.tabs) ? snap.tabs : [];
memToastSnooze.tabsAbove = tabs.length + TOAST_SNOOZE_TAB_BUMP;
const maxHeap = tabs.reduce((m, t) => Math.max(m, t.jsHeapUsed || 0), 0);
memToastSnooze.heapAbove = maxHeap + TOAST_SNOOZE_HEAP_BUMP;
await saveSnoozeState();
}
} catch (err) {
console.debug('[gstack sidebar] mem-toast snooze fetch failed:', err && err.message);
}
dismissMemToast();
});
}
void loadSnoozeState();
}
// Wire the toast on DOM ready.
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', setupMemToastWiring);
} else {
setupMemToastWiring();
}
// ─── Refs Tab ───────────────────────────────────────────────────
async function fetchRefs() {