diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff6f9cf8..d144f1b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -86,6 +86,108 @@ Mutating flows (form fills, click sequences, multi-step automations) ship next a
 - The atomic-write helper enforces "no half-written skills." Always call `stageSkill` → run tests → `commitSkill` (success) OR `discardStaged` (failure). Never write directly to the final tier path. The helper's `validateSkillName` is the only naming gate, keep it tight (lowercase letters/digits/dashes, ≤64 chars, no consecutive dashes, no leading digit).
 - Phase 2b (`/automate`) and Phase 4 (Bun runtime distribution, OS FS sandbox, fixture-staleness detection) are tracked in `docs/designs/BROWSER_SKILLS_V1.md` and `TODOS.md`. The `/automate` skill reuses `/skillify` and `browser-skill-write.ts` as-is; new code is the per-mutating-step confirmation gate.
 
+## [1.17.0.0] - 2026-04-26
+
+## **Your gstack memory now actually lives in gbrain.**
+
+For everyone who ran `/setup-gbrain` in the last month and noticed `gbrain search` couldn't find their CEO plans, learnings, or retros: that's because Step 7 wrote a placeholder `consumers.json` with `status: "pending"` and called it done. The HTTP endpoint that placeholder pointed at was never built on the gbrain side. This release scraps that approach and uses the gbrain v0.18.0 federation surface (`gbrain sources` + `gbrain sync`) instead.
+
+After upgrading, `/setup-gbrain` adds a `git worktree` of your brain repo, registers it as a federated source on your gbrain (Supabase or PGLite), and runs an initial sync. Subsequent gstack skill end-of-run cycles also run `gbrain sync` so new artifacts land in the index automatically. Local-Mac only. No cloud agent required. `/gstack-upgrade` runs a one-shot migration for existing users.
+
+### Verify after upgrade
+
+```bash
+gbrain sources list --json | jq '.sources[] | {id, page_count, federated}'
+# Expect: two entries, your default brain plus a "gstack-brain-{user}"
+# entry, both federated=true.
+
+gbrain search "ethos" --source gstack-brain-{user} | head -5
+# Expect: hits from your gstack repo content (readme, ethos, designs, etc).
+```
+
+### What shipped
+
+`bin/gstack-gbrain-source-wireup` is the new helper. It derives a per-user source id from `~/.gstack/.git`'s origin URL (with multi-fallback to `~/.gstack-brain-remote.txt` and a `--source-id` flag), creates a detached `git worktree` at `~/.gstack-brain-worktree/`, registers it as a federated source on gbrain, runs initial backfill, and supports `--strict` (Step 7 strictness), `--uninstall` (full teardown including future-launchd plist), and `--probe` (read-only state inspection). All idempotent. The helper depends on `jq` (transitive via `gstack-gbrain-detect`).
+
+The helper locks the database URL at startup (precedence: `--database-url` flag > `GBRAIN_DATABASE_URL`/`DATABASE_URL` env > read once from `~/.gbrain/config.json`) and exports it as `GBRAIN_DATABASE_URL` for every child `gbrain` invocation. This means external rewrites of `~/.gbrain/config.json` mid-sync (e.g., a concurrent `gbrain init --non-interactive` running in another workspace) cannot redirect the wireup at a different brain. Per gbrain's `loadConfig()`, env-var URLs override the file. Step 7 of `/setup-gbrain` reads the URL out of `config.json` once and passes it explicitly via `--database-url`, so the wireup is robust against config flips during the seconds-to-minutes sync window.
+
+`/setup-gbrain` Step 7 now invokes the helper with `--strict` after `gstack-brain-init`. `/gstack-upgrade` invokes the helper without `--strict` via `gstack-upgrade/migrations/v1.12.3.0.sh` so missing/old gbrain is a benign skip during batch upgrade. `bin/gstack-brain-restore` invokes the helper after the initial clone so a 2nd Mac gets the wireup automatically. `bin/gstack-brain-uninstall` invokes `--uninstall` plus removes legacy `consumers.json`.
+
+`bin/gstack-brain-init` drops 60 lines of dead consumer-registration code (the HTTP POST block, the `consumers.json` writer, the chore commit). `bin/gstack-brain-restore` drops the 18-line `consumers.json` token-rehydration block (the only consumer that used it never had real tokens). `bin/gstack-brain-consumer` is marked deprecated in its header docstring; removal in v1.18.0.0 after one cycle of grace.
+
+`test/gstack-gbrain-source-wireup.test.ts` is new: 13 unit tests with a fake `gbrain` binary on `$PATH` covering fresh-state registration, idempotent re-runs, drift recovery (gbrain has no `sources update`, only `remove + add`), `--strict` failure modes, source-id fallback chain (`.git` → remote-file → flag), `--probe` non-mutation, sync errors, and `--uninstall`.
+
+### The numbers that matter
+
+These are reproducible on any machine after upgrade. Run the verify commands above to see your own delta.
+
+| Metric | Before (v1.16.0.0) | After (v1.17.0.0) |
+|---|---|---|
+| `gbrain sources list` size | 1 (default `/data/brain`) | 2 (default + `gstack-brain-{user}`) |
+| `consumers.json` status | `"pending"`, ingest_url `""` | file deleted from new installs |
+| Manual steps to wire up | 4 (clone + sources add + sync + cron) | 0, automatic in Step 7 |
+| Helper test coverage | 0 unit tests | 13 unit tests (`bun test test/gstack-gbrain-source-wireup.test.ts`) |
+| `bin/gstack-brain-init` size | 363 lines | 300 lines (60 lines of dead code removed) |
+
+Local Mac is the producer of artifacts and the worktree advances automatically with `~/.gstack/`'s commits. Cross-machine sync runs through GitHub via the existing `gstack-brain-sync --once` push hook. No new cron infrastructure needed today; when gbrain v0.21 code-graph features ship, the helper's `--enable-cron` flag is a clean extension.
+
+### What this means for builders
+
+Your gstack memory is searchable now. Run a CEO plan review or office-hours session, sync runs at skill-end automatically, and `gbrain search` finds the plan content from any gbrain client (this Claude Code session, future Macs, optional cloud agents like OpenClaw). One source of truth across machines. The placeholder is dead.
+
+### For contributors
+
+- `bin/gstack-brain-consumer` is deprecated in this release; removal in v1.18.0.0.
+- The `gbrain_url` and `gbrain_token` config keys are now no-ops. They remain readable for one cycle for back-compat, removed in v1.18.0.0.
+- Three pre-existing test failures on this branch (`gstack-config gbrain keys > GSTACK_HOME overrides real config dir`, `no compiled binaries in git > git tracks no files larger than 2MB`, `Opus 4.7 overlay — pacing directive`) were verified to fail on the base branch too. Out of scope for this PR; flagged for a follow-up.
+
+## [1.16.0.0] - 2026-04-28
+
+## **Paired-agent tunnel allowlist now matches what the docs already promised. Catch-22 resolved, gate is unit-testable.**
+
+The visible bug: a paired remote agent over the ngrok tunnel hit 403s on `newtab`, `tabs`, `goto-on-existing-tab`, and a chain of other commands the operator docs claimed worked. The hidden bug: the v1.6.0.0 `TUNNEL_COMMANDS` allowlist was set at 17 entries while `docs/REMOTE_BROWSER_ACCESS.md`, `browse/src/cli.ts:546-586`, and the operator-facing instruction blocks all documented 26. The shipped allowlist drifted from the design intent silently for releases. This release closes the gap: 9 commands added (`newtab`, `tabs`, `back`, `forward`, `reload`, `snapshot`, `fill`, `url`, `closetab`), each bounded by the existing per-tab ownership check at `server.ts:613-624`. Scoped tokens default to `tabPolicy: 'own-only'`, so a paired agent still can't navigate, fill, or close on tabs it doesn't own — same isolation as before, just covering more verbs.
+
+### The numbers that matter
+
+Branch totals come from `git diff --shortstat origin/main..HEAD`. Test counts come from `bun test browse/test/dual-listener.test.ts browse/test/tunnel-gate-unit.test.ts browse/test/pair-agent-tunnel-eval.test.ts browse/test/pair-agent-e2e.test.ts` against the merged tree.
+
+| Metric | Δ |
+|---|---|
+| Tunnel allowlist size | **17 → 26 commands** (+53%) |
+| Catch-22 resolution | `newtab` → `goto` → `back` chain works for the first time |
+| Gate testability | inline regex check → **pure exported `canDispatchOverTunnel()`** function |
+| New unit-test coverage | **53 expects** in `tunnel-gate-unit.test.ts` (allowed, blocked, null/undefined/non-string, alias canonicalization) |
+| New behavioral coverage | **4 tests** in `pair-agent-tunnel-eval.test.ts` running BOTH listeners locally (no ngrok) |
+| Source-level guard | exact-set equality against the 26-command literal + ownership-exemption regex |
+| All free tests | **69 pass / 0 fail** on the four touched test files |
+| Codex review passes | **2 outside-voice rounds** during plan mode, 6 of 7 findings incorporated |
+
+### What this means for users running paired agents
+
+Three things change immediately. **First**, paired agents can actually open and drive their own tab without hitting the catch-22 the prior allowlist created. `newtab` succeeds (the ownership-exemption at `server.ts:613` was always there, but the allowlist gated the entry); `goto`, `back`, `forward`, `reload`, `fill`, `closetab` all work on the just-created tab; `snapshot`, `url`, `tabs` give the agent the read-side surface needed to be useful. **Second**, the tunnel-surface gate is unit-testable now — `canDispatchOverTunnel(command)` is pure, exported from `browse/src/server.ts`, and covered by 53 expects. A future refactor that decouples the allowlist literal from the gate logic fails a free test in milliseconds. **Third**, `pair-agent-tunnel-eval.test.ts` exercises the gate end-to-end with BOTH the local and tunnel listeners bound on 127.0.0.1 (no ngrok required) so the routing decision — "this request hit the tunnel listener, run the gate; this one hit the local listener, skip the gate" — is asserted on every PR. The new `BROWSE_TUNNEL_LOCAL_ONLY=1` env var binds the second listener locally without invoking ngrok, gated to no-op outside test mode. Production tunnel still requires `BROWSE_TUNNEL=1` + a valid `NGROK_AUTHTOKEN`.
+
+### Itemized changes
+
+#### Added
+
+- 9 new commands in `browse/src/server.ts:111-120` `TUNNEL_COMMANDS` set: `newtab`, `tabs`, `back`, `forward`, `reload`, `snapshot`, `fill`, `url`, `closetab`. The set is now exported so tests can reference the literal directly.
+- `canDispatchOverTunnel(command: string | undefined | null): boolean` in `browse/src/server.ts` — pure exported function. Handles non-string input, runs `canonicalizeCommand` for alias resolution, returns `TUNNEL_COMMANDS.has(canonical)`.
+- `BROWSE_TUNNEL_LOCAL_ONLY=1` env var in `browse/src/server.ts:2080-2104`. Test-only sibling branch to `BROWSE_TUNNEL=1` that binds the second `Bun.serve` listener via `makeFetchHandler('tunnel')` without invoking ngrok. Persists `tunnelLocalPort` to the state file for the eval to read.
+- `browse/test/tunnel-gate-unit.test.ts`: 53 expects covering all 26 allowed commands, 20 blocked commands (pair, unpair, cookies, setup, launch, restart, stop, tunnel-start, token-mint, etc.), null/undefined/empty/non-string defensive handling, and alias canonicalization (e.g. `set-content` resolves to `load-html` and is correctly rejected since `load-html` isn't tunnel-allowed).
+- `browse/test/pair-agent-tunnel-eval.test.ts`: 4 behavioral tests that spawn the daemon under `BROWSE_HEADLESS_SKIP=1 BROWSE_TUNNEL_LOCAL_ONLY=1`, bind both listeners on 127.0.0.1, mint a scoped token via the existing `/pair` → `/connect` ceremony, and assert: (1) `newtab` over the tunnel passes the gate; (2) `pair` over the tunnel 403s with `disallowed_command:pair` AND writes a fresh denial-log entry to `~/.gstack/security/attempts.jsonl`; (3) `pair` over the local listener does NOT trigger the tunnel gate; (4) regression test for the catch-22 — `newtab` followed by `goto` on the resulting tab does not 403 with `Tab not owned by your agent`.
+
+#### Changed
+
+- `browse/test/dual-listener.test.ts`: must-include + must-exclude assertions replaced with one exact-set-equality test against the 26-command literal. The intersection-only style of the prior tests let new commands sneak into the source without a corresponding test update — the bidirectional check catches it both ways. Added a regex assertion that the `command !== 'newtab'` ownership-exemption clause at `server.ts:613` still exists (catches refactors that re-introduce the catch-22 from the other side).
+- `browse/test/dual-listener.test.ts`: `/command` handler test updated to assert the inline `TUNNEL_COMMANDS.has(cmd)` check is now `canDispatchOverTunnel(body?.command)` — proves the gate is delegated to the pure function and not duplicated.
+- `docs/REMOTE_BROWSER_ACCESS.md:35,168`: bumped "17-command allowlist" to "26-command allowlist". Corrected the denied-commands list (removed `eval`, which IS in the allowlist; the prior doc was wrong).
+- `CLAUDE.md`: bumped the transport-layer security section's "17-command browser-driving allowlist" reference to "26-command".
+
+#### For contributors
+
+- The plan was reviewed under `/plan-eng-review` plus 2 sequential codex outside-voice passes during plan mode. Round-1 codex caught a doc-target mistake (we were going to update `SIDEBAR_MESSAGE_FLOW.md` instead of `REMOTE_BROWSER_ACCESS.md`) and a wrong-layer test design. Round-2 codex caught that the round-1 correction was still wrong (the chosen test harness only binds the local listener) AND that the docs promised 6 more commands than the allowlist had. All 6 of 7 substantive findings landed in the implementation; the 7th (a pre-existing `/pair-agent` `/health` probe mismatch at `cli.ts:656-668`) is logged as out of scope.
+- One known accepted risk: `tabs` over the tunnel returns metadata for ALL tabs in the browser, not just tabs the agent owns. The user authored the trust relationship when they paired the agent, the agent already can't read CONTENT of unowned tabs (write commands blocked, the active tab can't be switched without a `tab <id>` command that's NOT in the allowlist), and tab IDs already leak via the 403 `hint` field on disallowed `goto`. Codex noted that tightening this requires touching the ownership gate itself (the gate falls back to `getActiveTabId()` BEFORE dispatch in `server.ts:603-614`), which is materially out of scope for a catch-22 fix. Logged in the plan failure-mode table as accepted.
+
 ## [1.15.0.0] - 2026-04-26
 
 ## **Real-PTY test harness ships. 11 plan-mode E2E tests, 23 unit tests, and 50K fewer tokens per invocation.**
diff --git a/CLAUDE.md b/CLAUDE.md
index 2e5ae567..cd08caf4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -258,7 +258,7 @@ through `POST /pty-session` only.
 **Transport-layer security** (v1.6.0.0+). When `pair-agent` starts an ngrok tunnel,
 the daemon binds two HTTP listeners: a local listener (127.0.0.1, full command
 surface, never forwarded) and a tunnel listener (locked allowlist: `/connect`,
-`/command` with a scoped token + 17-command browser-driving allowlist,
+`/command` with a scoped token + 26-command browser-driving allowlist,
 `/sidebar-chat`). ngrok forwards only the tunnel port. Root tokens over the tunnel
 return 403. SSE endpoints use a 30-minute HttpOnly `gstack_sse` cookie minted via
 `POST /sse-session` (never valid against `/command`). Tunnel-surface rejections go
diff --git a/USING_GBRAIN_WITH_GSTACK.md b/USING_GBRAIN_WITH_GSTACK.md
index f0dfb14c..17dea2b0 100644
--- a/USING_GBRAIN_WITH_GSTACK.md
+++ b/USING_GBRAIN_WITH_GSTACK.md
@@ -159,6 +159,7 @@ The skill re-collects a PAT (one-time, discarded after), lists every project in
 | `gstack-gbrain-supabase-verify` | Structural URL check. Rejects direct-connection URLs (`db.*.supabase.co:5432`) with exit 3 |
 | `gstack-gbrain-supabase-provision` | Management API wrapper. Subcommands: `list-orgs`, `create`, `wait`, `pooler-url`, `list-orphans`, `delete-project`. All require `SUPABASE_ACCESS_TOKEN` in env. `create` and `pooler-url` also require `DB_PASS`. `--json` mode available on every subcommand. |
 | `gstack-gbrain-repo-policy` | Per-remote trust triad. Subcommands: `get`, `set`, `list`, `normalize` |
+| `gstack-gbrain-source-wireup` | Registers your `~/.gstack/` brain repo with gbrain as a federated source via `gbrain sources add` + `git worktree`, then runs an initial `gbrain sync`. Idempotent. Replaces the dead `consumers.json + /ingest-repo` HTTP wireup from v1.12.x. Flags: `--strict`, `--source-id <id>`, `--no-pull`, `--uninstall`, `--probe`. |
 
 ### gbrain CLI (upstream tool)
 
diff --git a/bin/gstack-brain-consumer b/bin/gstack-brain-consumer
index cf92ea3e..12403ae5 100755
--- a/bin/gstack-brain-consumer
+++ b/bin/gstack-brain-consumer
@@ -1,6 +1,11 @@
 #!/usr/bin/env bash
 # gstack-brain-consumer — manage the consumer (reader) registry.
 #
+# DEPRECATED in v1.17.0.0. This binary targets a gbrain HTTP /ingest-repo
+# endpoint that never shipped on the gbrain side. Live federation now uses
+# `gbrain sources` directly via bin/gstack-gbrain-source-wireup. This file
+# stays for one cycle to avoid breaking external scripts; removal in v1.18.0.0.
+#
 # Consumer = a reader that ingests the gstack-brain git repo as a source of
 # session memory. v1 primary consumer is GBrain; later versions can register
 # Codex, OpenClaw, or third-party readers.
diff --git a/bin/gstack-brain-init b/bin/gstack-brain-init
index 3ed48559..4bf665cc 100755
--- a/bin/gstack-brain-init
+++ b/bin/gstack-brain-init
@@ -22,11 +22,9 @@
 #   8. Prompt for remote (default: gh repo create --private gstack-brain-$USER)
 #   9. Initial commit + push
 #   10. Write ~/.gstack-brain-remote.txt  (URL-only, safe to share)
-#   11. Register GBrain consumer (HTTP POST if GBRAIN_URL set; else defer)
 #
 # Env:
 #   GSTACK_HOME — override ~/.gstack
-#   GBRAIN_URL  — GBrain ingest endpoint base URL (for consumer registration)
 
 set -euo pipefail
 
@@ -34,7 +32,6 @@ GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 CONFIG_BIN="$SCRIPT_DIR/gstack-config"
 REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
-CONSUMERS_FILE="$GSTACK_HOME/consumers.json"
 
 REMOTE_URL=""
 while [ $# -gt 0 ]; do
@@ -280,68 +277,6 @@ fi
 echo "$REMOTE_URL" > "$REMOTE_FILE"
 chmod 600 "$REMOTE_FILE"
 
-# ---- register GBrain consumer ----
-mkdir -p "$GSTACK_HOME"
-CONSUMER_STATUS="pending"
-GBRAIN_URL_VAL="${GBRAIN_URL:-$("$CONFIG_BIN" get gbrain_url 2>/dev/null || echo "")}"
-GBRAIN_TOKEN_VAL="${GBRAIN_TOKEN:-$("$CONFIG_BIN" get gbrain_token 2>/dev/null || echo "")}"
-
-if [ -n "$GBRAIN_URL_VAL" ] && [ -n "$GBRAIN_TOKEN_VAL" ]; then
-  # Try the HTTP handoff.
-  HTTP_RESP=$(curl -sS -X POST "${GBRAIN_URL_VAL%/}/ingest-repo" \
-    -H "Authorization: Bearer $GBRAIN_TOKEN_VAL" \
-    -H "Content-Type: application/json" \
-    --data "{\"repo_url\":\"$REMOTE_URL\"}" \
-    -w "\n%{http_code}" 2>&1 || echo -e "\ncurl-error")
-  HTTP_CODE=$(echo "$HTTP_RESP" | tail -1)
-  if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "204" ]; then
-    CONSUMER_STATUS="ok"
-    echo "GBrain consumer registered: $GBRAIN_URL_VAL"
-  else
-    echo "GBrain ingest endpoint returned HTTP $HTTP_CODE; will retry on next skill run."
-  fi
-elif [ -z "$GBRAIN_URL_VAL" ]; then
-  echo "(GBRAIN_URL not configured; skipping consumer registration. Set it with:"
-  echo "   gstack-config set gbrain_url <url>"
-  echo "   gstack-config set gbrain_token <token>"
-  echo " then run: gstack-brain-consumer add gbrain --ingest-url <url> --token <token>)"
-fi
-
-# Write consumers.json — the canonical registry. Tokens are NOT stored here;
-# they stay in gstack-config (machine-local). This file IS synced so a new
-# machine knows which consumers exist and can prompt for tokens.
-python3 - "$CONSUMERS_FILE" "$GBRAIN_URL_VAL" "$CONSUMER_STATUS" <<'PYEOF'
-import sys, json, os
-path, url, status = sys.argv[1:4]
-try:
-    with open(path) as f:
-        data = json.load(f)
-except (FileNotFoundError, json.JSONDecodeError):
-    data = {"consumers": []}
-# Upsert GBrain entry.
-entry = {"name": "gbrain", "ingest_url": url, "status": status, "token_ref": "gbrain_token"}
-updated = False
-for i, c in enumerate(data.get("consumers", [])):
-    if c.get("name") == "gbrain":
-        data["consumers"][i] = entry
-        updated = True
-        break
-if not updated:
-    data.setdefault("consumers", []).append(entry)
-with open(path, "w") as f:
-    json.dump(data, f, indent=2)
-    f.write("\n")
-PYEOF
-
-# Stage and commit consumers.json in the same session.
-cd "$GSTACK_HOME"
-git add -f consumers.json 2>/dev/null || true
-if ! git diff --cached --quiet 2>/dev/null; then
-  git -c user.email="gstack@localhost" -c user.name="gstack-brain-init" \
-      commit -q -m "chore: register GBrain consumer"
-  git push -q origin HEAD 2>/dev/null || true
-fi
-
 # ---- done ----
 cat <<EOF
 
@@ -350,12 +285,14 @@ Repo:    $GSTACK_HOME (git)
 Remote:  $REMOTE_URL
 Remote URL also saved at: $REMOTE_FILE
 
-Sync happens automatically at the start and end of each skill (no daemon).
-Check status anytime with:
+Sync to GitHub happens automatically at the start and end of each skill
+(no daemon). Check status anytime with:
   gstack-brain-sync --status
 
-To activate sync, the next skill you run will ask you one question about
-privacy mode (sync everything / artifacts only / off).
+The next skill run will ask you one question about privacy mode (full /
+artifacts-only / off). After that, /setup-gbrain Step 7 (or the
+gstack-gbrain-source-wireup helper) registers this repo as a federated
+source on gbrain so its content is searchable via 'gbrain search'.
 
 New machine? On the other laptop, put a copy of:
   $REMOTE_FILE
diff --git a/bin/gstack-brain-restore b/bin/gstack-brain-restore
index 315b36f9..0da18139 100755
--- a/bin/gstack-brain-restore
+++ b/bin/gstack-brain-restore
@@ -19,7 +19,8 @@
 #   3. rsync-copy tracked files into ~/.gstack/ with skip-if-same-hash
 #   4. Move staging's .git into ~/.gstack/.git
 #   5. Register local git config merge drivers (they don't clone from remote)
-#   6. Rehydrate consumers.json endpoints; prompt for tokens
+#   6. Wire the cloned brain into gbrain via gstack-gbrain-source-wireup
+#      (best-effort; restore continues even if gbrain wireup fails)
 #
 # Env:
 #   GSTACK_HOME — override ~/.gstack
@@ -195,25 +196,6 @@ sys.exit(0)
 HOOK_EOF
 chmod +x "$HOOK"
 
-# ---- rehydrate consumers, prompt for tokens ----
-if [ -f "$GSTACK_HOME/consumers.json" ]; then
-  echo ""
-  echo "Consumer registry restored. Tokens are machine-local and NOT synced."
-  echo "Run these for each consumer to re-enter tokens:"
-  python3 - "$GSTACK_HOME/consumers.json" <<'PYEOF'
-import sys, json
-try:
-    with open(sys.argv[1]) as f:
-        data = json.load(f)
-except Exception:
-    sys.exit(0)
-for c in data.get("consumers", []):
-    name = c.get("name", "")
-    token_ref = c.get("token_ref", f"{name}_token")
-    print(f"  gstack-config set {token_ref} <your-token>")
-PYEOF
-fi
-
 # ---- write remote helper file if missing ----
 if [ ! -f "$REMOTE_FILE" ]; then
   echo "$REMOTE_URL" > "$REMOTE_FILE"
@@ -222,6 +204,12 @@ if [ ! -f "$REMOTE_FILE" ]; then
   echo "Wrote $REMOTE_FILE for future skill-run auto-detection."
 fi
 
+# ---- wire the cloned brain into gbrain (best-effort) ----
+WIREUP_BIN="$SCRIPT_DIR/gstack-gbrain-source-wireup"
+if [ -x "$WIREUP_BIN" ]; then
+  "$WIREUP_BIN" || >&2 echo "WARNING: gbrain wireup failed; run $WIREUP_BIN manually after fixing prereqs"
+fi
+
 cat <<EOF
 
 gstack-brain-restore complete.
diff --git a/bin/gstack-brain-uninstall b/bin/gstack-brain-uninstall
index e259f288..c8ce1119 100755
--- a/bin/gstack-brain-uninstall
+++ b/bin/gstack-brain-uninstall
@@ -120,6 +120,16 @@ rm -f "$GSTACK_HOME/.brain-last-pull" 2>/dev/null || true
 rm -f "$GSTACK_HOME/.brain-skip.txt" 2>/dev/null || true
 rm -f "$GSTACK_HOME/.brain-sync-status.json" 2>/dev/null || true
 rm -rf "$GSTACK_HOME/.brain-sync.lock.d" 2>/dev/null || true
+
+# ---- unregister gbrain federated source + remove worktree (best-effort) ----
+# The wireup helper handles: gbrain sources remove, git worktree remove,
+# launchd plist (future). All best-effort; uninstall continues on failure.
+WIREUP_BIN="$SCRIPT_DIR/gstack-gbrain-source-wireup"
+if [ -x "$WIREUP_BIN" ]; then
+  "$WIREUP_BIN" --uninstall 2>/dev/null || true
+fi
+
+# ---- legacy consumers.json (no longer written by gstack-brain-init since v1.17.0.0) ----
 rm -f "$GSTACK_HOME/consumers.json" 2>/dev/null || true
 
 # ---- clear config keys ----
diff --git a/bin/gstack-gbrain-source-wireup b/bin/gstack-gbrain-source-wireup
new file mode 100755
index 00000000..3b175482
--- /dev/null
+++ b/bin/gstack-gbrain-source-wireup
@@ -0,0 +1,357 @@
+#!/usr/bin/env bash
+# gstack-gbrain-source-wireup — register the gstack brain repo as a gbrain
+# federated source via `git worktree`, run an initial sync, hook into
+# subsequent skill-end syncs.
+#
+# Replaces the v1.12.2.0 dead `consumers.json + ingest_url + /ingest-repo`
+# wireup which depended on a gbrain HTTP endpoint that never shipped.
+#
+# Usage:
+#   gstack-gbrain-source-wireup [--strict] [--source-id <id>] [--no-pull]
+#                               [--database-url <url>]
+#   gstack-gbrain-source-wireup --uninstall [--source-id <id>]
+#                               [--database-url <url>]
+#   gstack-gbrain-source-wireup --probe
+#   gstack-gbrain-source-wireup --help
+#
+# Exit codes:
+#   0 — success, OR benign skip without --strict
+#   1 — hard failure (gbrain or git op errored on a real call)
+#   2 — missing prereqs (no gbrain >= 0.18.0, no .git or remote-file)
+#   3 — source-id derivation failed in --uninstall, no fallback worked
+#
+# Env:
+#   GSTACK_HOME — override ~/.gstack (test harness)
+#   GSTACK_BRAIN_WORKTREE — override worktree path (default ~/.gstack-brain-worktree)
+#   GSTACK_BRAIN_SOURCE_ID — id override; --source-id flag takes precedence
+#   GSTACK_BRAIN_NO_SYNC — skip the gbrain sync step (tests; helper still
+#                          ensures source registration)
+#
+# Defense against external rewrites of ~/.gbrain/config.json:
+# At helper startup we capture the database URL ONCE — from --database-url,
+# from GBRAIN_DATABASE_URL/DATABASE_URL env, or from ~/.gbrain/config.json —
+# and export it as GBRAIN_DATABASE_URL for every child `gbrain` invocation.
+# That env var overrides whatever's in config.json (per gbrain's loadConfig
+# at src/core/config.ts:53), so a process that flips config.json mid-sync
+# can't redirect us at a different brain mid-stream.
+#
+# Depends on: jq (transitive via gstack-gbrain-detect).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONFIG_BIN="$SCRIPT_DIR/gstack-config"
+
+GSTACK_HOME="${GSTACK_HOME:-$HOME/.gstack}"
+WORKTREE="${GSTACK_BRAIN_WORKTREE:-$HOME/.gstack-brain-worktree}"
+REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
+PLIST_PATH="$HOME/Library/LaunchAgents/com.gstack.brain-sync.plist"
+GBRAIN_CONFIG="$HOME/.gbrain/config.json"
+
+# ---- arg parse ----
+MODE="wireup"
+STRICT=0
+NO_PULL=0
+SOURCE_ID=""
+DATABASE_URL_ARG=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --uninstall)     MODE="uninstall"; shift ;;
+    --probe)         MODE="probe"; shift ;;
+    --strict)        STRICT=1; shift ;;
+    --no-pull)       NO_PULL=1; shift ;;
+    --source-id)     SOURCE_ID="$2"; shift 2 ;;
+    --database-url)  DATABASE_URL_ARG="$2"; shift 2 ;;
+    --help|-h)       sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)               echo "Unknown flag: $1" >&2; exit 1 ;;
+  esac
+done
+
+# ---- lock the database URL at startup ----
+# Precedence: --database-url flag > existing GBRAIN_DATABASE_URL/DATABASE_URL
+# env > read once from ~/.gbrain/config.json. Whichever wins gets exported as
+# GBRAIN_DATABASE_URL so every child `gbrain` invocation uses THAT brain even
+# if config.json is rewritten by another process during the wireup.
+_locked_url=""
+if [ -n "$DATABASE_URL_ARG" ]; then
+  _locked_url="$DATABASE_URL_ARG"
+elif [ -n "${GBRAIN_DATABASE_URL:-}" ]; then
+  _locked_url="$GBRAIN_DATABASE_URL"
+elif [ -n "${DATABASE_URL:-}" ]; then
+  _locked_url="$DATABASE_URL"
+elif [ -f "$GBRAIN_CONFIG" ]; then
+  # Python heredoc reads config.json. On JSON parse failure or any IO error,
+  # we WARN (not silently swallow) so the user knows the URL lock fell back
+  # to gbrain's own loadConfig (which would still read this same file).
+  _py_err=$(mktemp -t wireup-pyerr 2>/dev/null || mktemp /tmp/wireup-pyerr.XXXXXX)
+  _locked_url=$(GBRAIN_CONFIG_PATH="$GBRAIN_CONFIG" python3 -c '
+import json, os, sys
+try:
+    c = json.load(open(os.environ["GBRAIN_CONFIG_PATH"]))
+    print(c.get("database_url",""))
+except FileNotFoundError:
+    sys.exit(0)
+except Exception as e:
+    print(f"config.json parse error: {e}", file=sys.stderr)
+    sys.exit(1)
+' </dev/null 2>"$_py_err") || warn "could not read $GBRAIN_CONFIG ($(cat "$_py_err" 2>/dev/null)); URL not locked"
+  rm -f "$_py_err" 2>/dev/null
+fi
+if [ -n "$_locked_url" ]; then
+  export GBRAIN_DATABASE_URL="$_locked_url"
+fi
+
+prefix() { sed 's/^/gstack-gbrain-source-wireup: /' >&2; }
+warn()   { echo "$*" | prefix; }
+# die <message> [exit_code]: warn with just the message, exit with code (default 1).
+die()    { warn "$1"; exit "${2:-1}"; }
+
+# Refuse to rm anything outside $HOME/. Defends against GSTACK_BRAIN_WORKTREE=/
+# or empty-string overrides that would otherwise have line 169 / 161 nuke the
+# user's home or root.
+safe_rm_worktree() {
+  local target="$1"
+  case "$target" in
+    "" | "/" | "/Users" | "/Users/" | "$HOME" | "$HOME/" )
+      die "refusing to rm dangerous path: $target" 1 ;;
+  esac
+  case "$target" in
+    "$HOME"/*) rm -rf "$target" ;;
+    *) die "refusing to rm path outside \$HOME: $target" 1 ;;
+  esac
+}
+
+# ---- source-id derivation (D6 multi-fallback) ----
+derive_source_id() {
+  if [ -n "$SOURCE_ID" ]; then
+    echo "$SOURCE_ID"; return 0
+  fi
+  if [ -n "${GSTACK_BRAIN_SOURCE_ID:-}" ]; then
+    echo "$GSTACK_BRAIN_SOURCE_ID"; return 0
+  fi
+  local remote_url=""
+  remote_url=$(git -C "$GSTACK_HOME" remote get-url origin 2>/dev/null) || true
+  if [ -z "$remote_url" ] && [ -f "$REMOTE_FILE" ]; then
+    remote_url=$(head -1 "$REMOTE_FILE" 2>/dev/null | tr -d '[:space:]')
+  fi
+  [ -z "$remote_url" ] && return 3
+  basename "$remote_url" .git \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr -c 'a-z0-9-' '-' \
+    | sed 's/--*/-/g; s/^-//; s/-$//' \
+    | cut -c1-32
+}
+
+# ---- gbrain version gate ----
+gbrain_version_ok() {
+  if ! command -v gbrain >/dev/null 2>&1; then
+    return 1
+  fi
+  local v
+  v=$(gbrain --version 2>/dev/null | awk '{print $2}')
+  [ -z "$v" ] && return 1
+  # 0.18.0 minimum (gbrain sources shipped here). Put the floor first in stdin
+  # so equal or greater $v sorts to position 2 — head -1 == "0.18.0" iff $v >= floor.
+  [ "$(printf '0.18.0\n%s\n' "$v" | sort -V | head -1)" = "0.18.0" ]
+}
+
+# ---- worktree management ----
+# A worktree is always created `--detach`ed at $GSTACK_HOME's HEAD. Detached
+# because a branch (main) can only be checked out in ONE worktree, and the
+# parent at $GSTACK_HOME already has it. To advance, we re-checkout the
+# parent's current HEAD into the detached worktree.
+_worktree_add_detached() {
+  local sha
+  sha=$(git -C "$GSTACK_HOME" rev-parse HEAD 2>/dev/null) || return 1
+  git -C "$GSTACK_HOME" worktree prune 2>/dev/null || true
+  # Surface git errors via prefix so users see WHY the add failed (disk, perms, etc).
+  git -C "$GSTACK_HOME" worktree add --detach "$WORKTREE" "$sha" 2>&1 | prefix
+  return "${PIPESTATUS[0]}"
+}
+
+ensure_worktree() {
+  if [ ! -d "$GSTACK_HOME/.git" ]; then
+    return 2
+  fi
+  if [ -d "$WORKTREE/.git" ] || [ -f "$WORKTREE/.git" ]; then
+    # already exists; advance the detached HEAD to parent's current HEAD
+    if [ "$NO_PULL" = "0" ]; then
+      local sha
+      sha=$(git -C "$GSTACK_HOME" rev-parse HEAD 2>/dev/null) || return 1
+      # Surface checkout errors via prefix so users see WHY the advance failed
+      # (uncommitted changes in the detached worktree, ref ambiguity, etc).
+      ( cd "$WORKTREE" && git checkout --detach "$sha" 2>&1 | prefix; exit "${PIPESTATUS[0]}" ) || {
+        warn "worktree at $WORKTREE could not advance to $sha; resetting via remove + re-add"
+        git -C "$GSTACK_HOME" worktree remove --force "$WORKTREE" 2>/dev/null || safe_rm_worktree "$WORKTREE"
+        _worktree_add_detached || return 1
+      }
+    fi
+    return 0
+  fi
+  # Stray non-git dir? Remove first.
+  [ -e "$WORKTREE" ] && safe_rm_worktree "$WORKTREE"
+  _worktree_add_detached || return 1
+}
+
+# ---- gbrain sources operations ----
+# Returns 0 if source with id exists at expected path. 1 if exists but path differs. 2 if absent.
+# Hard-fails (exits non-zero via die) if jq is missing — without jq we cannot
+# distinguish "absent" from "missing-tool" and would falsely re-add an existing
+# source. jq is documented as a dependency of gstack-gbrain-detect (transitive)
+# but adversarial review flagged the silent-fall-through path; this probe makes
+# the failure mode loud.
+check_source_state() {
+  local id="$1"
+  if ! command -v jq >/dev/null 2>&1; then
+    die "jq required for source state detection. Install jq (brew install jq) and re-run." 1
+  fi
+  local existing_path
+  existing_path=$(gbrain sources list --json 2>/dev/null \
+    | jq -r --arg id "$id" '.sources[] | select(.id==$id) | .local_path' 2>/dev/null \
+    | tr -d '[:space:]') || existing_path=""
+  if [ -z "$existing_path" ]; then
+    return 2
+  fi
+  if [ "$existing_path" = "$WORKTREE" ]; then
+    return 0
+  fi
+  return 1
+}
+
+# ---- modes ----
+do_probe() {
+  local id worktree_status="absent" gbrain_status="missing" source_status="absent"
+  id=$(derive_source_id 2>/dev/null) || id="(unknown)"
+  # Use explicit if-block so [ -d ] || [ -f ] doesn't get short-circuited by &&
+  # precedence (the `||` and `&&` chain has trap behavior in bash test syntax).
+  if [ -d "$WORKTREE/.git" ] || [ -f "$WORKTREE/.git" ]; then
+    worktree_status="present"
+  fi
+  if gbrain_version_ok; then
+    gbrain_status="ok ($(gbrain --version 2>/dev/null | awk '{print $2}'))"
+    # Capture check_source_state's return code explicitly. Relying on $? after
+    # an `if`-elif chain is fragile under set -e and undefined under some shells.
+    set +e
+    check_source_state "$id"
+    local css_rc=$?
+    set -e
+    case "$css_rc" in
+      0) source_status="registered ($WORKTREE)" ;;
+      1) source_status="registered (different path)" ;;
+    esac
+  fi
+  echo "source_id=$id"
+  echo "worktree=$WORKTREE"
+  echo "worktree_status=$worktree_status"
+  echo "gbrain=$gbrain_status"
+  echo "source_status=$source_status"
+}
+
+do_wireup() {
+  local id
+  id=$(derive_source_id) || die "cannot derive source id (no .git, no remote-file, no --source-id)" 2
+
+  if ! gbrain_version_ok; then
+    if [ "$STRICT" = "1" ]; then
+      die "gbrain not installed or < 0.18.0; install/upgrade gbrain and re-run" 2
+    fi
+    warn "gbrain not installed or < 0.18.0; skipping wireup (benign skip)"
+    exit 0
+  fi
+
+  # Capture ensure_worktree's return code explicitly. `$?` after `||` reflects
+  # the LAST command in the function under set -e, which is unreliable when the
+  # function has multiple internal exit paths.
+  set +e
+  ensure_worktree
+  ew_rc=$?
+  set -e
+  case "$ew_rc" in
+    0) : ;;  # success
+    2)
+      [ "$STRICT" = "1" ] && die "no $GSTACK_HOME/.git; run /setup-gbrain Step 7 (gstack-brain-init) first" 2
+      warn "no $GSTACK_HOME/.git; skipping (benign skip)"
+      exit 0
+      ;;
+    *) die "git worktree creation failed at $WORKTREE" 1 ;;
+  esac
+
+  # Source registration: probe state, then act.
+  set +e
+  check_source_state "$id"
+  local sstate=$?
+  set -e
+  case "$sstate" in
+    0) : ;;  # already correctly registered
+    1)
+      # Multi-Mac case: if the existing path also looks like another machine's
+      # brain-worktree (same basename, different parent), don't ping-pong the
+      # registration. Just sync from our local worktree — gbrain stores pages
+      # by content, not by local_path. The metadata is informational only.
+      local existing_path
+      existing_path=$(gbrain sources list --json 2>/dev/null \
+        | jq -r --arg id "$id" '.sources[] | select(.id==$id) | .local_path' 2>/dev/null \
+        | tr -d '[:space:]') || existing_path=""
+      if [ "$(basename "$existing_path")" = "$(basename "$WORKTREE")" ] \
+         && [ "$existing_path" != "$WORKTREE" ]; then
+        warn "source $id is registered at $existing_path (likely another machine's local copy of the same brain repo). Skipping re-registration; will sync from local worktree."
+      else
+        warn "source $id registered with different path; recreating (gbrain has no 'sources update')"
+        gbrain sources remove "$id" --yes 2>&1 | prefix || die "gbrain sources remove failed" 1
+        gbrain sources add "$id" --path "$WORKTREE" --federated 2>&1 | prefix \
+          || die "gbrain sources add failed" 1
+      fi
+      ;;
+    2)
+      gbrain sources add "$id" --path "$WORKTREE" --federated 2>&1 | prefix \
+        || die "gbrain sources add failed" 1
+      ;;
+  esac
+
+  if [ "${GSTACK_BRAIN_NO_SYNC:-0}" = "1" ]; then
+    echo "source_id=$id"
+    echo "worktree=$WORKTREE"
+    echo "pages_synced=skipped"
+    exit 0
+  fi
+
+  local sync_out sync_redacted
+  sync_out=$(gbrain sync --repo "$WORKTREE" 2>&1) || {
+    # Redact any postgres:// URLs from the error message in case gbrain logged
+    # a connection error containing the full DSN with password. The user sees
+    # "***REDACTED***" instead of credentials in their stderr or any log.
+    sync_redacted=$(echo "$sync_out" | tail -10 | sed -E 's#postgres(ql)?://[^[:space:]]+#postgres://***REDACTED***#g')
+    die "gbrain sync failed (last 10 lines, secrets redacted): $sync_redacted" 1
+  }
+  echo "$sync_out" | tail -3 | prefix
+
+  echo "source_id=$id"
+  echo "worktree=$WORKTREE"
+  echo "pages_synced=$(echo "$sync_out" | grep -oE '[0-9]+ pages? imported' | head -1 || echo 'incremental')"
+}
+
+do_uninstall() {
+  local id
+  id=$(derive_source_id) || die "cannot derive source id; pass --source-id <id> explicitly" 3
+
+  if command -v gbrain >/dev/null 2>&1; then
+    gbrain sources remove "$id" --yes 2>&1 | prefix || warn "gbrain sources remove failed (continuing)"
+  fi
+
+  if [ -d "$WORKTREE/.git" ] || [ -f "$WORKTREE/.git" ]; then
+    git -C "$GSTACK_HOME" worktree remove --force "$WORKTREE" 2>/dev/null \
+      || safe_rm_worktree "$WORKTREE"
+  fi
+
+  # Cron-stub: future launchd plist (not created today; safety net for D9 future).
+  rm -f "$PLIST_PATH" 2>/dev/null || true
+
+  echo "uninstalled source=$id worktree=$WORKTREE"
+}
+
+case "$MODE" in
+  probe)     do_probe ;;
+  wireup)    do_wireup ;;
+  uninstall) do_uninstall ;;
+esac
diff --git a/browse/src/server.ts b/browse/src/server.ts
index fa593520..02060812 100644
--- a/browse/src/server.ts
+++ b/browse/src/server.ts
@@ -116,13 +116,31 @@ const TUNNEL_PATHS = new Set<string>([
  * extension-inspector state. This allowlist maps to the eng-review decision
  * logged in the CEO plan for sec-wave v1.6.0.0.
  */
-const TUNNEL_COMMANDS = new Set<string>([
+export const TUNNEL_COMMANDS = new Set<string>([
+  // Original 17
   'goto', 'click', 'text', 'screenshot',
   'html', 'links', 'forms', 'accessibility',
   'attrs', 'media', 'data',
   'scroll', 'press', 'type', 'select', 'wait', 'eval',
+  // Tab + navigation primitives operator docs and CLI hints already promised
+  'newtab', 'tabs', 'back', 'forward', 'reload',
+  // Read/inspect/write operators paired agents need to be useful
+  'snapshot', 'fill', 'url', 'closetab',
 ]);
 
+/**
+ * Pure gate: returns true iff the command is reachable over the tunnel surface.
+ * Extracted from the inline /command handler so the gate logic is unit-testable
+ * without standing up an HTTP listener. Behavior is identical to the inline
+ * check; the function canonicalizes the command (so aliases hit the same set)
+ * and returns false for null/undefined input.
+ */
+export function canDispatchOverTunnel(command: string | undefined | null): boolean {
+  if (typeof command !== 'string' || command.length === 0) return false;
+  const cmd = canonicalizeCommand(command);
+  return TUNNEL_COMMANDS.has(cmd);
+}
+
 /**
  * Read ngrok authtoken from env var, ~/.gstack/ngrok.env, or ngrok's native
  * config files.  Returns null if nothing found.  Shared between the
@@ -1782,8 +1800,7 @@ async function start() {
         // Paired remote agents drive the browser but cannot configure the
         // daemon, launch new browsers, import cookies, or rotate tokens.
         if (surface === 'tunnel') {
-          const cmd = canonicalizeCommand(body?.command);
-          if (!cmd || !TUNNEL_COMMANDS.has(cmd)) {
+          if (!canDispatchOverTunnel(body?.command)) {
             logTunnelDenial(req, url, `disallowed_command:${body?.command}`);
             return new Response(JSON.stringify({
               error: `Command '${body?.command}' is not allowed over the tunnel surface`,
@@ -2070,6 +2087,29 @@ async function start() {
         tunnelListener = null;
       }
     }
+  } else if (process.env.BROWSE_TUNNEL_LOCAL_ONLY === '1') {
+    // Test-only: bind the dual-listener tunnel surface on 127.0.0.1 with NO
+    // ngrok forwarding. Lets paid evals exercise the surface==='tunnel' gate
+    // without an ngrok authtoken or live network. Production tunneling still
+    // requires BROWSE_TUNNEL=1 + a valid authtoken above.
+    try {
+      const boundTunnel = Bun.serve({
+        port: 0,
+        hostname: '127.0.0.1',
+        fetch: makeFetchHandler('tunnel'),
+      });
+      tunnelServer = boundTunnel;
+      tunnelActive = true;
+      const tunnelPort = boundTunnel.port;
+      console.log(`[browse] Tunnel listener bound (local-only test mode) on 127.0.0.1:${tunnelPort}`);
+      const stateContent = JSON.parse(fs.readFileSync(config.stateFile, 'utf-8'));
+      stateContent.tunnelLocalPort = tunnelPort;
+      const tmpState = config.stateFile + '.tmp';
+      fs.writeFileSync(tmpState, JSON.stringify(stateContent, null, 2), { mode: 0o600 });
+      fs.renameSync(tmpState, config.stateFile);
+    } catch (err: any) {
+      console.error(`[browse] BROWSE_TUNNEL_LOCAL_ONLY=1 listener bind failed: ${err.message}`);
+    }
   }
 }
 
diff --git a/browse/test/dual-listener.test.ts b/browse/test/dual-listener.test.ts
index c14966bb..47ef0b25 100644
--- a/browse/test/dual-listener.test.ts
+++ b/browse/test/dual-listener.test.ts
@@ -70,17 +70,37 @@ describe('Tunnel path allowlist', () => {
 });
 
 describe('Tunnel command allowlist', () => {
-  test('TUNNEL_COMMANDS is a closed set of browser-driving commands only', () => {
+  // The full closed set of commands reachable over the tunnel surface. Adding
+  // or removing a command here means changing the literal in server.ts AND
+  // updating this list — that double-edit is the point. A single-source
+  // "include the items in the source" assertion would silently widen the
+  // surface during a refactor that adds a command to server.ts without test
+  // review. The exact-set match catches it.
+  const EXPECTED_TUNNEL_COMMANDS = new Set([
+    // Original 17
+    'goto', 'click', 'text', 'screenshot',
+    'html', 'links', 'forms', 'accessibility',
+    'attrs', 'media', 'data',
+    'scroll', 'press', 'type', 'select', 'wait', 'eval',
+    // Tab + navigation primitives operator docs and CLI hints already promised
+    'newtab', 'tabs', 'back', 'forward', 'reload',
+    // Read/inspect/write operators paired agents need to be useful
+    'snapshot', 'fill', 'url', 'closetab',
+  ]);
+
+  test('TUNNEL_COMMANDS literal matches the closed allowlist exactly (catches additions/removals without test update)', () => {
     const cmds = extractSetContents(SERVER_SRC, 'TUNNEL_COMMANDS');
-    // Must include the core browser-driving commands
-    const required = [
-      'goto', 'click', 'text', 'screenshot', 'html', 'links',
-      'forms', 'accessibility', 'attrs', 'media', 'data',
-      'scroll', 'press', 'type', 'select', 'wait', 'eval',
-    ];
-    for (const c of required) {
+    // Both directions: anything in the source must be expected, and anything
+    // expected must be in the source. The intersection-only style of the old
+    // must-include / must-exclude tests let new commands sneak into the source
+    // without a corresponding test update.
+    for (const c of cmds) {
+      expect(EXPECTED_TUNNEL_COMMANDS.has(c)).toBe(true);
+    }
+    for (const c of EXPECTED_TUNNEL_COMMANDS) {
       expect(cmds.has(c)).toBe(true);
     }
+    expect(cmds.size).toBe(EXPECTED_TUNNEL_COMMANDS.size);
   });
 
   test('TUNNEL_COMMANDS does NOT include daemon-configuration or bootstrap commands', () => {
@@ -89,12 +109,21 @@ describe('Tunnel command allowlist', () => {
       'launch', 'launch-browser', 'connect', 'disconnect',
       'restart', 'stop', 'tunnel-start', 'tunnel-stop',
       'token-mint', 'token-revoke', 'cookie-picker', 'cookie-import',
-      'inspector-pick',
+      'inspector-pick', 'pair', 'unpair', 'cookies', 'setup',
     ];
     for (const c of forbidden) {
       expect(cmds.has(c)).toBe(false);
     }
   });
+
+  test('newtab ownership exemption preserved (catches refactors that re-introduce the catch-22)', () => {
+    // The /command handler must skip the per-tab ownership check when the
+    // command is `newtab`, otherwise paired agents have no way to create their
+    // own tab — every other write command requires an owned tab, and you can't
+    // own a tab you haven't created. The string `command !== 'newtab'` is the
+    // contract that breaks the catch-22.
+    expect(SERVER_SRC).toMatch(/command\s*!==\s*['"]newtab['"]/);
+  });
 });
 
 describe('Request handler factory', () => {
@@ -176,14 +205,14 @@ describe('GET /connect alive probe', () => {
 });
 
 describe('/command tunnel command allowlist', () => {
-  test('/command handler checks TUNNEL_COMMANDS when surface is tunnel', () => {
+  test('/command handler delegates to canDispatchOverTunnel when surface is tunnel', () => {
     const commandBlock = sliceBetween(
       SERVER_SRC,
       "url.pathname === '/command' && req.method === 'POST'",
       'return handleCommand(body, tokenInfo)'
     );
     expect(commandBlock).toContain("surface === 'tunnel'");
-    expect(commandBlock).toContain('TUNNEL_COMMANDS.has');
+    expect(commandBlock).toContain('canDispatchOverTunnel(body?.command)');
     expect(commandBlock).toContain('disallowed_command');
     expect(commandBlock).toContain('is not allowed over the tunnel surface');
     expect(commandBlock).toContain('status: 403');
diff --git a/browse/test/pair-agent-tunnel-eval.test.ts b/browse/test/pair-agent-tunnel-eval.test.ts
new file mode 100644
index 00000000..ffb43219
--- /dev/null
+++ b/browse/test/pair-agent-tunnel-eval.test.ts
@@ -0,0 +1,215 @@
+/**
+ * Tunnel-surface behavioral eval for the pair-agent flow.
+ *
+ * Spawns the daemon under `BROWSE_HEADLESS_SKIP=1 BROWSE_TUNNEL_LOCAL_ONLY=1`
+ * so BOTH listeners come up: the local listener on `port` and the tunnel
+ * listener on `tunnelLocalPort`. No ngrok, no live network — the surface tag
+ * (`local` vs `tunnel`) is set by which listener received the request, which
+ * is testable as long as both bind locally.
+ *
+ * This file is the only place that exercises the tunnel-surface gate
+ * end-to-end. The source-level guards in `dual-listener.test.ts` catch
+ * literal/exemption regressions, the unit test in `tunnel-gate-unit.test.ts`
+ * catches gate-logic regressions, and this file catches routing-or-listener
+ * regressions (e.g. someone accidentally swaps `'local'` and `'tunnel'` at
+ * the makeFetchHandler call site).
+ *
+ * The browser dispatch path under BROWSE_HEADLESS_SKIP=1 surfaces an error
+ * because there is no Playwright context, so the assertion target is
+ * specifically that the GATE was passed (i.e. the response is NOT a 403 with
+ * `disallowed_command:<x>`), not that the dispatch succeeded.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const ROOT = path.resolve(import.meta.dir, '../..');
+const SERVER_ENTRY = path.join(ROOT, 'browse/src/server.ts');
+
+interface DaemonHandle {
+  proc: ReturnType<typeof Bun.spawn>;
+  localPort: number;
+  tunnelPort: number;
+  rootToken: string;
+  scopedToken: string;
+  stateFile: string;
+  tempDir: string;
+  localUrl: string;
+  tunnelUrl: string;
+  attemptsLogPath: string;
+}
+
+async function waitForReady(baseUrl: string, timeoutMs = 20_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const resp = await fetch(`${baseUrl}/health`, {
+        signal: AbortSignal.timeout(1000),
+      });
+      if (resp.ok) return;
+    } catch {
+      // not ready yet
+    }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  throw new Error(`Daemon did not become ready within ${timeoutMs}ms at ${baseUrl}`);
+}
+
+async function waitForTunnelPort(stateFile: string, timeoutMs = 20_000): Promise<number> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+      if (typeof state.tunnelLocalPort === 'number') return state.tunnelLocalPort;
+    } catch {
+      // state file not written yet
+    }
+    await new Promise(r => setTimeout(r, 200));
+  }
+  throw new Error(`Tunnel local port did not appear in ${stateFile} within ${timeoutMs}ms`);
+}
+
+async function spawnDaemonWithTunnel(): Promise<DaemonHandle> {
+  // Isolate this test's analytics + denial log directory so we can assert on a
+  // fresh attempts.jsonl without colliding with the user's real ~/.gstack.
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pair-agent-tunnel-eval-'));
+  const stateFile = path.join(tempDir, 'browse.json');
+  const fakeHome = path.join(tempDir, 'home');
+  fs.mkdirSync(fakeHome, { recursive: true });
+  const localPort = 30000 + Math.floor(Math.random() * 30000);
+  const attemptsLogPath = path.join(fakeHome, '.gstack', 'security', 'attempts.jsonl');
+
+  const proc = Bun.spawn(['bun', 'run', SERVER_ENTRY], {
+    cwd: ROOT,
+    env: {
+      ...process.env,
+      HOME: fakeHome,
+      BROWSE_HEADLESS_SKIP: '1',
+      BROWSE_TUNNEL_LOCAL_ONLY: '1',
+      BROWSE_PORT: String(localPort),
+      BROWSE_STATE_FILE: stateFile,
+      BROWSE_PARENT_PID: '0',
+      BROWSE_IDLE_TIMEOUT: '600000',
+    },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  const localUrl = `http://127.0.0.1:${localPort}`;
+  await waitForReady(localUrl);
+  const tunnelPort = await waitForTunnelPort(stateFile);
+  const tunnelUrl = `http://127.0.0.1:${tunnelPort}`;
+
+  // Read the root token, then exchange it for a scoped token via /pair → /connect.
+  const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+  const rootToken = state.token;
+
+  const pairResp = await fetch(`${localUrl}/pair`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${rootToken}` },
+    body: JSON.stringify({ clientId: 'tunnel-eval' }),
+  });
+  if (!pairResp.ok) throw new Error(`/pair failed: ${pairResp.status}`);
+  const { setup_key } = await pairResp.json() as any;
+
+  const connectResp = await fetch(`${localUrl}/connect`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ setup_key }),
+  });
+  if (!connectResp.ok) throw new Error(`/connect failed: ${connectResp.status}`);
+  const { token: scopedToken } = await connectResp.json() as any;
+
+  return { proc, localPort, tunnelPort, rootToken, scopedToken, stateFile, tempDir, localUrl, tunnelUrl, attemptsLogPath };
+}
+
+function killDaemon(handle: DaemonHandle): void {
+  try { handle.proc.kill('SIGKILL'); } catch {}
+  try { fs.rmSync(handle.tempDir, { recursive: true, force: true }); } catch {}
+}
+
+async function postCommand(baseUrl: string, token: string, body: any): Promise<{ status: number; bodyText: string }> {
+  const resp = await fetch(`${baseUrl}/command`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  });
+  return { status: resp.status, bodyText: await resp.text() };
+}
+
+describe('pair-agent over tunnel surface — gate fires on the right surface only', () => {
+  let daemon: DaemonHandle;
+
+  beforeAll(async () => {
+    daemon = await spawnDaemonWithTunnel();
+  }, 30_000);
+
+  afterAll(() => {
+    if (daemon) killDaemon(daemon);
+  });
+
+  test('newtab on tunnel surface passes the allowlist gate (not 403 disallowed_command)', async () => {
+    const { status, bodyText } = await postCommand(daemon.tunnelUrl, daemon.scopedToken, { command: 'newtab' });
+    // Browser dispatch under BROWSE_HEADLESS_SKIP=1 will fail differently
+    // (no Playwright context), but the gate must NOT 403 with
+    // disallowed_command.
+    if (status === 403) {
+      expect(bodyText).not.toContain('disallowed_command:newtab');
+      expect(bodyText).not.toContain('is not allowed over the tunnel surface');
+    }
+  });
+
+  test('pair on tunnel surface 403s with disallowed_command and writes a denial-log entry', async () => {
+    // Snapshot attempts.jsonl size before the call so we can detect the new entry.
+    let beforeBytes = 0;
+    try { beforeBytes = fs.statSync(daemon.attemptsLogPath).size; } catch {}
+
+    const { status, bodyText } = await postCommand(daemon.tunnelUrl, daemon.scopedToken, { command: 'pair' });
+    expect(status).toBe(403);
+    expect(bodyText).toContain('is not allowed over the tunnel surface');
+
+    // Wait briefly for the denial-log writer (it's synchronous fs.appendFile in
+    // tunnel-denial-log.ts but the OS may need a tick to flush).
+    await new Promise(r => setTimeout(r, 250));
+    expect(fs.existsSync(daemon.attemptsLogPath)).toBe(true);
+    const after = fs.readFileSync(daemon.attemptsLogPath, 'utf-8');
+    const newSection = after.slice(beforeBytes);
+    expect(newSection).toContain('disallowed_command:pair');
+  });
+
+  test('pair on local surface does NOT trigger the tunnel allowlist gate', async () => {
+    // The same scoped token over the LOCAL listener must not see the
+    // disallowed_command path — the tunnel gate is surface-scoped.
+    const { status, bodyText } = await postCommand(daemon.localUrl, daemon.scopedToken, { command: 'pair' });
+    // Whatever happens (404 unknown command, 403 from a token-scope check, or
+    // 200 if the local handler accepts it) the response must NOT come from the
+    // tunnel allowlist gate.
+    expect(bodyText).not.toContain('disallowed_command:pair');
+    expect(bodyText).not.toContain('is not allowed over the tunnel surface');
+    expect([200, 400, 403, 404, 500]).toContain(status);
+  });
+
+  test('catch-22 regression: newtab + goto on the just-created tab passes ownership check', async () => {
+    // Without the `command !== 'newtab'` exemption at server.ts:613, scoped
+    // agents can't open a tab (newtab fails ownership) and can't goto an
+    // existing tab (also fails ownership). This proves the exemption holds:
+    // newtab succeeds the gate AND the ownership check, then the agent can
+    // hand off the tabId to a follow-up command without hitting the
+    // "Tab not owned by your agent" error.
+    const newtabResp = await postCommand(daemon.tunnelUrl, daemon.scopedToken, { command: 'newtab' });
+    if (newtabResp.status === 403) {
+      expect(newtabResp.bodyText).not.toContain('disallowed_command');
+      expect(newtabResp.bodyText).not.toContain('Tab not owned by your agent');
+    }
+
+    // Even if the headless-skip dispatch fails before returning a tabId, a
+    // follow-up `goto` over the tunnel surface must not 403 with
+    // `disallowed_command:goto`. We are NOT asserting that the goto
+    // succeeds — only that the allowlist + ownership exemption don't reject
+    // it as a class.
+    const gotoResp = await postCommand(daemon.tunnelUrl, daemon.scopedToken, { command: 'goto', args: ['http://127.0.0.1:1/'] });
+    expect(gotoResp.bodyText).not.toContain('disallowed_command:goto');
+    expect(gotoResp.bodyText).not.toContain('is not allowed over the tunnel surface');
+  });
+});
diff --git a/browse/test/tunnel-gate-unit.test.ts b/browse/test/tunnel-gate-unit.test.ts
new file mode 100644
index 00000000..f6d61c13
--- /dev/null
+++ b/browse/test/tunnel-gate-unit.test.ts
@@ -0,0 +1,97 @@
+/**
+ * Unit-test the pure tunnel-gate function extracted from the /command handler.
+ *
+ * The gate decides whether a paired remote agent's request to `/command` over
+ * the tunnel surface is allowed (returns true) or 403'd (returns false). Pure,
+ * synchronous, no HTTP — testable without standing up a Bun.serve listener.
+ *
+ * The behavioral coverage of the gate firing on the right surface (and only
+ * the right surface) lives in `pair-agent-tunnel-eval.test.ts` (paid eval,
+ * gate-tier).
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { canDispatchOverTunnel, TUNNEL_COMMANDS } from '../src/server';
+
+describe('canDispatchOverTunnel — closed allowlist', () => {
+  test('every command in TUNNEL_COMMANDS dispatches over tunnel', () => {
+    for (const cmd of TUNNEL_COMMANDS) {
+      expect(canDispatchOverTunnel(cmd)).toBe(true);
+    }
+  });
+
+  test('TUNNEL_COMMANDS contains the 26-command closed set', () => {
+    // Mirror the source-level guard in dual-listener.test.ts. If this ever
+    // disagrees with the literal in server.ts, one of them is wrong.
+    const expected = new Set([
+      'goto', 'click', 'text', 'screenshot',
+      'html', 'links', 'forms', 'accessibility',
+      'attrs', 'media', 'data',
+      'scroll', 'press', 'type', 'select', 'wait', 'eval',
+      'newtab', 'tabs', 'back', 'forward', 'reload',
+      'snapshot', 'fill', 'url', 'closetab',
+    ]);
+    expect(TUNNEL_COMMANDS.size).toBe(expected.size);
+    for (const c of expected) expect(TUNNEL_COMMANDS.has(c)).toBe(true);
+    for (const c of TUNNEL_COMMANDS) expect(expected.has(c)).toBe(true);
+  });
+});
+
+describe('canDispatchOverTunnel — daemon-config + bootstrap commands rejected', () => {
+  const blocked = [
+    'pair', 'unpair', 'cookies', 'setup',
+    'launch', 'launch-browser', 'connect', 'disconnect',
+    'restart', 'stop', 'tunnel-start', 'tunnel-stop',
+    'token-mint', 'token-revoke', 'cookie-picker', 'cookie-import',
+    'inspector-pick', 'extension-inspect',
+    'invalid-command-xyz', 'totally-made-up',
+  ];
+  for (const cmd of blocked) {
+    test(`rejects '${cmd}'`, () => {
+      expect(canDispatchOverTunnel(cmd)).toBe(false);
+    });
+  }
+});
+
+describe('canDispatchOverTunnel — null/undefined/empty input', () => {
+  test('returns false for empty string', () => {
+    expect(canDispatchOverTunnel('')).toBe(false);
+  });
+
+  test('returns false for undefined', () => {
+    expect(canDispatchOverTunnel(undefined)).toBe(false);
+  });
+
+  test('returns false for null', () => {
+    expect(canDispatchOverTunnel(null)).toBe(false);
+  });
+
+  test('returns false for non-string input (defensive)', () => {
+    // The body parser may hand the gate a number or object if a malicious
+    // client sends `{"command": 42}`. The pure gate must treat anything
+    // non-string as not-allowed rather than throw.
+    expect(canDispatchOverTunnel(42 as unknown as string)).toBe(false);
+    expect(canDispatchOverTunnel({} as unknown as string)).toBe(false);
+  });
+});
+
+describe('canDispatchOverTunnel — alias canonicalization', () => {
+  // canonicalizeCommand resolves aliases (e.g. 'set-content' → 'load-html').
+  // Any aliased form of an allowlisted canonical command should also pass the
+  // gate; aliases that resolve to a non-allowlisted canonical command should
+  // not. We don't hardcode alias names here — we read from the source registry
+  // by importing what we need from commands.ts.
+  test('aliases that resolve to allowlisted commands pass the gate', () => {
+    // 'set-content' canonicalizes to 'load-html'. 'load-html' is NOT in
+    // TUNNEL_COMMANDS, so 'set-content' must also be rejected. This guards
+    // against a future alias that accidentally maps a tunnel-allowed name to
+    // a non-tunnel-allowed canonical (e.g. 'goto' → 'navigate' would break).
+    expect(canDispatchOverTunnel('set-content')).toBe(false);
+  });
+
+  test('canonical commands pass directly without alias lookup', () => {
+    expect(canDispatchOverTunnel('goto')).toBe(true);
+    expect(canDispatchOverTunnel('newtab')).toBe(true);
+    expect(canDispatchOverTunnel('closetab')).toBe(true);
+  });
+});
diff --git a/docs/REMOTE_BROWSER_ACCESS.md b/docs/REMOTE_BROWSER_ACCESS.md
index e7386ffa..88dc30bb 100644
--- a/docs/REMOTE_BROWSER_ACCESS.md
+++ b/docs/REMOTE_BROWSER_ACCESS.md
@@ -32,7 +32,7 @@ GStack Browser Server                 Any AI agent
 
 The daemon binds two HTTP sockets. The **local listener** serves the full command surface to 127.0.0.1 only and is never forwarded. The **tunnel listener** is bound lazily on `/tunnel/start` (and torn down on `/tunnel/stop`) with a locked path allowlist. ngrok forwards only the tunnel port.
 
-A caller who stumbles onto your ngrok URL cannot reach `/health`, `/cookie-picker`, `/inspector/*`, or `/welcome` — those paths don't exist on that TCP socket. Root tokens sent over the tunnel get 403. The tunnel listener accepts only `/connect`, `/command` (with a scoped token + the 17-command browser-driving allowlist), and `/sidebar-chat`.
+A caller who stumbles onto your ngrok URL cannot reach `/health`, `/cookie-picker`, `/inspector/*`, or `/welcome` — those paths don't exist on that TCP socket. Root tokens sent over the tunnel get 403. The tunnel listener accepts only `/connect`, `/command` (with a scoped token + the 26-command browser-driving allowlist), and `/sidebar-chat`.
 
 See [ARCHITECTURE.md](../ARCHITECTURE.md#dual-listener-tunnel-architecture-v1600) for the full endpoint table.
 
@@ -165,7 +165,7 @@ Each agent owns the tabs it creates. Rules:
 ## Security Model
 
 - **Physical port separation.** Local listener and tunnel listener are separate TCP sockets. ngrok only forwards the tunnel port. Tunnel callers cannot reach bootstrap endpoints at all (404, wrong port).
-- **Tunnel command allowlist.** `/command` over the tunnel only accepts 17 browser-driving commands (goto, click, fill, snapshot, text, etc.). Server-management commands (tunnel, pair, token, useragent, eval, js) are denied on the tunnel.
+- **Tunnel command allowlist.** `/command` over the tunnel only accepts 26 browser-driving commands (goto, click, fill, snapshot, text, newtab, tabs, back, forward, reload, closetab, etc.). Server-management commands (tunnel, pair, token, useragent, js) are denied on the tunnel.
 - **Root token is tunnel-blocked.** A request bearing the root token over the tunnel listener returns 403 with a pairing hint. Only scoped session tokens work over the tunnel.
 - **Setup keys** expire in 5 minutes and can only be used once.
 - **Session tokens** expire in 24 hours (configurable).
diff --git a/docs/gbrain-sync.md b/docs/gbrain-sync.md
index 02e9dd4c..e5f1d700 100644
--- a/docs/gbrain-sync.md
+++ b/docs/gbrain-sync.md
@@ -43,9 +43,13 @@ The command:
 3. Pushes an initial commit with just the config.
 4. Writes `~/.gstack-brain-remote.txt` (URL-only, no secrets —
    safe to copy to another machine).
-5. Registers GBrain as a reader if `GBRAIN_URL` + `GBRAIN_TOKEN` are
-   configured. Otherwise you can add readers later with
-   `gstack-brain-reader add <name> --ingest-url <url> --token <token>`.
+5. Wires the gstack-brain repo into your local gbrain as a federated
+   source (via `gbrain sources add` + `git worktree`) so `gbrain search`
+   can index your synced learnings, plans, and designs. Implementation
+   lives in `bin/gstack-gbrain-source-wireup`. The old
+   `gstack-brain-reader add --ingest-url ...` HTTP path was removed in
+   v1.15.1.0 — it depended on a `/ingest-repo` endpoint gbrain never
+   shipped.
 
 After init, the **next skill you run** will ask you ONE question about
 privacy mode:
diff --git a/gstack-upgrade/migrations/v1.17.0.0.sh b/gstack-upgrade/migrations/v1.17.0.0.sh
new file mode 100755
index 00000000..5b8f1dd9
--- /dev/null
+++ b/gstack-upgrade/migrations/v1.17.0.0.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Migration: v1.17.0.0 — Wire existing brain-sync repos as gbrain federated sources
+#
+# Pre-1.17.0.0 /setup-gbrain wrote ~/.gstack/consumers.json with a placeholder
+# `status: "pending"` and an empty `ingest_url`, expecting a gbrain HTTP
+# /ingest-repo endpoint that never shipped. This migration runs the real
+# wireup (gbrain sources add + worktree + initial sync) for users who
+# already opted into brain-sync but never got the gbrain side connected.
+#
+# Idempotent: safe to re-run. Skips when:
+#   - User never opted into brain-sync (gbrain_sync_mode = off or unset)
+#   - No ~/.gstack/.git (brain-init never ran)
+#   - The wireup helper is missing on disk (broken install — defensive)
+#
+# Failure mode: invokes the helper WITHOUT --strict, so a missing/old gbrain
+# CLI is a benign skip rather than blocking the rest of /gstack-upgrade.
+set -euo pipefail
+
+if [ -z "${HOME:-}" ]; then
+  echo "  [v1.17.0.0] HOME is unset or empty — skipping migration." >&2
+  exit 0
+fi
+
+SKILLS_DIR="${HOME}/.claude/skills"
+BIN_DIR="${SKILLS_DIR}/gstack/bin"
+CONFIG_BIN="${BIN_DIR}/gstack-config"
+WIREUP_BIN="${BIN_DIR}/gstack-gbrain-source-wireup"
+
+# Skip if user never opted into brain-sync.
+SYNC_MODE=""
+if [ -x "$CONFIG_BIN" ]; then
+  # Trim whitespace defensively: gstack-config can emit trailing newlines,
+  # which would mis-classify "off\n" as a non-empty non-off mode.
+  SYNC_MODE=$("$CONFIG_BIN" get gbrain_sync_mode 2>/dev/null | tr -d '[:space:]' || echo "")
+fi
+if [ "$SYNC_MODE" = "off" ] || [ -z "$SYNC_MODE" ]; then
+  exit 0
+fi
+
+# Skip if no brain-sync git repo exists.
+if [ ! -d "${HOME}/.gstack/.git" ]; then
+  exit 0
+fi
+
+# Skip if helper missing (defensive — should always be present post-upgrade).
+if [ ! -x "$WIREUP_BIN" ]; then
+  echo "  [v1.17.0.0] $WIREUP_BIN missing or non-executable — skipping wireup." >&2
+  exit 0
+fi
+
+echo "  [v1.17.0.0] Wiring brain-sync repo into gbrain (federated source + initial sync)..."
+
+# No --strict: missing/old gbrain is a benign skip during a batch upgrade.
+"$WIREUP_BIN" || {
+  echo "  [v1.17.0.0] Wireup exited non-zero — re-run manually with: $WIREUP_BIN" >&2
+}
diff --git a/package.json b/package.json
index 4aac18f0..c26d8682 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gstack",
-  "version": "1.16.0.0",
+  "version": "1.19.0.0",
   "description": "Garry's Stack — Claude Code skills + fast headless browser. One repo, one install, entire AI engineering workflow.",
   "license": "MIT",
   "type": "module",
diff --git a/scripts/compare-pr-version.ts b/scripts/compare-pr-version.ts
index 00bf3cea..27f746aa 100644
--- a/scripts/compare-pr-version.ts
+++ b/scripts/compare-pr-version.ts
@@ -1,14 +1,19 @@
 #!/usr/bin/env bun
-// compare-pr-version — CI gate helper. Compares the util's next-slot output
-// against the PR's branch VERSION. Exits 0 (pass), 1 (confirmed collision),
-// or 2 (util was offline — fail-open per user decision, exit 0 with warning).
+// compare-pr-version — CI gate helper. Validates the PR's branch VERSION
+// against the queue of other open PRs' claimed versions. Exits 0 (pass)
+// or 1 (confirmed collision).
 //
 // Input:
 //   argv[2] — path to next.json (the util's JSON output)
 //   argv[3] — optional PR number for log lines
 //
 // Design note: fail-open on util error. A gstack bug must never freeze the
-// merge queue. Confirmed collisions (util OK, PR version < next slot) DO block.
+// merge queue. The gate enforces ONE rule: this PR must not claim the same
+// version as another open PR. Lower-than-the-util's-suggestion is fine if
+// the slot is unclaimed — that preserves monotonic version ordering on main
+// when this PR lands ahead of higher-numbered queued PRs. The util's output
+// is informational (the *recommended* slot for fresh /ship runs); the gate
+// only blocks actual collisions.
 
 import { readFileSync } from "node:fs";
 
@@ -58,25 +63,44 @@ if (!pPR || !pNext) {
 }
 
 const tag = prNumber ? `PR #${prNumber}` : "this PR";
+const claimed = (parsed.claimed ?? []) as Array<{ pr: number; branch: string; version: string; url?: string }>;
 
 // Emit a GitHub step summary (always helpful, even on pass).
-const claimedList = (parsed.claimed ?? [])
-  .map((c: any) => `  #${c.pr} ${c.branch} → v${c.version}`)
+const claimedList = claimed
+  .map((c) => `  #${c.pr} ${c.branch} → v${c.version}`)
   .join("\n");
 
 console.log(`::group::Version gate (${tag})`);
-console.log(`  PR VERSION:  v${prVersion}`);
-console.log(`  Next slot:   v${nextSlot}`);
-console.log(`  Queue (${(parsed.claimed ?? []).length} open PRs claiming versions):`);
+console.log(`  PR VERSION:    v${prVersion}`);
+console.log(`  Suggested:     v${nextSlot} (util's next-slot recommendation)`);
+console.log(`  Queue (${claimed.length} open PRs claiming versions):`);
 if (claimedList) console.log(claimedList);
 console.log("::endgroup::");
 
-if (cmp(pPR, pNext) >= 0) {
-  console.log(`✓ ${tag} claims v${prVersion} — slot is free (next would be v${nextSlot}).`);
-  process.exit(0);
+// Hard rule 1: this PR's VERSION must be strictly greater than the base
+// version, otherwise we're not actually bumping.
+const pBase = parseV((parsed.base_version ?? "").trim());
+if (pBase && cmp(pPR, pBase) <= 0) {
+  console.log(`::error::VERSION not bumped: ${tag} claims v${prVersion} but base is v${parsed.base_version}.`);
+  process.exit(1);
 }
 
-// Confirmed collision: PR version is stale.
-console.log(`::error::VERSION drift: ${tag} claims v${prVersion} but the queue has moved — next free slot is v${nextSlot}.`);
-console.log(`::error::Rerun /ship from the feature branch to reconcile. /ship's ALREADY_BUMPED branch handles this atomically (VERSION, package.json, CHANGELOG, PR title).`);
-process.exit(1);
+// Hard rule 2: no collision with another open PR's claimed VERSION.
+const collision = claimed.find((c) => c.version.trim() === prVersion);
+if (collision) {
+  console.log(`::error::VERSION collision: ${tag} claims v${prVersion} but #${collision.pr} (${collision.branch}) already claims the same slot.`);
+  console.log(`::error::Rerun /ship to pick a different slot, or coordinate with #${collision.pr} on landing order.`);
+  process.exit(1);
+}
+
+// Optional informational note: PR version is below the util's suggested next
+// slot. This is allowed — the suggested slot is a recommendation for /ship's
+// next run, but landing at a lower-but-unclaimed slot first preserves
+// monotonic ordering on main when this PR merges ahead of higher-numbered
+// queued PRs.
+if (cmp(pPR, pNext) < 0) {
+  console.log(`::notice::${tag} claims v${prVersion}, below util's suggestion v${nextSlot}. Slot is unclaimed; gate passes. If this PR lands ahead of queued PRs at higher slots, version ordering on main remains monotonic.`);
+}
+
+console.log(`✓ ${tag} claims v${prVersion} — slot is free.`);
+process.exit(0);
diff --git a/setup-gbrain/SKILL.md b/setup-gbrain/SKILL.md
index 77e297b4..1ee78dac 100644
--- a/setup-gbrain/SKILL.md
+++ b/setup-gbrain/SKILL.md
@@ -986,7 +986,7 @@ For `/setup-gbrain --repo` invocations, execute ONLY Step 6 and exit.
 
 ---
 
-## Step 7: Offer gstack-brain-sync
+## Step 7: Offer gstack-brain-sync + wire it into gbrain
 
 Separate AskUserQuestion: "Also sync your gstack session memory (learnings,
 plans, retros) to a private git repo that gbrain can index across machines?"
@@ -1004,6 +1004,37 @@ If yes:
 # or "full" if user picked yes-full
 ```
 
+Then wire the brain repo into gbrain so its content is searchable from any
+gbrain client (this Claude Code session, future Macs, optional cloud agents).
+The helper creates a `git worktree` of `~/.gstack/`, registers it as a
+federated source on the user's gbrain (Supabase or PGLite), and runs an
+initial `gbrain sync`. Local-Mac only. No cloud agent required. Subsequent
+skill runs trigger incremental sync via the existing skill-end push hook.
+
+Capture the database URL out of `~/.gbrain/config.json` first and pass it
+explicitly so the wireup is robust against any other process rewriting
+`~/.gbrain/config.json` mid-sync (e.g., concurrent `gbrain init` runs
+elsewhere on the machine):
+
+```bash
+GBRAIN_URL=$(python3 -c "
+import json, os, sys
+try:
+    c = json.load(open(os.path.expanduser('~/.gbrain/config.json')))
+    print(c.get('database_url', ''))
+except Exception:
+    pass
+")
+~/.claude/skills/gstack/bin/gstack-gbrain-source-wireup --strict \
+  ${GBRAIN_URL:+--database-url "$GBRAIN_URL"}
+```
+
+`--strict` exits non-zero on missing prereqs (gbrain not installed, < 0.18.0,
+or no `~/.gstack/.git` yet) so the user sees the failure rather than silently
+ending up with an unwired brain. On non-zero exit, surface the helper's
+output and STOP per skill rules — search-across-machines won't work until
+the prereq is fixed.
+
 ---
 
 ## Step 8: Persist `## GBrain Configuration` in CLAUDE.md
diff --git a/setup-gbrain/SKILL.md.tmpl b/setup-gbrain/SKILL.md.tmpl
index 685e15e0..3bbf9b12 100644
--- a/setup-gbrain/SKILL.md.tmpl
+++ b/setup-gbrain/SKILL.md.tmpl
@@ -347,7 +347,7 @@ For `/setup-gbrain --repo` invocations, execute ONLY Step 6 and exit.
 
 ---
 
-## Step 7: Offer gstack-brain-sync
+## Step 7: Offer gstack-brain-sync + wire it into gbrain
 
 Separate AskUserQuestion: "Also sync your gstack session memory (learnings,
 plans, retros) to a private git repo that gbrain can index across machines?"
@@ -365,6 +365,37 @@ If yes:
 # or "full" if user picked yes-full
 ```
 
+Then wire the brain repo into gbrain so its content is searchable from any
+gbrain client (this Claude Code session, future Macs, optional cloud agents).
+The helper creates a `git worktree` of `~/.gstack/`, registers it as a
+federated source on the user's gbrain (Supabase or PGLite), and runs an
+initial `gbrain sync`. Local-Mac only. No cloud agent required. Subsequent
+skill runs trigger incremental sync via the existing skill-end push hook.
+
+Capture the database URL out of `~/.gbrain/config.json` first and pass it
+explicitly so the wireup is robust against any other process rewriting
+`~/.gbrain/config.json` mid-sync (e.g., concurrent `gbrain init` runs
+elsewhere on the machine):
+
+```bash
+GBRAIN_URL=$(python3 -c "
+import json, os, sys
+try:
+    c = json.load(open(os.path.expanduser('~/.gbrain/config.json')))
+    print(c.get('database_url', ''))
+except Exception:
+    pass
+")
+~/.claude/skills/gstack/bin/gstack-gbrain-source-wireup --strict \
+  ${GBRAIN_URL:+--database-url "$GBRAIN_URL"}
+```
+
+`--strict` exits non-zero on missing prereqs (gbrain not installed, < 0.18.0,
+or no `~/.gstack/.git` yet) so the user sees the failure rather than silently
+ending up with an unwired brain. On non-zero exit, surface the helper's
+output and STOP per skill rules — search-across-machines won't work until
+the prereq is fixed.
+
 ---
 
 ## Step 8: Persist `## GBrain Configuration` in CLAUDE.md
diff --git a/test/gstack-gbrain-source-wireup.test.ts b/test/gstack-gbrain-source-wireup.test.ts
new file mode 100644
index 00000000..d7a30b76
--- /dev/null
+++ b/test/gstack-gbrain-source-wireup.test.ts
@@ -0,0 +1,440 @@
+/**
+ * gstack-gbrain-source-wireup — unit tests with mocked gbrain CLI.
+ *
+ * The helper registers the gstack brain repo as a gbrain federated source
+ * via `git worktree`, runs an initial sync, and exposes --uninstall + --probe.
+ *
+ * Strategy: put a fake `gbrain` binary on PATH that records every call into
+ * a log file and reads/writes its "registered sources" state from a JSON
+ * file in the test's tmp dir. The helper sees a consistent gbrain-CLI surface
+ * but no real database, no real gbrain.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const BIN_DIR = path.join(ROOT, 'bin');
+const WIREUP_BIN = path.join(BIN_DIR, 'gstack-gbrain-source-wireup');
+
+let tmpHome: string;
+let gstackHome: string;
+let worktreeDir: string;
+let fakeBinDir: string;
+let gbrainCallLog: string;
+let gbrainStateFile: string;
+
+function makeFakeGbrain(opts: {
+  version?: string | null; // null = "binary missing" (don't write the file)
+  syncFails?: boolean;
+}) {
+  const version = opts.version ?? '0.18.2';
+  if (version === null) return; // simulate missing binary by NOT writing one
+  const syncFails = opts.syncFails ?? false;
+
+  // Stub gbrain reads/writes state from a JSON file. Fields:
+  //   sources: [{id, local_path, federated}]
+  fs.writeFileSync(gbrainStateFile, JSON.stringify({ sources: [] }, null, 2));
+
+  const script = `#!/bin/bash
+LOG="${gbrainCallLog}"
+STATE="${gbrainStateFile}"
+# Record the call AND any GBRAIN_DATABASE_URL that the parent passed via env.
+# Format: "gbrain <args> [GBRAIN_DATABASE_URL=<url>]" so tests can assert
+# the wireup helper exported the locked URL into our env.
+LINE="gbrain $@"
+[ -n "\${GBRAIN_DATABASE_URL:-}" ] && LINE="\$LINE [GBRAIN_DATABASE_URL=\$GBRAIN_DATABASE_URL]"
+echo "\$LINE" >> "$LOG"
+
+# --version
+if [ "$1" = "--version" ]; then
+  echo "gbrain ${version}"
+  exit 0
+fi
+
+# sources list --json  → emits state
+if [ "$1" = "sources" ] && [ "$2" = "list" ]; then
+  cat "$STATE"
+  exit 0
+fi
+
+# sources add <id> --path <p> --federated  → adds entry
+if [ "$1" = "sources" ] && [ "$2" = "add" ]; then
+  shift 2
+  ID="$1"; shift
+  PATH_VAL=""
+  FED="false"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --path) PATH_VAL="$2"; shift 2 ;;
+      --federated) FED="true"; shift ;;
+      *) shift ;;
+    esac
+  done
+  python3 -c "
+import json, sys
+state = json.load(open('$STATE'))
+state['sources'].append({'id': '$ID', 'local_path': '$PATH_VAL', 'federated': '$FED' == 'true'})
+json.dump(state, open('$STATE','w'), indent=2)
+" || exit 1
+  exit 0
+fi
+
+# sources remove <id> --yes  → drops entry
+if [ "$1" = "sources" ] && [ "$2" = "remove" ]; then
+  shift 2
+  ID="$1"
+  python3 -c "
+import json
+state = json.load(open('$STATE'))
+state['sources'] = [s for s in state['sources'] if s['id'] != '$ID']
+json.dump(state, open('$STATE','w'), indent=2)
+"
+  exit 0
+fi
+
+# sync --repo <p>  → records, optionally fails
+if [ "$1" = "sync" ]; then
+  ${syncFails ? 'echo "sync failed: connection error" >&2; exit 1' : 'echo "1 page imported"; exit 0'}
+fi
+
+echo "fake gbrain: unhandled subcommand: $@" >&2
+exit 99
+`;
+  const gbrainPath = path.join(fakeBinDir, 'gbrain');
+  fs.writeFileSync(gbrainPath, script, { mode: 0o755 });
+}
+
+function run(
+  argv: string[],
+  opts: { env?: Record<string, string> } = {}
+) {
+  const env = {
+    PATH: `${fakeBinDir}:${process.env.PATH || '/usr/bin:/bin:/opt/homebrew/bin'}`,
+    HOME: tmpHome,
+    GSTACK_HOME: gstackHome,
+    GSTACK_BRAIN_WORKTREE: worktreeDir,
+    GSTACK_BRAIN_NO_SYNC: '0',
+    ...(opts.env || {}),
+  };
+  return spawnSync(WIREUP_BIN, argv, {
+    env,
+    encoding: 'utf-8',
+    cwd: ROOT,
+  });
+}
+
+function readState(): { sources: Array<{ id: string; local_path: string; federated: boolean }> } {
+  if (!fs.existsSync(gbrainStateFile)) return { sources: [] };
+  return JSON.parse(fs.readFileSync(gbrainStateFile, 'utf-8'));
+}
+
+function gbrainCalls(): string[] {
+  if (!fs.existsSync(gbrainCallLog)) return [];
+  return fs.readFileSync(gbrainCallLog, 'utf-8')
+    .split('\n')
+    .filter((l) => l.trim());
+}
+
+function setupGstackRepo(remoteUrl: string) {
+  // Real git repo at gstackHome with at least one commit + an origin remote.
+  fs.mkdirSync(gstackHome, { recursive: true });
+  spawnSync('git', ['-C', gstackHome, 'init', '-q', '-b', 'main'], { stdio: 'pipe' });
+  spawnSync('git', ['-C', gstackHome, 'config', 'user.email', 'test@example.com'], { stdio: 'pipe' });
+  spawnSync('git', ['-C', gstackHome, 'config', 'user.name', 'test'], { stdio: 'pipe' });
+  fs.writeFileSync(path.join(gstackHome, '.brain-allowlist'), '# allowlist\n');
+  spawnSync('git', ['-C', gstackHome, 'add', '.'], { stdio: 'pipe' });
+  spawnSync('git', ['-C', gstackHome, 'commit', '-q', '-m', 'init'], { stdio: 'pipe' });
+  spawnSync('git', ['-C', gstackHome, 'remote', 'add', 'origin', remoteUrl], { stdio: 'pipe' });
+}
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-wireup-test-'));
+  gstackHome = path.join(tmpHome, '.gstack');
+  worktreeDir = path.join(tmpHome, '.gstack-brain-worktree');
+  fakeBinDir = path.join(tmpHome, 'fake-bin');
+  fs.mkdirSync(fakeBinDir, { recursive: true });
+  gbrainCallLog = path.join(tmpHome, 'gbrain-calls.log');
+  gbrainStateFile = path.join(tmpHome, 'gbrain-state.json');
+});
+
+afterEach(() => {
+  try {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  } catch {}
+});
+
+describe('gstack-gbrain-source-wireup — wireup mode', () => {
+  test('fresh state: registers source + creates worktree + syncs', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    const r = run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(r.status).toBe(0);
+    expect(fs.existsSync(worktreeDir)).toBe(true);
+    const state = readState();
+    expect(state.sources).toHaveLength(1);
+    expect(state.sources[0].id).toBe('gstack-brain-user');
+    expect(state.sources[0].local_path).toBe(worktreeDir);
+    expect(state.sources[0].federated).toBe(true);
+  });
+
+  test('idempotent re-run after success: no new sources add call', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    const callsAfterFirst = gbrainCalls().filter((c) => c.startsWith('gbrain sources add')).length;
+    expect(callsAfterFirst).toBe(1);
+    run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    const callsAfterSecond = gbrainCalls().filter((c) => c.startsWith('gbrain sources add')).length;
+    expect(callsAfterSecond).toBe(1); // no new add
+  });
+
+  test('drift recovery: existing source with different path triggers remove + add', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    // Pre-seed the fake gbrain state with a source at the wrong path
+    fs.writeFileSync(
+      gbrainStateFile,
+      JSON.stringify({
+        sources: [{ id: 'gstack-brain-user', local_path: '/old/stale/path', federated: true }],
+      })
+    );
+    const r = run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(r.status).toBe(0);
+    const calls = gbrainCalls();
+    expect(calls.some((c) => c.startsWith('gbrain sources remove gstack-brain-user'))).toBe(true);
+    expect(calls.some((c) => c.includes(`gbrain sources add gstack-brain-user --path ${worktreeDir}`))).toBe(true);
+    const state = readState();
+    expect(state.sources[0].local_path).toBe(worktreeDir);
+  });
+
+  test('--strict + gbrain too old: exits 2', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({ version: '0.17.0' });
+    const r = run(['--strict']);
+    expect(r.status).toBe(2);
+    expect(r.stderr).toContain('< 0.18.0');
+  });
+
+  test('non-strict + gbrain too old: warn + exit 0', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({ version: '0.17.0' });
+    const r = run([]);
+    expect(r.status).toBe(0);
+    expect(r.stderr).toContain('benign skip');
+  });
+
+  test('--strict + gbrain missing on PATH: exits 2', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    // Don't make a fake gbrain — fakeBinDir is empty. Keep system dirs on PATH
+    // so basic commands (git, awk, sed, etc.) work; only `gbrain` is absent.
+    const r = run(['--strict'], {
+      env: { PATH: `${fakeBinDir}:/usr/bin:/bin:/opt/homebrew/bin` },
+    });
+    expect(r.status).toBe(2);
+  });
+
+  test('source-id derived from origin URL', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-alice.git');
+    makeFakeGbrain({});
+    const r = run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(r.status).toBe(0);
+    expect(readState().sources[0].id).toBe('gstack-brain-alice');
+  });
+
+  test('source-id fallback to ~/.gstack-brain-remote.txt when .git is gone', () => {
+    // No git repo at gstackHome; just the remote-file
+    fs.mkdirSync(tmpHome, { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.gstack-brain-remote.txt'),
+      'git@github.com:user/gstack-brain-bob.git\n'
+    );
+    makeFakeGbrain({});
+    // No --strict: helper should benign-skip because .gstack/.git is missing
+    const r = run([]);
+    // ensure_worktree returns 2 → benign skip, exit 0
+    expect(r.status).toBe(0);
+  });
+
+  test('source-id from --source-id flag overrides everything', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-different.git');
+    makeFakeGbrain({});
+    run(['--source-id', 'custom-id'], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    const state = readState();
+    expect(state.sources[0].id).toBe('custom-id');
+  });
+
+  test('--probe: read-only, prints state without mutating', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    const r = run(['--probe']);
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain('source_id=gstack-brain-user');
+    expect(r.stdout).toContain('worktree=');
+    expect(r.stdout).toContain('gbrain=ok');
+    expect(r.stdout).toContain('source_status=absent');
+    // Probe should NOT call sources add / sync
+    const calls = gbrainCalls();
+    expect(calls.some((c) => c.startsWith('gbrain sources add'))).toBe(false);
+    expect(calls.some((c) => c.startsWith('gbrain sync'))).toBe(false);
+  });
+
+  test('gbrain sync failure: exits 1 with stderr', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({ syncFails: true });
+    const r = run([]);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('sync failed');
+  });
+});
+
+describe('gstack-gbrain-source-wireup — --database-url lock (defends against external config rewrites)', () => {
+  test('--database-url flag is exported as GBRAIN_DATABASE_URL to child gbrain calls', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    const TARGET = 'postgresql://postgres.abc:pw@aws.pooler.supabase.com:5432/postgres';
+    const r = run(['--database-url', TARGET], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(r.status).toBe(0);
+    const calls = gbrainCalls();
+    // every gbrain invocation should carry the locked URL
+    const writingCalls = calls.filter((c) => c.includes('sources') || c.includes('sync'));
+    expect(writingCalls.length).toBeGreaterThan(0);
+    for (const c of writingCalls) {
+      expect(c).toContain(`[GBRAIN_DATABASE_URL=${TARGET}]`);
+    }
+  });
+
+  test('falls back to ~/.gbrain/config.json database_url when no flag and no env', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    const FILE_URL = 'postgresql://postgres.xyz:pw@aws.pooler.supabase.com:5432/postgres';
+    fs.mkdirSync(path.join(tmpHome, '.gbrain'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.gbrain', 'config.json'),
+      JSON.stringify({ engine: 'postgres', database_url: FILE_URL })
+    );
+    // Important: don't pass GBRAIN_DATABASE_URL or DATABASE_URL in env; helper
+    // should read from $HOME/.gbrain/config.json (HOME is tmpHome here).
+    const r = run([], {
+      env: {
+        GSTACK_BRAIN_NO_SYNC: '1',
+        GBRAIN_DATABASE_URL: '',
+        DATABASE_URL: '',
+      },
+    });
+    expect(r.status).toBe(0);
+    const calls = gbrainCalls();
+    const writingCalls = calls.filter((c) => c.includes('sources add'));
+    expect(writingCalls.length).toBe(1);
+    expect(writingCalls[0]).toContain(`[GBRAIN_DATABASE_URL=${FILE_URL}]`);
+  });
+
+  test('--database-url overrides env GBRAIN_DATABASE_URL and config.json', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    const FLAG_URL = 'postgresql://postgres.flag:pw@a.b:5432/postgres';
+    const ENV_URL = 'postgresql://postgres.env:pw@x.y:5432/postgres';
+    const FILE_URL = 'postgresql://postgres.file:pw@p.q:5432/postgres';
+    fs.mkdirSync(path.join(tmpHome, '.gbrain'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.gbrain', 'config.json'),
+      JSON.stringify({ engine: 'postgres', database_url: FILE_URL })
+    );
+    const r = run(['--database-url', FLAG_URL], {
+      env: {
+        GSTACK_BRAIN_NO_SYNC: '1',
+        GBRAIN_DATABASE_URL: ENV_URL,
+      },
+    });
+    expect(r.status).toBe(0);
+    const calls = gbrainCalls();
+    const writingCalls = calls.filter((c) => c.includes('sources add'));
+    expect(writingCalls.length).toBe(1);
+    expect(writingCalls[0]).toContain(`[GBRAIN_DATABASE_URL=${FLAG_URL}]`);
+    expect(writingCalls[0]).not.toContain(ENV_URL);
+    expect(writingCalls[0]).not.toContain(FILE_URL);
+  });
+});
+
+describe('gstack-gbrain-source-wireup — uninstall mode', () => {
+  test('after wireup: removes source + worktree', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(readState().sources).toHaveLength(1);
+    expect(fs.existsSync(worktreeDir)).toBe(true);
+    const r = run(['--uninstall']);
+    expect(r.status).toBe(0);
+    expect(readState().sources).toHaveLength(0);
+    expect(fs.existsSync(worktreeDir)).toBe(false);
+  });
+
+  test('with no prior state: exits 3 (cannot derive id)', () => {
+    // No git repo, no remote file. --uninstall must fail with code 3.
+    fs.mkdirSync(tmpHome, { recursive: true });
+    makeFakeGbrain({});
+    const r = run(['--uninstall']);
+    expect(r.status).toBe(3);
+  });
+
+  test('--uninstall when gbrain is missing: exits 0 (best-effort), still removes worktree', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    // First wireup with fake gbrain to create the worktree + register source
+    makeFakeGbrain({});
+    run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(fs.existsSync(worktreeDir)).toBe(true);
+    // Now remove the fake gbrain so uninstall sees gbrain missing
+    fs.rmSync(path.join(fakeBinDir, 'gbrain'), { force: true });
+    const r = run(['--uninstall'], {
+      env: { PATH: `${fakeBinDir}:/usr/bin:/bin:/opt/homebrew/bin` },
+    });
+    expect(r.status).toBe(0); // best-effort, never fails on gbrain absence
+    expect(fs.existsSync(worktreeDir)).toBe(false); // worktree still cleaned up
+  });
+});
+
+describe('gstack-gbrain-source-wireup — defensive paths', () => {
+  test('--no-pull skips HEAD advance on existing worktree', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    // First run to create worktree
+    run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    // Make a new commit on parent so worktree HEAD is "behind"
+    fs.writeFileSync(path.join(gstackHome, 'newfile.md'), 'new');
+    spawnSync('git', ['-C', gstackHome, 'add', '.'], { stdio: 'pipe' });
+    spawnSync('git', ['-C', gstackHome, 'commit', '-q', '-m', 'second commit'], { stdio: 'pipe' });
+    const parentHeadAfter = spawnSync('git', ['-C', gstackHome, 'rev-parse', 'HEAD'], {
+      encoding: 'utf-8',
+    }).stdout.trim();
+    const worktreeHeadBefore = spawnSync('git', ['-C', worktreeDir, 'rev-parse', 'HEAD'], {
+      encoding: 'utf-8',
+    }).stdout.trim();
+    expect(parentHeadAfter).not.toBe(worktreeHeadBefore); // sanity: parent advanced
+    // --no-pull should leave worktree HEAD where it was
+    const r = run(['--no-pull'], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(r.status).toBe(0);
+    const worktreeHeadAfter = spawnSync('git', ['-C', worktreeDir, 'rev-parse', 'HEAD'], {
+      encoding: 'utf-8',
+    }).stdout.trim();
+    expect(worktreeHeadAfter).toBe(worktreeHeadBefore);
+    expect(worktreeHeadAfter).not.toBe(parentHeadAfter);
+  });
+
+  test('stray non-git directory at worktree path is cleaned up + worktree created', () => {
+    setupGstackRepo('git@github.com:user/gstack-brain-user.git');
+    makeFakeGbrain({});
+    // Plant a stray non-git directory at the worktree path
+    fs.mkdirSync(worktreeDir, { recursive: true });
+    fs.writeFileSync(path.join(worktreeDir, 'unrelated.txt'), 'not a worktree');
+    expect(fs.existsSync(path.join(worktreeDir, 'unrelated.txt'))).toBe(true);
+    expect(fs.existsSync(path.join(worktreeDir, '.git'))).toBe(false);
+    // Helper should remove the stray dir + create a real worktree
+    const r = run([], { env: { GSTACK_BRAIN_NO_SYNC: '1' } });
+    expect(r.status).toBe(0);
+    expect(fs.existsSync(path.join(worktreeDir, '.git'))).toBe(true); // real worktree
+    expect(fs.existsSync(path.join(worktreeDir, 'unrelated.txt'))).toBe(false); // stray gone
+  });
+});
diff --git a/test/gstack-upgrade-migration-v1_17_0_0.test.ts b/test/gstack-upgrade-migration-v1_17_0_0.test.ts
new file mode 100644
index 00000000..e1d20a95
--- /dev/null
+++ b/test/gstack-upgrade-migration-v1_17_0_0.test.ts
@@ -0,0 +1,151 @@
+/**
+ * gstack-upgrade/migrations/v1.17.0.0.sh — migration script unit tests.
+ *
+ * The migration runs on /gstack-upgrade for users with brain-sync configured but
+ * never wired up to gbrain. It has 4 skip conditions and one happy path.
+ *
+ * Strategy: stub gstack-config and gstack-gbrain-source-wireup binaries on PATH
+ * so each skip condition can be triggered independently. The migration script
+ * itself is plain bash — we exercise it directly.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+const MIGRATION = path.join(ROOT, 'gstack-upgrade', 'migrations', 'v1.17.0.0.sh');
+
+let tmpHome: string;
+let fakeBinDir: string;
+let stubLog: string;
+
+function makeFakeStubs(opts: {
+  configValue?: string; // value gstack-config returns for gbrain_sync_mode
+  configMissing?: boolean; // gstack-config binary itself missing (test edge)
+  wireupMissing?: boolean; // wireup binary missing
+  wireupExitCode?: number;
+}) {
+  const skillsBin = path.join(tmpHome, '.claude', 'skills', 'gstack', 'bin');
+  fs.mkdirSync(skillsBin, { recursive: true });
+
+  if (!opts.configMissing) {
+    const cfg = `#!/bin/bash
+echo "gstack-config $@" >> "${stubLog}"
+[ "$1" = "get" ] && [ "$2" = "gbrain_sync_mode" ] && echo "${opts.configValue ?? ''}"
+exit 0
+`;
+    fs.writeFileSync(path.join(skillsBin, 'gstack-config'), cfg, { mode: 0o755 });
+  }
+
+  if (!opts.wireupMissing) {
+    const wu = `#!/bin/bash
+echo "gstack-gbrain-source-wireup $@" >> "${stubLog}"
+exit ${opts.wireupExitCode ?? 0}
+`;
+    fs.writeFileSync(path.join(skillsBin, 'gstack-gbrain-source-wireup'), wu, { mode: 0o755 });
+  }
+}
+
+function makeBrainGitRepo() {
+  const gstackHome = path.join(tmpHome, '.gstack');
+  fs.mkdirSync(path.join(gstackHome, '.git'), { recursive: true });
+}
+
+function run(opts: { env?: Record<string, string> } = {}) {
+  const env = {
+    PATH: '/usr/bin:/bin:/opt/homebrew/bin',
+    HOME: tmpHome,
+    ...(opts.env || {}),
+  };
+  return spawnSync('bash', [MIGRATION], {
+    env,
+    encoding: 'utf-8',
+    cwd: tmpHome,
+  });
+}
+
+function stubCalls(): string[] {
+  if (!fs.existsSync(stubLog)) return [];
+  return fs.readFileSync(stubLog, 'utf-8').split('\n').filter((l) => l.trim());
+}
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-migration-test-'));
+  fakeBinDir = path.join(tmpHome, 'fake-bin');
+  fs.mkdirSync(fakeBinDir, { recursive: true });
+  stubLog = path.join(tmpHome, 'stub-calls.log');
+});
+
+afterEach(() => {
+  try {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  } catch {}
+});
+
+describe('migrations/v1.17.0.0.sh', () => {
+  test('HOME unset: prints message + exit 0 (defensive)', () => {
+    // Override HOME to empty string. Bash's [ -z "${HOME:-}" ] guard should fire.
+    const r = run({ env: { HOME: '' } });
+    expect(r.status).toBe(0);
+    expect(r.stderr).toContain('HOME is unset or empty');
+  });
+
+  test('gbrain_sync_mode = off: exit 0 silently (no helper invoked)', () => {
+    makeFakeStubs({ configValue: 'off' });
+    const r = run();
+    expect(r.status).toBe(0);
+    // Helper should not have been invoked
+    const calls = stubCalls();
+    expect(calls.some((c) => c.startsWith('gstack-gbrain-source-wireup'))).toBe(false);
+  });
+
+  test('gbrain_sync_mode unset/empty: exit 0 silently', () => {
+    makeFakeStubs({ configValue: '' }); // empty string return
+    const r = run();
+    expect(r.status).toBe(0);
+    const calls = stubCalls();
+    expect(calls.some((c) => c.startsWith('gstack-gbrain-source-wireup'))).toBe(false);
+  });
+
+  test('no ~/.gstack/.git: exit 0 silently (no brain-sync configured)', () => {
+    makeFakeStubs({ configValue: 'full' });
+    // Do NOT call makeBrainGitRepo() — no .gstack/.git directory exists
+    const r = run();
+    expect(r.status).toBe(0);
+    const calls = stubCalls();
+    expect(calls.some((c) => c.startsWith('gstack-gbrain-source-wireup'))).toBe(false);
+  });
+
+  test('helper missing on PATH: prints warning, exit 0 (defensive)', () => {
+    makeFakeStubs({ configValue: 'full', wireupMissing: true });
+    makeBrainGitRepo();
+    const r = run();
+    expect(r.status).toBe(0);
+    expect(r.stderr).toContain('missing or non-executable');
+  });
+
+  test('happy path: invokes the helper', () => {
+    makeFakeStubs({ configValue: 'full' });
+    makeBrainGitRepo();
+    const r = run();
+    expect(r.status).toBe(0);
+    const calls = stubCalls();
+    expect(calls.some((c) => c.startsWith('gstack-gbrain-source-wireup'))).toBe(true);
+    // Note: migration invokes WITHOUT --strict (benign-skip semantics for batch upgrade)
+    const helperCall = calls.find((c) => c.startsWith('gstack-gbrain-source-wireup'));
+    expect(helperCall).not.toContain('--strict');
+  });
+
+  test('helper exits non-zero: migration prints retry hint, exit 0 (non-blocking)', () => {
+    // The migration uses `|| { echo retry-hint; }` so non-zero helper still
+    // exits 0 and prints a retry hint to stderr.
+    makeFakeStubs({ configValue: 'full', wireupExitCode: 2 });
+    makeBrainGitRepo();
+    const r = run();
+    expect(r.status).toBe(0); // migration is non-blocking
+    expect(r.stderr).toContain('Wireup exited non-zero');
+  });
+});