* fix(gstack-paths): guard CLAUDE_PLUGIN_DATA against cross-plugin contamination (#1569) gstack-paths previously trusted CLAUDE_PLUGIN_DATA as a fallback for GSTACK_STATE_ROOT whenever GSTACK_HOME was unset. When another plugin (e.g. Codex) persists its own CLAUDE_PLUGIN_DATA into the session env via CLAUDE_ENV_FILE, gstack picked it up and wrote checkpoints, analytics, and learnings into that plugin's directory. Anyone with the Codex plugin installed alongside gstack hit this silently. Fix: guard the CLAUDE_PLUGIN_DATA branch so it only fires when CLAUDE_PLUGIN_ROOT confirms we're running as the gstack plugin (path contains "gstack"). Skill installs fall through to \$HOME/.gstack. Contributed by @ElliotDrel via #1570. Closes #1569. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(gbrain-sync): sourceLocalPath handles wrapped {sources:[...]} shape from gbrain v0.20+ gbrain v0.20+ changed `gbrain sources list --json` to return {sources: [...]} instead of a flat array. sourceLocalPath crashed upstream with `list.find is not a function` on every /sync-gbrain invocation against modern gbrain. Accept both shapes for forward/backward compat, matching probeSource/sourcePageCount in lib/gbrain-sources.ts. Contributed by @jakehann11 via #1571. Closes #1567. Supersedes #1564 (@tonyjzhou, same fix, different shape — credit retained). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(brain-context-load): probe gbrain via execFile, not shell builtin (#1559) gbrainAvailable() used `execFileSync("command", ["-v", "gbrain"])`, which fails in any environment where the `command` builtin isn't on the spawned process's PATH (most non-interactive shells). The probe then reported gbrain as missing even when it was installed, and context-load silently skipped vector/list queries. Fix: probe `gbrain --version` directly with a 500ms timeout (matching the rest of the file's MCP_TIMEOUT_MS). Same semantics, works everywhere execFile works. Contributed by @jbetala7 via #1560. Closes #1559. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(gbrain-doctor): pin schema_version:2 doctor parse path (#1418) Adds an exec-path regression test that runs a fake gbrain shim emitting the v0.25+ doctor JSON shape (schema_version: 2, status: "warnings", exit 1 for health_score < 100, no top-level `engine` field). Confirms freshDetectEngineTier recovers stdout from the non-zero exit and falls back to GBRAIN_HOME/config.json for the engine label. The pre-existing test for #1415 only stripped gbrain from PATH; this test exercises the actual doctor parse path, closing the gap that codex's plan review flagged. Also documents the schema_version separation in lib/gbrain-local-status.ts: the local CacheEntry stays at version 1, distinct from the doctor-output schema_version which we accept across versions in gstack-memory-helpers. Closes #1418 (credit @mvanhorn for surfacing the doctor + schema_v2 collapse). The fix landed pre-emptively in v1.29.x; this commit pins it with a stronger test. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(memory-ingest): pin put_page regression + scrub stale name from --help and comments (#1346) #1346 reported that gstack-memory-ingest still called the renamed gbrain put_page subcommand on gbrain v0.18+. The actual code migrated to `gbrain put` and later to batch `gbrain import <dir>` before this report landed — only documentation lag remained. This commit: - Updates the --help string ("Skip gbrain put calls (still updates state file)") so user-facing docs match the shipped subcommand - Updates two inline comments that still referenced the old name - Adds test/memory-ingest-no-put_page.test.ts: a regression pin that strips comments from bin/gstack-memory-ingest.ts and fails the build if "put_page" appears in any active code or string literal, plus a sanity check that the file still calls a supported gbrain page-write verb (put or import) Closes #1346. Reporter @kylma-code surfaced the doc lag; the original code migration credit is on the v1.27.x wave. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(resolvers): rewrite all gbrain put_page instructions to canonical put <slug> scripts/resolvers/gbrain.ts emitted user-facing copy-paste instructions using the renamed `gbrain put_page` subcommand across 10 skills (office-hours, investigate, plan-ceo-review, retro, plan-eng-review, ship, cso, design-consultation, fallback, entity-stub). Every gstack user copying those snippets hit "unknown command: put_page" on gbrain v0.18+. This commit: - Rewrites all 10 instruction templates to use `gbrain put <slug> --content "$(cat <<EOF...EOF)"` with title/tags moved into YAML frontmatter inside --content, matching the v0.18+ subcommand shape - Updates README.md and USING_GBRAIN_WITH_GSTACK.md "common commands" table to reference `gbrain put` and `gbrain get` - Adds test/resolvers-gbrain-put-rewrite.test.ts pinning two invariants: (a) resolver source ships only canonical instructions, (b) every tracked SKILL.md file is free of `gbrain put_page` CHANGELOG entries are deliberately left untouched (historical record). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(build): extract package.json build to scripts/build.sh for Windows Bun compat (#1538, #1537, #1530, #1457, #1561) Bun's Windows shell parser rejects multiple constructs the inline package.json build chain used: brace groups `{ cmd; }`, subshells with redirection `( git ... ) > path/.version`, and (in Bun 1.3.x) subshells near redirections in general. Every Windows install + every auto-upgrade since v1.34.2.0 has failed on `bun run build`. Extracts the build chain to scripts/build.sh and the .version writes to scripts/write-version-files.sh. POSIX-portable, no Bun shell parsing involved. Also adds Windows-specific bun.exe handling for non-ASCII PATHs (a separate Windows footgun where Bun's --compile fails when the binary lives under a path with non-ASCII chars). Updates test/build-script-shell-compat.test.ts to assert the new shape: no subshells with redirections anywhere in the build chain, and build delegates to scripts/build.sh which delegates .version writes. Contributed by @Charlie-El via #1544. Supersedes #1531 (@scarson, fixed in build helper), #1480 (@mikepsinn, partial overlap), #1460 (@realcarsonterry, brace-group fix subsumed) — credit retained. Closes #1538, #1537, #1530, #1457, #1561. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(windows): .exe glob in .gitignore + .exe extension resolution in find-browse (#1554) bun build --compile on Windows appends .exe to the output filename, producing browse.exe instead of browse. find-browse's existsSync probe only checked the bare path and returned null on Windows even when the binary was correctly built. .gitignore similarly only excluded the bare bin/gstack-global-discover path, leaving the .exe variant tracked. This commit: - .gitignore: changes `bin/gstack-global-discover` → `bin/gstack-global-discover*` so the Windows .exe variant is ignored - browse/src/find-browse.ts: adds isExecutable + findExecutable helpers that fall back to .exe/.cmd/.bat probing on Windows, mirroring the same helper already in make-pdf/src/browseClient.ts and pdftotext.ts Contributed by @Mike-E-Log via #1554. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ci(windows): add fresh-install E2E gate that runs bun run build on windows-latest Adds .github/workflows/windows-setup-e2e.yml as the gate that catches Bun shell-parser regressions in the build chain before they reach users. Triggers on PRs touching package.json, scripts/build.sh, scripts/write-version-files.sh, setup, browse cli/find-browse, or gstack-paths. What it verifies: 1. bun run build completes on Windows (the previously-broken path that #1538/#1537/#1530/#1457/#1561 reported) 2. All compiled binaries land on disk (browse.exe, find-browse.exe, design.exe, gstack-global-discover.exe) 3. find-browse resolves to the .exe variant on Windows (regression gate for #1554) 4. gstack-paths returns non-empty GSTACK_STATE_ROOT/PLAN_ROOT/TMP_ROOT on Windows (regression gate for #1570) Complements the existing windows-free-tests.yml (curated unit subset); this new workflow exercises the install path itself. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(codex): move diff scope into prompt instead of --base (Codex CLI 0.130+ argv conflict) (#1209) Codex CLI ≥ 0.130.0 rejects passing a custom prompt and --base together (mutually exclusive at argv level). Every /codex review, /review, and /ship structured Codex review call ended with an argv error before the model ran. Fix: scope the diff in prompt text using "Run git diff origin/<base>...HEAD 2>/dev/null || git diff <base>...HEAD" instead of `--base <base>`. Preserves the filesystem boundary instruction across all invocations and keeps Codex's review prompt tuning. Touches: - codex/SKILL.md.tmpl + regenerated codex/SKILL.md - scripts/resolvers/review.ts + regenerated review/SKILL.md, ship/SKILL.md - test/gen-skill-docs.test.ts: new regression that fails if any of the five known files still contain the prompt+--base shape - test/skill-validation.test.ts: corresponding negative + positive pin on the rendered SKILL.md files Contributed by @jbetala7 via #1209. Closes #1479. Supersedes #1527 (@mvanhorn — same intent, different patch shape, CONFLICTING) and #1449 (@Gujiassh — broader refactor, CONFLICTING). Credit retained in CHANGELOG. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(review): diff from git merge-base, not git diff origin/<base> (#1492) git diff origin/<base> shows everything since the common ancestor in both directions — it includes commits that landed on origin/<base> after this branch was created as deletions. That made /review and /ship's pre-landing structured review report inflated diff totals and flagged "removed" code that was actually still present in the working tree. Fix: compute DIFF_BASE via git merge-base origin/<base> HEAD and diff the working tree against that point. Same coverage of uncommitted edits, no phantom deletions from out-of-order base advancement. Applies to /review's Step 1 (diff existence check), Step 3 (get the diff), the build-on-intent scope-creep check, the structured review DIFF_INS/DIFF_DEL stats, and the Claude adversarial subagent prompt. Same change flows into ship/SKILL.md via the shared resolver. Touches: - review/SKILL.md.tmpl + regenerated review/SKILL.md, ship/SKILL.md - scripts/resolvers/review.ts - scripts/resolvers/review-army.ts Contributed by @mvanhorn via #1492. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(codex): pin filesystem-boundary preservation across all codex review surfaces (#1503, #1522) #1503 reported that the bare codex review --base path stripped the filesystem boundary instruction, letting Codex spend tokens reading .claude/skills/ and agents/. #1522 proposed adding a skill-path detector that switched to the custom-instructions route when the diff touched skill files. After C10 (#1209) restructured codex review to always carry the boundary in the prompt (the prompt+--base argv conflict forced the restructure), the skill-path detector becomes redundant — every default call already preserves the boundary. This commit pins the post-#1209 invariant with a test that fails the build if any future refactor strips the boundary from codex/SKILL.md, review/SKILL.md, or ship/SKILL.md. Closes #1503 by regression test. #1522 (@genisis0x) is superseded by #1209 (the prompt rewrite covers its safety concern); credit retained in CHANGELOG. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(skills): use command -v instead of which for codex detection (#1197) `which` is not on PATH in every shell — some Windows shells, BusyBox- only containers, and minimal CI images all fail when skills probe codex availability via `which codex`. `command -v` is a POSIX builtin and always available where the skill is running. Touched: - codex/SKILL.md.tmpl: CODEX_BIN=$(command -v codex || echo "") - scripts/resolvers/review.ts and scripts/resolvers/design.ts: 3 + 3 sites each rewritten to `command -v codex >/dev/null 2>&1` - Regenerated all 10 affected SKILL.md files (codex, review, ship, design-consultation, design-review, office-hours, plan-ceo-review, plan-design-review, plan-devex-review, plan-eng-review) - test/skill-validation.test.ts: updated pin + defensive regression test that fails if `which codex` returns to codex/SKILL.md - test/skill-e2e-plan.test.ts: updated summary regex Contributed by @mvanhorn via #1197. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(codex): surface non-zero exits so wrappers stop reading as silent stalls (#1467, #1327) When codex exits non-zero (parse errors, arg-shape breaks, model API errors that propagate as non-zero status), the calling agent previously saw an empty output and burned 30-60 minutes misdiagnosing as a silent model/API stall. The hang-detection block only caught exit 124 (the timeout-wrapper signal). Adds elif blocks in all four codex invocation sites (Review default, Challenge, Consult new-session, Consult resume) that: - Echo "[codex exit N] <stderr first line>" to stdout - Indent the first 20 stderr lines for inline context - Log codex_nonzero_exit telemetry tagged with the call site Contributed by @genisis0x via #1467. Closes #1327. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(design): disclose OpenAI key source + warn on cwd .env match (#1278, closes #1248) The design binary previously called process.env.OPENAI_API_KEY without checking where the key came from. If a user ran $D inside someone else's project that had OPENAI_API_KEY in its .env, the resulting generation billed that project's account. Silent and irreversible. Fix: resolveApiKeyInfo() returns both the key and its source. When the env-var path matches an OPENAI_API_KEY entry in the current directory's .env, .env.<NODE_ENV>, or .env.local file, we set a warning. requireApiKey() prints "Using OpenAI key from <source>" plus the warning before the run — never the key itself. Adds 6 unit tests covering: config-vs-env precedence, env-only (no match), env+cwd .env match, quoted/exported values, value-mismatch (no false positive), and the no-leak invariant for requireApiKey stderr output. Contributed by @jbetala7 via #1278. Closes #1248. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(browse): guard full-page screenshots against Anthropic vision API >2000px brick (#1214) Full-page screenshots of tall pages routinely exceeded 2000px on the longest dimension, silently bricking the agent's session: the resulting base64 reached the Anthropic vision API which rejected the oversized image, leaving the agent burning turns on a useless blob with no stderr trace from the browse side. Adds browse/src/screenshot-size-guard.ts as a shared helper: - guardScreenshotBuffer(buf) → downscales in-memory if max(w,h) > 2000 - guardScreenshotPath(path) → file-mode variant that rewrites in place - Aspect ratio preserved via sharp's resize fit:inside - Stderr diagnostic on any downscale so callers can see when it fired - Lazy sharp import so non-screenshot paths pay no startup cost Wires the guard into all three full-page callsites codex review flagged: - browse/src/snapshot.ts: annotated + heatmap fullPage captures - browse/src/meta-commands.ts: screenshot command (path + base64 fullPage modes) plus the responsive 3-viewport sweep - browse/src/write-commands.ts: prettyscreenshot fullPage path Covers seven unit cases (pass-through, downscale, aspect ratio, exactly-2000px edge, file-mode rewrite) plus a static invariant test that fails the build if any of the three callsites stops importing the guard. Closes #1214. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(security): add Node sidecar entry for L4 prompt-injection classifier (#1370) The L4 TestSavant classifier in browse/src/security-classifier.ts can't be imported into the compiled browse server (onnxruntime-node dlopen fails from Bun's compile extract dir per CLAUDE.md). The agent that used to host it (sidebar-agent.ts) was removed when the PTY proved out — leaving the classifier file shipped but with zero callers. Exactly the gap codex flagged in #1370. Adds browse/src/security-sidecar-entry.ts: a Node script that runs the classifier as a subprocess of the browse server. It reads NDJSON requests from stdin and writes id-correlated NDJSON responses to stdout, supporting: - op: "scan-page-content" — full L4 classifier scan - op: "ping" — liveness probe for the client's health check - op: "status" — classifier readiness (used by /pty-inject-scan to surface l4 { available: bool } in its response) Plus browse/src/find-security-sidecar.ts: a resolver that locates node + the bundled JS entry (browse/dist/security-sidecar.js, built in a follow-up package.json change) or falls back to the dev TS entry. Returns null cleanly when node isn't on PATH so the calling endpoint can degrade per D7 (extension WARN + user confirm). C17 of the security-stack wave. C18 adds the IPC client + lifecycle management; C19 wires the endpoint; C20 routes the extension through it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(security): sidecar IPC client with lifecycle + circuit breaker (#1370) Adds browse/src/security-sidecar-client.ts to manage the Node L4 classifier subprocess from the compiled browse server: - Lazy spawn on first scan; reuses the same process across requests - Id-correlated request/response via NDJSON over stdio - 5s default per-scan timeout; 64KB payload cap (short-circuits before spawn so oversized requests don't waste a process) - 3-in-10-minutes respawn cap → trips circuit breaker; subsequent scans throw immediately so the /pty-inject-scan endpoint can surface l4 { available: false } to the extension and degrade to WARN+confirm - process.on('exit') sends SIGTERM to the child for clean teardown - isSidecarAvailable() lets the endpoint probe before scan calls so the response shape reflects degraded mode honestly Unit tests cover the payload cap, the availability probe, and the breaker-doesn't-crash invariant under repeated rejected calls. C18 of the security-stack wave. C19 adds POST /pty-inject-scan; C20 routes the extension through it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(security): add POST /pty-inject-scan endpoint for pre-PTY-inject scans (#1370) The sidebar's gstackInjectToTerminal callers (toolbar Cleanup, Inspector "Send to Code") were piping page-derived text directly into the live claude PTY with ZERO classifier processing — the gap codex flagged in #1370. The documented sidebar security stack had a hole the size of every Cleanup-button click. Adds POST /pty-inject-scan to browse/src/server.ts: - Local-only binding (NOT in TUNNEL_PATHS — tunnel attempts get the general 404 path; never reaches the scan logic) - Root-token auth via existing validateAuth() — 401 on unauth - 64KB request cap → 413 + payload-too-large body - 5s scan timeout via sidecar client - URL-blocklist forced to BLOCK in PTY context (page-derived REPL input is higher-risk than ordinary tool output) - L4 ML classifier via the sidecar when available; degrades to WARN per D7 when sidecar is unavailable - Response goes through JSON.stringify(..., sanitizeReplacer) per v1.38.0.0 Unicode-egress hardening - Imports only from security-sidecar-client.ts, never directly from security-classifier.ts (which would brick the compiled Bun binary) Seven static-invariant tests pin the POST verb, auth gate, 64KB cap, tunnel-listener exclusion, sanitizeReplacer wrapping, l4 availability shape, and the no-direct-classifier-import rule. C19 of the security-stack wave. C20 routes the extension through it; C21 adds the invariant AST check. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(extension): route gstackInjectToTerminal through /pty-inject-scan (#1370) Closes the documented-vs-shipped gap codex flagged in #1370. The sidebar's two PTY-injection call sites (Inspector "Send to Code" and toolbar Cleanup) now pre-scan via the new /pty-inject-scan endpoint before writing to the live claude REPL. Adds window.gstackScanForPTYInject(text, origin) to extension/sidepanel-terminal.js: - Async, returns { allow, verdict, reasons, l4 } - POST to /pty-inject-scan with the existing root-token auth - WARN+confirm on scan failure (network down, sidecar absent, etc.) rather than silent PASS — D7 honest-degradation gstackInjectToTerminal stays synchronous, returns boolean. Per D6: keeping the inject sync means existing `const ok = ...?.()` callers don't break, and the invariant test in test/extension-pty-inject-invariant.test.ts can statically pin that every call goes through the scan first. extension/sidepanel.js call sites updated: - inspectorSendBtn click → await scan, BLOCK drops + WARN prompts via window.confirm, PASS injects silently - runCleanup() → same flow. Static cleanup prompt always PASSes but still routes through scan to honor the invariant. C20 of the security-stack wave. C21 adds the static invariant test. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(security): invariant — extension PTY inject must be scan-gated (#1370) Static-analysis invariant test that fails the build if any extension/*.js path calls window.gstackInjectToTerminal without a preceding window.gstackScanForPTYInject in the same enclosing function. Closes the documented-vs-shipped gap codex demanded a machine check on. Rules: - Rule 1: any file that calls inject must also reference scan - Rule 2: in the enclosing function (function declaration, arrow, async (), event handler), a scan call must appear before the inject call by source position - Exemption: sidepanel-terminal.js (the file that DEFINES the inject function) is exempt from Rule 2 since the definition is not a call Plus two structural checks: - sidepanel-terminal.js defines both the inject and scan functions - inject stays SYNCHRONOUS (no `async` modifier) per D6 — async would silently break the `const ok = ...?.()` pattern at every caller C21 of the security-stack wave. The sidecar architecture (#1370) is complete: server-side L1-L3 + L4-via-sidecar (C17+C18+C19), extension pre-scan wiring (C20), and now the regression gate (C21). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(browse): opt-in extended stealth mode with 6 detection-vector patches (#1112) Rebases @garrytan's PR #1112 (Apr 2026, abandoned) onto the current browse/src/stealth.ts contract. The existing minimal "codex narrowed" stealth (webdriver-mask + AutomationControlled launch arg) stays the default. PR #1112's six additional patches are added behind an opt-in GSTACK_STEALTH=extended env flag. Extended-mode patches (applied AFTER the default mask, in order): 1. delete navigator.webdriver from prototype (not just the getter — detectors check `"webdriver" in navigator`) 2. WebGL renderer spoof to Apple M1 Pro (SwiftShader was the #1 software-GPU tell in containers) 3. navigator.plugins returns a PluginArray-prototype-passing array with MimeType objects and namedItem() 4. window.chrome populated with chrome.app, chrome.runtime, chrome.loadTimes(), chrome.csi() with realistic shapes 5. navigator.mediaDevices backfilled when headless drops it 6. CDP cdc_*-prefixed window globals cleared Why opt-in: the default mode's contract is fingerprint CONSISTENCY, which protects against detectors that flag spoofing mismatch. Extended mode actively lies about the environment; sites that reflect on these properties can break. Users who hit detection in default mode can flip GSTACK_STEALTH=extended for SannySoft 100% pass-rate. Twenty unit tests pin the env-flag semantics, all six patches' code presence, and the applyStealth wiring order. Live SannySoft pass-rate verification stays in the periodic-tier E2E suite. Contributed by @garrytan via #1112 (rebased — original PR opened before the codex-narrowed minimum landed; rebase preserves the narrowed default while adding the SannySoft-passing path as opt-in). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(fixtures): regenerate ship-SKILL.md golden baselines after C10-C13 + C16 templates Updates the three ship-SKILL.md golden baselines (claude, codex, factory hosts) to match the new shape produced by: - C10 #1209 codex argv (prompt + diff scope, no --base) - C11 #1492 merge-base diff (DIFF_BASE= preamble) - C13 #1197 command -v for codex detection - C12 + boundary preservation per regen-enforcing test Per CLAUDE.md SKILL.md workflow: edit the .tmpl, run gen:skill-docs, commit the regenerated outputs together. Goldens are part of the regen contract — without this commit, test/host-config.test.ts' golden-baseline checks fail with the diff codex review surfaced. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(release): v1.41.0.0 — Daegu wave (24 bisect commits, 14 user-facing fixes) Bumps VERSION 1.40.0.0 → 1.41.0.0. CHANGELOG entry follows the release-summary format in CLAUDE.md: two-line headline, lead paragraph, "The numbers that matter" table, "What this means for builders" closer, then itemized Added/Changed/Fixed/For contributors with inline credit to every PR author and original issue reporter. Scale-aware bump per CLAUDE.md: 24 commits, ~6000 LOC net, substantial new capability across security (PTY sidecar wiring), install (Windows build chain), compat (gbrain 0.18-0.35, Codex CLI 0.130+), and quality (screenshot guard, design key disclosure, extended stealth opt-in). MINOR is the right call. Closes for users: #1567, #1559, #1569, #1346, #1418, #1538, #1537, #1530, #1457, #1561, #1554, #1479, #1503, #1248, #1214, #1370, #1327, #1193 pattern, #1152 pattern. Credit retained inline. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(find-browse): resolve source-checkout layout <git-root>/browse/dist/browse[.exe] windows-setup-e2e.yml runs `bun browse/src/find-browse.ts` against a freshly-built repo where binaries land at browse/dist/browse.exe (no .claude/skills/gstack/ install layout). The previous markers chain only matched .codex/.agents/.claude prefixed paths, so find-browse exited "not found" even when the binary was present. Adds a source-checkout fallback after the marker scan: if no installed layout resolves but <git-root>/browse/dist/browse[.exe] exists, return that. Three real callers hit this path: - gstack repo dev workflow before `./setup` runs - windows-setup-e2e.yml CI (the breakage that surfaced this) - make-pdf consumers running from a sibling source checkout Smoke-verified: a fresh git repo with browse/dist/browse on disk now resolves through the source-checkout branch (was returning null before this commit). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(release): bump v1.41.0.0 → v1.42.0.0 to clear queue collision with #1574 The version-gate workflow flagged a collision: PR #1574 (garrytan/colombo-v3) already claims v1.41.0.0, and #1592 (fix/audit-critical-high-bugs) claims v1.41.1.0. Per CLAUDE.md's workspace-aware ship rule, queue-advancing past a claimed version within the same bump level is permitted — MINOR work landing on top of a queued MINOR still reads as MINOR relative to main. Util's suggested next slot is v1.42.0.0; taking it. CHANGELOG entry header bumped + dated 2026-05-19; entry body unchanged (same wave content, same credit list). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
28 KiB
Using GBrain with GStack
Your coding agent, with a memory it actually keeps.
GBrain is a persistent knowledge base designed for AI agents. It stores what your agent learns, what you've decided, what worked and what didn't, and lets the agent search all of it on demand. GStack gives you a one-command path from zero to "gbrain is running, and my agent can call it" — with paths for try-it-local, share-with-your-team, and everything between.
This is the full monty: every scenario, every flag, every helper bin, every troubleshooting step. For the quick pitch, see the README's GBrain section. For error codes and sync-specific issues, see docs/gbrain-sync.md.
The one-command install
/setup-gbrain
That's it. The skill detects your current state, asks three questions at most, and walks you through install, init, MCP registration for Claude Code, and per-repo trust policy. On a clean Mac with nothing installed it finishes in under five minutes. On a Mac where something's already set up it takes seconds (it detects the existing state and skips done work).
What you get after setup
Once /setup-gbrain finishes, your coding agent has two retrieval surfaces it didn't have before:
- Semantic code search across this repo.
gbrain search "browser security canary"returns ranked file regions, not exact-match grep hits.gbrain code-def,code-refs,code-callers,code-calleeswalk the call graph by symbol — useful when you don't know which file holds the implementation but you know what it does. The agent prefers these over Grep when the question is semantic; CLAUDE.md gets a## GBrain Search Guidanceblock that teaches it the routing rules. - Cross-session memory. Plans, retros, decisions, and learnings from past sessions live in
~/.gstack/and (if you opted in to artifacts sync) get pushed to a private git repo that gbrain indexes.gbrain search "what did we decide about auth?"actually finds the prior CEO plan instead of you re-describing context every session.
If you also enabled remote MCP (Path 4 below), brain queries route to a shared brain server that other machines can write to — your laptop, your desktop, and a teammate's machine all see the same memory.
The four paths
You pick one when the skill asks "Where should your brain live?"
Path 1: Supabase, you already have a connection string
Best for: you (or a teammate's cloud agent) already provisioned a Supabase brain and you want this local machine to use the same data.
What happens: Paste the Session Pooler URL (Settings → Database → Connection Pooler → Session → copy URI, port 6543). The skill reads it with echo off, shows you a redacted preview (aws-0-us-east-1.pooler.supabase.com:6543/postgres — host visible, password masked), hands it to gbrain init via the GBRAIN_DATABASE_URL environment variable, and the URL is never written to argv or your shell history.
Trust warning: Pasting this URL gives your local Claude Code full read/write access to every page in the shared brain. If that's not the trust level you want, pick PGLite local (Path 3) instead and accept the brains are disjoint.
Path 2a: Supabase, auto-provision a new project
Best for: fresh Supabase account, you want a clean new project with zero clicking.
What happens: You paste a Supabase Personal Access Token (PAT). The skill shows you the scope disclosure first — the token grants full access to every project in your Supabase account, not just the one we're about to create. It lists your organizations, asks which one and which region (default us-east-1), generates a database password, calls POST /v1/projects, polls GET /v1/projects/{ref} every 5 seconds until the project is ACTIVE_HEALTHY (180s timeout), fetches the pooler URL, hands it to gbrain init. End-to-end: ~90 seconds.
At the end: explicit reminder to revoke the PAT at https://supabase.com/dashboard/account/tokens. The skill already discarded it from memory.
If you Ctrl-C mid-provision: The SIGINT trap prints your in-flight project ref + a resume command. You can delete the orphan at the Supabase dashboard, or run /setup-gbrain --resume-provision <ref> to pick up where you left off.
Path 2b: Supabase, create manually
Best for: you'd rather click through supabase.com yourself than paste a PAT.
What happens: The skill walks you through the four manual steps (signup → new project → wait ~2 min → copy Session Pooler URL), then takes over from Path 1's paste step. Same security treatment as Path 1.
Path 3: PGLite local
Best for: try-it-first, no account, no cloud, no sharing. Or a dedicated "this Mac's brain" that stays isolated from any cloud agent.
What happens: gbrain init --pglite. Brain lives at ~/.gbrain/brain.pglite. No network calls. Done in 30 seconds.
This is the best first choice if you just want to see what gbrain feels like before committing to cloud. You can always migrate later with /setup-gbrain --switch.
Path 4: Remote gbrain MCP (split-engine)
Best for: your brain runs on another machine you control (Tailscale, ngrok, internal LAN) or a teammate's server. You want the cross-machine memory benefit without standing up a local database, and you still want symbol-aware code search on this Mac.
What happens: You paste an MCP URL (e.g. https://wintermute.tail554574.ts.net:3131/mcp) and a bearer token. The skill verifies the URL over the wire, registers gbrain as an HTTP MCP in ~/.claude.json at user scope, and offers to also stand up a tiny local PGLite for code search (~30 seconds, ~120 MB disk).
If you accept the local PGLite, you end up in split-engine mode:
- Brain/context queries (
mcp__gbrain__search,mcp__gbrain__query,mcp__gbrain__get_page) route to the remote MCP. Plans, retros, learnings, cross-machine memory — all on the shared server. - Code queries (
gbrain code-def,code-refs,code-callers,code-callees,gbrain searchfor code) route to the local PGLite via the.gbrain-sourcepin in each worktree. Indexed locally, fast, never leaves the machine.
The two engines are independent. Wiping the local PGLite doesn't touch the remote brain; rotating the remote MCP bearer doesn't affect local code search. This is also the right configuration if your remote brain admin can't (or shouldn't) index every developer's checkout — local code stays local.
MCP registration for Claude Code
By default the skill asks "Give Claude Code a typed tool surface for gbrain?" If you say yes, it runs:
claude mcp add gbrain -- gbrain serve
That registers gbrain's stdio MCP server with Claude Code. Now gbrain search, gbrain put, gbrain get, etc. show up as first-class tools in every session, not bash shell-outs.
If claude is not on PATH, the skill skips MCP registration gracefully with a manual-register hint. The CLI resolver still works from any skill that shells out to gbrain — MCP is an upgrade, not a prerequisite.
Other local agents (Cursor, Codex CLI, etc.) need their own MCP registration. The skill is Claude-Code-targeted for v1; other hosts can register gbrain serve manually in their own MCP config.
Per-remote trust policy (the triad)
Every repo on your machine gets a policy decision: read-write, read-only, or deny.
- read-write — your agent can
gbrain searchfrom this repo's context AND write new pages back to the brain. Default for your own projects. - read-only — your agent can search the brain but never writes new pages from this repo's sessions. Ideal for multi-client consultants: search the shared brain, don't contaminate it with Client A's code while you're in Client B's repo.
- deny — no gbrain interaction at all. The repo is invisible to gbrain tooling.
The skill asks once per repo the first time you run a gstack skill there. After that the decision is sticky — every worktree + branch of the same git remote shares the same policy, so you set it once and it follows you.
SSH and HTTPS remote variants collapse to the same key: https://github.com/foo/bar.git and git@github.com:foo/bar.git are the same repo.
To change a policy:
/setup-gbrain --repo # re-prompt for this repo only
# Or directly:
~/.claude/skills/gstack/bin/gstack-gbrain-repo-policy set "github.com/foo/bar" read-only
To see every policy:
~/.claude/skills/gstack/bin/gstack-gbrain-repo-policy list
Storage: ~/.gstack/gbrain-repo-policy.json, mode 0600, schema-versioned so future migrations stay deterministic.
Keeping the brain current with /sync-gbrain
/setup-gbrain is one-time onboarding. /sync-gbrain is the verb you run every time you want gbrain to see fresh changes in this repo's code.
/sync-gbrain # incremental: mtime fast-path, ~seconds on a clean tree
/sync-gbrain --full # full reindex (~25-35 minutes on a big Mac)
/sync-gbrain --code-only # only the code stage; skip memory + brain-sync
/sync-gbrain --dry-run # preview what would sync; no writes
The skill runs three stages — code, memory, brain-sync — independently. A failure in one doesn't block the others. State persists to ~/.gstack/.gbrain-sync-state.json so re-running picks up cleanly.
What it does on a fresh worktree:
- Pre-flight. Checks
gbrain_local_status(the local engine's health). If the engine isbroken-dborbroken-config, the skill STOPs with a remediation menu — it refuses to silently degrade. If the local engine is missing and you're in remote-MCP mode (Path 4), the code stage SKIPs cleanly and only brain-sync runs. - Code stage. Registers the cwd as a federated source via
gbrain sources add, writes a.gbrain-sourcepin file in the repo root (kubectl-style context — every worktree gets its own pin, so Conductor sibling worktrees don't collide), runsgbrain sync --strategy code. - Memory stage. Stages your
~/.gstack/transcripts + curated memory. In local-stdio MCP mode, ingests into the local engine. In remote-http MCP mode, persists staged markdown to~/.gstack/transcripts/run-<pid>-<ts>/for the remote brain admin's pull pipeline. - Brain-sync stage. Pushes curated artifacts (plans, designs, retros) to your private artifacts repo if you have one configured.
- CLAUDE.md guidance. Capability-checks the round-trip (write a page → search → find it). If green, writes the
## GBrain Search Guidanceblock to your project's CLAUDE.md. If red, REMOVES the block — the agent should never be told to use a tool that isn't installed.
The watermark. Sync state advances by commit hash. If gbrain hits a file it can't index (5 MB hard limit per file, or a file vanished mid-sync), the watermark stays put and subsequent syncs retry. To acknowledge an unfixable failure and move past it:
gbrain sync --source <source-id> --skip-failed
Re-runnable, idempotent, safe to run from multiple terminals on the same machine (locked at ~/.gstack/.sync-gbrain.lock).
Switching engines later
Picked PGLite and now want to join a team brain? One command:
/setup-gbrain --switch
The skill runs gbrain migrate --to supabase --url "$URL" wrapped in timeout 180s. Migration is bidirectional (Supabase → PGLite also works) and lossless — pages, chunks, embeddings, links, tags, and timeline all copy. Your original brain is preserved as a backup.
If migration hangs: another gstack session may be holding a lock on the source brain. The timeout fires at 3 minutes with an actionable message. Close other workspaces and re-run.
GStack memory sync (a separate concern)
This is different from gbrain itself. Your gstack state (~/.gstack/ — learnings, plans, retros, timeline, developer profile) is machine-local by default. "GStack memory sync" optionally pushes a curated, secret-scanned subset to a private git repo so your memory follows you across machines — and, if you're running gbrain, that git repo becomes indexable there too.
Turn it on with:
gstack-brain-init
You'll get a one-time privacy prompt: everything allowlisted / artifacts only (plans, designs, retros, learnings — skip behavioral data like timelines) / off. Every skill run syncs the queue at start and end — no daemon, no background process.
Secret-shaped content (AWS keys, GitHub tokens, PEM blocks, JWTs, bearer tokens) is blocked from sync before it leaves your machine.
On a new machine: Copy ~/.gstack-brain-remote.txt over, run gstack-brain-restore, and yesterday's learnings surface on today's laptop.
Full guide: docs/gbrain-sync.md. Error index: docs/gbrain-sync-errors.md.
/setup-gbrain offers to wire this up for you at the end of initial setup — it's one more AskUserQuestion, and it integrates with the same private-repo infrastructure.
Cleanup orphan projects
If you Ctrl-C'd mid-provision, tried three different names before settling on one, or otherwise accumulated gbrain-shaped Supabase projects you don't use, there's a subcommand for that:
/setup-gbrain --cleanup-orphans
The skill re-collects a PAT (one-time, discarded after), lists every project in your Supabase account whose name starts with gbrain and whose ref doesn't match your active ~/.gbrain/config.json pooler URL. For each orphan it asks per-project: "Delete orphan project <ref> (<name>, created <date>)?" — no batching, no "delete all" shortcut. The active brain is never offered for deletion.
Command + flag reference
/setup-gbrain entry modes
| Invocation | What it does |
|---|---|
/setup-gbrain |
Full flow: detect state, pick path, install, init, MCP, policy, optional memory-sync |
/setup-gbrain --repo |
Flip the per-remote trust policy for the current repo only |
/setup-gbrain --switch |
Migrate engine (PGLite ↔ Supabase) without re-running the other steps |
/setup-gbrain --resume-provision <ref> |
Resume a path-2a auto-provision that was interrupted during polling |
/setup-gbrain --cleanup-orphans |
List + per-project delete of orphan Supabase projects |
Bin helpers (for scripting)
| Bin | Purpose |
|---|---|
gstack-gbrain-detect |
Emit current state as JSON: gbrain on PATH, version, config engine, doctor status, sync mode |
gstack-gbrain-install |
Detect-first installer (probes ~/git/gbrain, ~/gbrain, then fresh clone). Has --dry-run and --validate-only flags. PATH-shadow check exits 3 with remediation menu. |
gstack-gbrain-lib.sh |
Sourced, not executed. Provides read_secret_to_env VARNAME "prompt" [--echo-redacted "<sed-expr>"] |
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)
Gbrain itself ships with these that gstack wraps:
| Command | Purpose |
|---|---|
gbrain init --pglite |
Initialize a local PGLite brain |
gbrain init --non-interactive |
Initialize via env (GBRAIN_DATABASE_URL or DATABASE_URL). Never pass a URL as argv — it'll leak to shell history. |
gbrain doctor --json |
Health check. Returns `{status: "ok" |
gbrain migrate --to supabase --url ... |
Move a PGLite brain to Supabase (lossless, preserves source as backup) |
gbrain migrate --to pglite |
Reverse migration |
gbrain search "query" |
Search the brain |
gbrain put "<slug>" --content "<markdown-with-frontmatter>" |
Write a page (title/tags go in YAML frontmatter inside --content) |
gbrain get "<slug>" |
Fetch a page |
gbrain serve |
Start the MCP stdio server (used by claude mcp add) |
Config files + state
| Path | What lives there |
|---|---|
~/.gbrain/config.json |
Engine (pglite/postgres), database URL or path, API keys. Mode 0600. Written by gbrain init. |
~/.gstack/gbrain-repo-policy.json |
Per-remote trust triad. Schema v2. Mode 0600. |
~/.gstack/.setup-gbrain.lock.d |
Concurrent-run lock (atomic mkdir). Released on normal exit + SIGINT. |
~/.gstack/.brain-queue.jsonl |
Pending sync entries for gstack memory sync |
~/.gstack/.brain-last-push |
Timestamp of last sync push (for /health scoring) |
~/.gstack-brain-remote.txt |
URL of your gstack memory sync remote (safe to copy between machines) |
~/.gstack/.setup-gbrain-inflight.json |
Reserved for future --resume-provision persisted state |
Environment variables
| Var | Where it's read | What it does |
|---|---|---|
SUPABASE_ACCESS_TOKEN |
gstack-gbrain-supabase-provision |
PAT for Management API calls. Discarded after each setup run. |
DB_PASS |
gstack-gbrain-supabase-provision (create, pooler-url) |
Generated DB password. Never in argv. |
GBRAIN_DATABASE_URL |
gbrain init, gbrain doctor, etc. |
Postgres connection string (Supabase pooler URL for us). Env takes precedence over ~/.gbrain/config.json. |
DATABASE_URL |
gbrain init (fallback) |
Same semantics as GBRAIN_DATABASE_URL; checked second. |
SUPABASE_API_BASE |
gstack-gbrain-supabase-provision |
Override the Management API host. Used by tests to point at a mock server. |
GBRAIN_INSTALL_DIR |
gstack-gbrain-install |
Override default install path (~/gbrain) |
GSTACK_HOME |
every bin helper | Override ~/.gstack state dir. Heavy test use. |
OPENAI_API_KEY |
gbrain embed subprocess |
Required for embeddings during gbrain sync / /sync-gbrain. Without it, pages are imported structurally (symbol tables, chunks) but semantic search degrades — you'll see [gbrain] embedding failed for code file ... OpenAI embedding requires OPENAI_API_KEY in the sync log. |
ANTHROPIC_API_KEY |
claude-agent-sdk, paid evals |
Required for bun run test:evals and any direct query() call against Claude. |
GSTACK_OPENAI_API_KEY |
lib/conductor-env-shim.ts |
Conductor-injected fallback. Promoted to OPENAI_API_KEY when the canonical name is empty. |
GSTACK_ANTHROPIC_API_KEY |
lib/conductor-env-shim.ts |
Same pattern as above for Anthropic. |
Conductor + GSTACK_* env vars
If you run gstack inside a Conductor workspace, Conductor explicitly strips ANTHROPIC_API_KEY and OPENAI_API_KEY from the workspace env. Setting them in ~/.zshrc or .env won't help — the strip happens after env inheritance. To get a usable API key into a workspace, set GSTACK_ANTHROPIC_API_KEY and GSTACK_OPENAI_API_KEY in Conductor's workspace env config instead. Conductor passes those through untouched.
lib/conductor-env-shim.ts bridges the gap on the gstack side: when imported as a side effect (import "../lib/conductor-env-shim";), it promotes GSTACK_FOO_API_KEY to FOO_API_KEY for any subprocess that doesn't see the canonical name. The shim is already wired into:
bin/gstack-gbrain-sync.ts— so/sync-gbrainpicks up OpenAI for embeddingsbin/gstack-model-benchmark— so--judgeruns work without manual env mappingscripts/preflight-agent-sdk.ts— so paid-eval auth probes worktest/helpers/e2e-helpers.ts— sobun run test:evalsfinds Anthropic
If you add a new TS entry point that hits a paid API or needs gbrain embeddings, add the same one-line import at the top. See CONTRIBUTING.md "Conductor workspaces" for the contributor checklist.
bin/gstack-codex-probe is bash and doesn't read these directly — it relies on ~/.codex/ auth managed by the Codex CLI.
Security model
One rule for every secret this skill touches: env var only, never argv, never logged, never written to disk by us. The only persistent storage is gbrain's own ~/.gbrain/config.json at mode 0600, which is gbrain's discipline, not ours.
Enforced in code:
- CI grep test in
test/skill-validation.test.tsfails the build if$SUPABASE_ACCESS_TOKENor$GBRAIN_DATABASE_URLappears in an argv position - CI grep test fails if
--insecure,-k, orNODE_TLS_REJECT_UNAUTHORIZED=0appear inbin/gstack-gbrain-supabase-provision set +xat the top of the provision helper prevents debug tracing from leaking PAT- Telemetry payload contains only enumerated categorical values (scenario, install result, MCP opt-in, trust tier) — never free-form strings that could contain secrets
Enforced via tests:
test/secret-sink-harness.test.tsruns every secret-handling bin with a seeded secret and asserts the seed never appears in any captured channel (stdout, stderr, files under$HOME, telemetry JSONL). Four match rules per seed: exact, URL-decoded, first-12-char prefix, base64.- Positive controls in the same test file deliberately leak seeds in every covered channel and assert the harness catches each one. Without the positive controls, a harness that silently under-reports would look identical to a working harness.
What you can still leak (the honest limits of v1):
- If you paste a secret into a normal chat message outside
read -s, it's in the conversation transcript and any host-side logging - The leak harness doesn't dump subprocess environment — a bin that
env >> ~/.logwould evade detection (no bin in v1 does this; grep tests prevent it) - Your shell's own
HISTFILEbehavior is your shell's, not ours — we never pass secrets to argv so they don't land there via our code, but nothing stops you from pasting one into a rawcurlcommand yourself
Troubleshooting
"PATH SHADOWING DETECTED" during install
Another gbrain binary is earlier in PATH than the one the installer just linked. The installer's version check caught it. Fix one of:
rm $(which gbrain)if you don't need the other one- Prepend
~/.bun/binto PATH in your shell rc so the linked binary wins - Set
GBRAIN_INSTALL_DIRto the shadowing binary's install directory and re-run
Then re-run /setup-gbrain.
"rejected direct-connection URL"
You pasted a db.<ref>.supabase.co:5432 URL. Those are IPv6-only and fail in most environments. Use the Session Pooler URL instead: Supabase dashboard → Settings → Database → Connection Pooler → Session → copy URI (port 6543).
Auto-provision times out at 180s
The Supabase project is still initializing. Your ref was printed in the exit message. Wait a minute, then:
/setup-gbrain --resume-provision <ref>
The skill re-collects a PAT, skips project creation, resumes polling.
"Another /setup-gbrain instance is running"
You have a stale lock directory. If you're sure no other instance is actually running:
rm -rf ~/.gstack/.setup-gbrain.lock.d
Then re-run.
"No cross-model tension" on policy file
You edited ~/.gstack/gbrain-repo-policy.json by hand with legacy allow values? No problem. On the next read, gstack auto-migrates allow → read-write and adds _schema_version: 2. One log line on stderr, idempotent, deterministic.
gbrain doctor says "warnings"
/health treats that as yellow, not red. Check gbrain doctor --json | jq .checks to see which sub-checks are warning. Typical causes: resolver MECE overlap (skill names clashing) or DB connection not yet configured.
/sync-gbrain reports OK but gbrain search returns nothing semantic
Embeddings probably failed during import. Symbol queries (code-def, code-refs) still work because they don't need embeddings, but gbrain search "<terms>" falls back to a degraded BM25 path. Look in the sync output for lines like:
[gbrain] embedding failed for code file <name>: OpenAI embedding requires OPENAI_API_KEY
The fix is to put OPENAI_API_KEY in the process env before re-running. On a bare Mac shell, source it from ~/.zshrc before calling. In Conductor, set GSTACK_OPENAI_API_KEY at the workspace level — lib/conductor-env-shim.ts promotes it to canonical automatically when imported. Re-run /sync-gbrain --code-only to backfill embeddings on already-imported pages.
gbrain sync blocked at a commit hash — FILE_TOO_LARGE
A file in your tree exceeds gbrain's 5 MB hard limit (MAX_FILE_SIZE in gbrain/src/core/import-file.ts). Common culprits: response replay caches, captured screenshots, large JSON fixtures. Gbrain doesn't honor .gitignore-style exclude lists for code sync; the only knob is acknowledging the failure:
gbrain sync --source <source-id> --skip-failed
Watermark advances past the offending commit. The same file fails again if it changes; re-skip when that happens.
Switching PGLite → Supabase hangs
Another gstack session in a sibling Conductor workspace may be holding a lock on your local PGLite file via its preamble's gstack-brain-sync call. Close other workspaces, re-run /setup-gbrain --switch. The timeout is bounded at 180s so you'll never actually wait forever.
Why this design
Why per-remote trust triad and not binary allow/deny? Multi-client consultants need search without write-back. A freelance dev working on Client A in the morning and Client B in the afternoon can't let A's code insights leak into a brain Client B can search. Read-only solves that cleanly.
Why not bundle gbrain into gstack? Gbrain is a separate, actively-developed project with its own release cadence, schema migrations, and MCP surface. Bundling would mean gstack has to gate gbrain updates, which slows gbrain improvements from reaching users. Separate-but-integrated lets each ship on its own cadence.
Why gbrain init --non-interactive via env var and not a flag? Connection strings contain database passwords. Passing them as argv lands the password in ps, shell history, and process listings. Env-var handoff keeps the secret in process memory only. Gbrain supports both GBRAIN_DATABASE_URL and DATABASE_URL; we use the former to avoid collisions with non-gbrain tooling.
Why fail-hard on PATH shadowing instead of warn-and-continue? A shadowed gbrain means every subsequent command calls a different binary than the one we just installed. That's a silent version-drift bug that surfaces as mysterious feature gaps weeks later. Setup skills have one job — set up a working environment. Refusing to install into a broken one is the setup-skill-correct behavior.
Why not auto-import every repo? Privacy + noise. An auto-import preamble hook that ingests every repo you touch would: (a) leak work code into a shared brain without consent, and (b) clog search with throwaway repos. The per-remote policy makes ingestion an explicit, per-repo decision. /setup-gbrain doesn't install any auto-import hook today — but the policy store is forward-compatible for one later.
Related skills + next steps
/health— includes a GBrain dimension (doctor status, sync queue depth, last-push age) in its 0-10 composite score. The dimension is omitted when gbrain isn't installed; running/healthon a non-gbrain machine doesn't penalize that choice./gstack-upgrade— keeps gstack itself up to date. Does NOT upgrade gbrain independently. To bump gbrain, updatePINNED_COMMITinbin/gstack-gbrain-installand re-run/setup-gbrain./retro— weekly retrospective pulls learnings and plans from your gbrain when memory sync is on, letting the retro reference cross-machine history.
Run /setup-gbrain and see what sticks.