Merge remote-tracking branch 'origin/main' into stevenbarragan/pin-chromium-launch-headed

* origin/main:
  v1.42.1.0 feat: gate terminal-agent teardown on ServerConfig.ownsTerminalAgent (unblocks gbrowser embedder) (garrytan#1615)
  v1.42.0.0 Daegu wave: 23 community-filed bugs + PTY classifier enforcement (24 bisect commits) (garrytan#1594)
  v1.41.1.0 fix wave: 7 HIGH bugs from external audit + regression tests (PR garrytan#1169 follow-up) (garrytan#1592)

Author: stevenbarragan

.github/workflows/windows-setup-e2e.yml

@@ -0,0 +1,96 @@
+name: Windows Setup E2E
+
+# End-to-end fresh-install gate for Windows. Runs `./setup` on a clean
+# windows-latest checkout and asserts the build completes, binaries
+# resolve via find-browse, and the gstack-paths state root resolves
+# cleanly. Catches Bun shell-parser regressions in package.json's build
+# chain (#1538, #1537, #1530, #1457, #1561) before they reach users.
+#
+# Separate from windows-free-tests.yml because that one runs a curated
+# unit-test subset; this one exercises the install path itself.
+#
+# Runner: GitHub-hosted free windows-latest. ~3-5 min total.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'package.json'
+      - 'scripts/build.sh'
+      - 'scripts/write-version-files.sh'
+      - 'setup'
+      - 'browse/src/cli.ts'
+      - 'browse/src/find-browse.ts'
+      - 'bin/gstack-paths'
+      - '.github/workflows/windows-setup-e2e.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: windows-setup-e2e-${{ github.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  windows-setup:
+    runs-on: windows-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Configure git identity
+        run: |
+          git config --global user.email "windows-setup-e2e@gstack.test"
+          git config --global user.name "Windows Setup E2E"
+          git config --global init.defaultBranch main
+        shell: bash
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+        shell: bash
+
+      - name: Run bun run build (the previously-broken path)
+        # This is the regression gate. Bun's Windows shell parser rejected
+        # multiple constructs the old inline build chain used; the wave
+        # moved the build to scripts/build.sh. If this step fails on
+        # Windows, the build chain regressed.
+        run: bun run build
+        shell: bash
+        env:
+          GSTACK_SKIP_PLAYWRIGHT: '1'
+
+      - name: Verify binaries exist (with .exe extension on Windows)
+        run: |
+          set -e
+          test -f browse/dist/browse.exe || test -f browse/dist/browse || (echo "MISSING: browse" && exit 1)
+          test -f browse/dist/find-browse.exe || test -f browse/dist/find-browse || (echo "MISSING: find-browse" && exit 1)
+          test -f design/dist/design.exe || test -f design/dist/design || (echo "MISSING: design" && exit 1)
+          test -f bin/gstack-global-discover.exe || test -f bin/gstack-global-discover || (echo "MISSING: gstack-global-discover" && exit 1)
+          echo "All binaries present"
+        shell: bash
+
+      - name: Verify find-browse resolves to the .exe variant
+        run: |
+          set -e
+          OUT=$(bun browse/src/find-browse.ts 2>&1) || true
+          echo "find-browse output: $OUT"
+          # On Windows, find-browse should successfully resolve to a binary,
+          # whether or not it has the .exe extension on disk. Empty output
+          # or "not found" means the .exe extension resolver regressed.
+          echo "$OUT" | grep -qE '(browse\.exe|browse)$' || (echo "find-browse failed to resolve binary on Windows" && exit 1)
+        shell: bash
+
+      - name: Verify gstack-paths state root resolves
+        run: |
+          set -e
+          eval "$(bash bin/gstack-paths)"
+          test -n "$GSTACK_STATE_ROOT" || (echo "GSTACK_STATE_ROOT empty" && exit 1)
+          test -n "$PLAN_ROOT" || (echo "PLAN_ROOT empty" && exit 1)
+          test -n "$TMP_ROOT" || (echo "TMP_ROOT empty" && exit 1)
+          echo "GSTACK_STATE_ROOT=$GSTACK_STATE_ROOT"
+          echo "PLAN_ROOT=$PLAN_ROOT"
+          echo "TMP_ROOT=$TMP_ROOT"
+        shell: bash

.gitignore

@@ -4,7 +4,7 @@ dist/
 browse/dist/
 design/dist/
 make-pdf/dist/
-bin/gstack-global-discover
+bin/gstack-global-discover*
 .gstack/
 .claude/skills/
 .claude/scheduled_tasks.lock

CHANGELOG.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
+`<stateDir>/terminal-port` and `<stateDir>/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

CLAUDE.md

@@ -395,7 +395,7 @@ Four paths, pick one:
 - **PGLite local** — zero accounts, zero network, ~30 seconds. Isolated brain on this Mac only. Great for try-first; migrate to Supabase later with `/setup-gbrain --switch`.
 - **Remote gbrain MCP** — your brain runs on another machine (Tailscale, ngrok, internal LAN) or a teammate's server; paste an MCP URL and bearer token. Optionally pair with a local PGLite for symbol-aware code search in split-engine mode. Best for cross-machine memory without standing up a local DB.
 
-After init, the skill offers to register gbrain as an MCP server for Claude Code (`claude mcp add gbrain -- gbrain serve`) so `gbrain search`, `gbrain put_page`, etc. show up as first-class typed tools — not bash shell-outs.
+After init, the skill offers to register gbrain as an MCP server for Claude Code (`claude mcp add gbrain -- gbrain serve`) so `gbrain search`, `gbrain put`, etc. show up as first-class typed tools — not bash shell-outs.
 
 **Keeping the brain current.** Run `/sync-gbrain` from any repo to re-index its code into gbrain (incremental by default, `--full` for a full reindex, `--dry-run` to preview). The skill registers the cwd as a federated source via `gbrain sources add`, runs `gbrain sync --strategy code`, and writes a `## GBrain Search Guidance` block to your project's CLAUDE.md so the agent prefers `gbrain search`/`code-def`/`code-refs` over Grep. The block is removed automatically if the capability check fails — no stale guidance pointing at tools that aren't installed.
 

README.md

@@ -1,5 +1,99 @@
 # TODOS
 
+## browse server: terminal-agent teardown follow-ups (filed v1.41 via /plan-eng-review)
+
+### P3: Identity-based terminal-agent kill (replace pkill regex with PID)
+
+**What:** Record the spawned terminal-agent PID at `browse/src/cli.ts:1057` and
+replace `pkill -f terminal-agent\.ts` at both `cli.ts:1047` and
+`server.ts:1281` (now inside the `if (ownsTerminalAgent)` gate) with
+`process.kill(pid, signal)` against the recorded PID.
+
+**Why:** `pkill -f terminal-agent\.ts` matches by command-line regex, so today
+it can kill ANY process whose argv contains `terminal-agent.ts` — sibling
+gstack sessions, editor processes that have the file open, a second gstack
+run on the same host. Latent footgun for the CLI path, not just embedders.
+
+**Pros:** Removes a real cross-session foot-cannon. PID-based kill is the
+correct identity primitive. Lets us tighten `pkill -f`'s broad-match warning
+in the new `ownsTerminalAgent` JSDoc to "historical" rather than "current".
+
+**Cons:** Requires threading the PID through the CLI-to-server state path
+(currently the parent server reads `terminal-port` to discover the agent; it
+would also need `terminal-agent-pid`). Touches `cli.ts`, `server.ts`, and
+`terminal-agent.ts` together — bigger surface than the v1.41 fix.
+
+**Context:** Surfaced by both Codex and Claude subagent during /autoplan
+review of the `ownsTerminalAgent` gate. Currently documented as out-of-scope
+in `browse/src/server.ts` JSDoc for `ServerConfig.ownsTerminalAgent`. The
+embedder fix (ownsTerminalAgent: false) means embedders don't hit this; CLI
+users still do.
+
+**Depends on:** None.
+
+---
+
+### P3: shutdown() reads module-level `config`, not `cfg.config` (composition gap)
+
+**What:** `browse/src/server.ts:shutdown()` reads `path.dirname(config.stateFile)`
+where `config` is the module-level value resolved at import time, not the
+`cfg.config` passed into `buildFetchHandler`. Same gap applies to
+`cleanSingletonLocks(resolveChromiumProfile())` at server.ts:1298 — should
+read `cfg.chromiumProfile`.
+
+**Why:** Embedders today happen to share state-dir resolution with the CLI
+(both go through `resolveConfig()` against the same env), so this doesn't
+bite. But if an embedder ever passes a divergent `cfg.config` (e.g., a test
+harness pointing at a temp dir), shutdown will operate on the wrong paths.
+The `ownsTerminalAgent` flag exposes the problem without fixing it.
+
+**Pros:** Closes the embedder-composition story properly. Pairs with
+`cfg.chromiumProfile` to give a single coherent "this factory teardown
+respects cfg" contract.
+
+**Cons:** Pre-existing — not a regression. Two call sites today (1285 for
+terminal files, 1298 for chromium locks). Threading `cfg.config` and
+`cfg.chromiumProfile` into the right closures is straightforward but
+broader than the v1.41 fix.
+
+**Context:** Flagged by both Codex and Claude subagent in the /plan-eng-review
+dual voices. Documented as out-of-scope in the v1.41 plan; same shape as the
+`chromiumProfile` PR-body note to the gbrowser team.
+
+**Depends on:** None.
+
+---
+
+### P3: Ownership-object refactor if a 4th caller-owned teardown gate appears
+
+**What:** Today `ServerConfig` has three caller-owned teardown gates:
+`xvfb?` (presence ⇒ don't close), `proxyBridge?` (same), and now
+`ownsTerminalAgent` (explicit boolean). If a 4th gate appears, collapse to
+`cfg.callerOwns?: Set<'terminalAgent' | 'xvfb' | 'proxyBridge' | ...>` or
+similar.
+
+**Why:** Three independent flags is below the refactor threshold — each
+field has clear, distinct semantics and the JSDoc voice is consistent. A
+fourth tips the cost balance: the per-field surface gets noisy, and
+"what does this factory own?" becomes a question you have to ask of three
+or four scattered fields instead of one explicit set.
+
+**Pros:** Single source of truth for "what gstack tears down". Trivial
+extension surface for future caller-owned resources. Easier to assert in
+tests ("the set should contain X, not Y").
+
+**Cons:** Premature today. The polarity-inversion note in the
+`ownsTerminalAgent` JSDoc only hurts a little — it's one anomaly, not a
+pattern. Refactoring now to an ownership object would touch every embedder.
+
+**Context:** Recommended by Claude subagent during /plan-ceo-review dual
+voice (autoplan). Trigger: a 4th caller-owned teardown gate in this same
+`ServerConfig` shape.
+
+**Depends on:** A 4th gate to motivate the refactor.
+
+---
+
 ## /sync-gbrain memory stage perf follow-up
 
 ### P2: Investigate `gbrain import` perf on large staging dirs

TODOS.md

@@ -82,7 +82,7 @@ By default the skill asks "Give Claude Code a typed tool surface for gbrain?" If
 claude mcp add gbrain -- gbrain serve
 ```
 
-That registers gbrain's stdio MCP server with Claude Code. Now `gbrain search`, `gbrain put_page`, `gbrain get_page`, etc. show up as first-class tools in every session, not bash shell-outs.
+That registers gbrain's stdio MCP server with Claude Code. Now `gbrain search`, `gbrain put`, `gbrain get`, etc. show up as first-class tools in every session, not bash shell-outs.
 
 **If `claude` is not on PATH**, the skill skips MCP registration gracefully with a manual-register hint. The CLI resolver still works from any skill that shells out to `gbrain` — MCP is an upgrade, not a prerequisite.
 
@@ -224,8 +224,8 @@ Gbrain itself ships with these that gstack wraps:
 | `gbrain migrate --to supabase --url ...` | Move a PGLite brain to Supabase (lossless, preserves source as backup) |
 | `gbrain migrate --to pglite` | Reverse migration |
 | `gbrain search "query"` | Search the brain |
-| `gbrain put_page --title "..." --tags "a,b" <<<"content"` | Write a page |
-| `gbrain get_page "<slug>"` | Fetch a page |
+| `gbrain put "<slug>" --content "<markdown-with-frontmatter>"` | Write a page (title/tags go in YAML frontmatter inside `--content`) |
+| `gbrain get "<slug>"` | Fetch a page |
 | `gbrain serve` | Start the MCP stdio server (used by `claude mcp add`) |
 
 ### Config files + state

USING_GBRAIN_WITH_GSTACK.md

@@ -1 +1 @@
-1.40.0.0
+1.42.1.0

VERSION

@@ -192,7 +192,10 @@ function resolveSkillFile(args: CliArgs): string | null {
 
 function gbrainAvailable(): boolean {
   try {
-    execFileSync("command", ["-v", "gbrain"], { stdio: "ignore" });
+    execFileSync("gbrain", ["--version"], {
+      stdio: "ignore",
+      timeout: MCP_TIMEOUT_MS,
+    });
     return true;
   } catch {
     return false;

bin/gstack-brain-context-load.ts

@@ -287,13 +287,20 @@ function gbrainSupportsSourcesRename(env?: NodeJS.ProcessEnv): boolean {
  * `env` is the environment passed to the spawned `gbrain` process; defaults
  * to `process.env`. Tests inject a PATH that points at a gbrain shim so the
  * helper can be exercised without a real gbrain CLI.
+ *
+ * Shape note: `gbrain sources list --json` returns `{sources: [...]}` (v0.20+);
+ * older versions returned a flat array. Accept both for forward/backward compat
+ * (mirrors `probeSource`/`sourcePageCount` in lib/gbrain-sources.ts).
  */
 export function sourceLocalPath(sourceId: string, env?: NodeJS.ProcessEnv): string | null {
-  const list = execGbrainJson<Array<{ id: string; local_path?: string }>>(
+  const raw = execGbrainJson<unknown>(
     ["sources", "list", "--json"],
     { baseEnv: env },
   );
-  if (!list) return null;
+  if (!raw) return null;
+  const list: Array<{ id?: string; local_path?: string }> = Array.isArray(raw)
+    ? (raw as Array<{ id?: string; local_path?: string }>)
+    : ((raw as { sources?: Array<{ id?: string; local_path?: string }> }).sources ?? []);
   const found = list.find((s) => s.id === sourceId);
   return found?.local_path ?? null;
 }