From 54b719ab2c9bc6bed6dbca8089d1a0c9b458563b Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 19 May 2026 19:29:13 -0700 Subject: [PATCH] docs: note ServerConfig.ownsTerminalAgent in CLAUDE.md sidebar block Adds a one-paragraph reference for the v1.42.1.0 embedder teardown gate right after the Sidebar architecture block. Covers default semantics, when embedders must pass `false`, polarity inversion vs xvfb?/proxyBridge?, and the static-grep CI test that pins the CLI call site. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 6cbff85f9..3ff25fffe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -236,6 +236,20 @@ Activity / Refs / Inspector as debug overlays behind the footer's flow, dual-token model, and threat-model boundary — silent failures here usually trace to not understanding the cross-component flow. +**Embedder terminal-agent ownership** (v1.42.1.0+). `buildFetchHandler` +in `browse/src/server.ts` accepts `ServerConfig.ownsTerminalAgent?: +boolean` (default `true`). When `true`, factory shutdown runs the full +teardown: `pkill -f terminal-agent\.ts` plus `safeUnlinkQuiet` on +`/terminal-port` and `/terminal-internal-token`. +Embedders (e.g. the gbrowser phoenix overlay) that pre-launch their +own PTY server must pass `false` so their discovery files survive +gstack teardown cycles. The flag is the third caller-owned teardown +gate in `ServerConfig` (alongside `xvfb?` and `proxyBridge?`); polarity +is inverted (explicit bool vs presence) and documented in the field's +JSDoc. CLI `start()` always passes `true` explicitly — the static-grep +test in `browse/test/server-embedder-terminal-port.test.ts` fails CI +if a refactor drops it. + **WebSocket auth uses Sec-WebSocket-Protocol, not cookies.** Browsers can't set `Authorization` on a WebSocket upgrade, but they CAN set `Sec-WebSocket-Protocol` via `new WebSocket(url, [token])`. The agent