v1.39.2.0 feat: GSTACK_* env-shim for Conductor + gbrain/gstack setup docs (#1534)

* feat: GSTACK_* env-key shim for Conductor workspaces

New lib/conductor-env-shim.ts promotes GSTACK_ANTHROPIC_API_KEY and
GSTACK_OPENAI_API_KEY to canonical names when canonical is empty. Wired
into the four TS entry points that hit paid APIs or gbrain embeddings:
gstack-gbrain-sync.ts, gstack-model-benchmark, preflight-agent-sdk.ts,
test/helpers/e2e-helpers.ts. Side-effect-only import, 15 lines total.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: gbrain+gstack setup, Conductor env mapping (v1.39.2.0)

USING_GBRAIN_WITH_GSTACK.md: new "What you get after setup" section,
Path 4 (remote MCP / split-engine), /sync-gbrain workflow stages +
watermark mechanics, "Conductor + GSTACK_* env vars" section, env vars
table extended, two troubleshooting entries (silent embedding failure
and FILE_TOO_LARGE watermark block).

CONTRIBUTING.md "Conductor workspaces": new paragraph on the GSTACK_*
prefix pattern and the four entry points importing the shim.

VERSION 1.39.1.0 → 1.39.2.0 and CHANGELOG entry covering the shim +
docs (full release-summary format with before/after table).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: unit coverage for conductor-env-shim

Refactor lib/conductor-env-shim.ts to export promoteConductorEnv()
so unit tests can manipulate env and call it directly (a bare side-
effect IIFE on import isn't reachable from bun:test once cached).
The on-import IIFE still runs — existing four-entry-point imports
keep working unchanged.

test/conductor-env-shim.test.ts covers all three branches:
GSTACK_FOO present + FOO empty → promotion; FOO already set →
no-overwrite; nothing in env → no-op.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: Conductor strips canonical API keys (not just "doesn't inherit")

The prior docs framed the GSTACK_* prefix as collision-avoidance:
"Conductor exposes API keys under a GSTACK_ prefix so it never
collides with whatever the host system has set." That understates
the mechanism — Conductor actively strips ANTHROPIC_API_KEY and
OPENAI_API_KEY from every workspace's process env, so setting them
in ~/.zshrc or .env doesn't help. The fix path is to set the
GSTACK_-prefixed forms in Conductor's workspace env config; Conductor
passes those through untouched.

Three docs updated to reflect the strip, not the polite framing:
USING_GBRAIN_WITH_GSTACK.md (Conductor section), CONTRIBUTING.md
(Conductor workspaces paragraph), CHANGELOG.md (release summary).

README.md gains a "Running gstack in Conductor?" callout in the
GBrain section pointing at the canonical doc's anchor, plus a fourth
path entry (remote gbrain MCP / split-engine) that was already
documented in USING_GBRAIN but missing from the README summary.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [1.39.2.0] - 2026-05-15
+
+## **Conductor workspaces wire `GSTACK_*` keys straight into gbrain embeddings and paid evals.**
+## **No more sourcing keys from your shell before every paid run.**
+
+Conductor explicitly strips `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from every workspace's process env, so `.env` copies and `~/.zshrc` exports never reach gbrain's embedding pipeline or `@anthropic-ai/claude-agent-sdk`. The fix path is `GSTACK_ANTHROPIC_API_KEY` / `GSTACK_OPENAI_API_KEY` — Conductor passes those through untouched. The new `lib/conductor-env-shim.ts` closes the loop on the gstack side: it promotes the prefixed form to canonical when canonical is empty. Four TS entry points import the shim as a side effect (`gstack-gbrain-sync.ts`, `gstack-model-benchmark`, `preflight-agent-sdk.ts`, `e2e-helpers.ts`). `README.md`, `USING_GBRAIN_WITH_GSTACK.md`, and `CONTRIBUTING.md` document the pattern, plus the checklist for adding the import to new entry points.
+
+### The numbers that matter
+
+Source: working-tree verification before commit. Three observable scenarios in a fresh Conductor workspace with only `GSTACK_OPENAI_API_KEY` and `GSTACK_ANTHROPIC_API_KEY` in env.
+
+| Surface | Before | After |
+|---|---|---|
+| `/sync-gbrain` embeddings | 50+ lines of `[gbrain] embedding failed for code file ...: OpenAI embedding requires OPENAI_API_KEY`; pages indexed structurally but semantic search degrades to BM25 | 3294 chunks embedded; `gbrain search "browser security canary token"` returns ranked code regions at 0.95 top score |
+| `bun run test:evals` | `ANTHROPIC_API_KEY not set, judge requires Anthropic access` from `test/helpers/benchmark-judge.ts:15` before any test runs | Shim promotes at module import; paid evals proceed normally |
+| Adding a new paid-API entry point | Manual env mapping every invocation, or every new entry point ships broken inside Conductor | One import line: `import "../lib/conductor-env-shim";` at the top of the file |
+
+### What this means for Conductor users
+
+If you run gstack inside Conductor, `/sync-gbrain` embeddings, paid evals, and the agent SDK just work without sourcing keys from your shell. The shim is 15 lines, side-effect-only, and the import is one line per consumer. The new "Conductor + GSTACK_* env vars" section in `USING_GBRAIN_WITH_GSTACK.md` and the updated "Conductor workspaces" block in `CONTRIBUTING.md` cover the pattern so you don't have to reverse-engineer it from a stack trace.
+
+### Itemized changes
+
+#### Added
+
+- `lib/conductor-env-shim.ts` (new, 15 lines) — side-effect IIFE that promotes `GSTACK_FOO_API_KEY` to `FOO_API_KEY` when the canonical name is empty. Currently covers `ANTHROPIC_API_KEY` and `OPENAI_API_KEY`.
+- `USING_GBRAIN_WITH_GSTACK.md` "What you get after setup" section — semantic code search + cross-session memory framed as concrete capabilities.
+- `USING_GBRAIN_WITH_GSTACK.md` Path 4 (remote gbrain MCP / split-engine) section — covers brain-via-remote-MCP + code-via-local-PGLite, the two engines being independent, when to pick this path.
+- `USING_GBRAIN_WITH_GSTACK.md` `/sync-gbrain` workflow section — three stages (code, memory, brain-sync), pre-flight gating on local engine health, watermark + `--skip-failed` mechanics, capability check governing the CLAUDE.md guidance block.
+- `USING_GBRAIN_WITH_GSTACK.md` "Conductor + GSTACK_* env vars" section — explains the prefix pattern, lists the four entry points that import the shim, points contributors at `CONTRIBUTING.md`.
+- `USING_GBRAIN_WITH_GSTACK.md` troubleshooting entries: "`/sync-gbrain` reports OK but `gbrain search` returns nothing semantic" (embeddings failed silently) and "`gbrain sync` blocked at a commit hash, `FILE_TOO_LARGE`" (5 MB hard limit, fix via `--skip-failed`).
+
+#### Changed
+
+- `bin/gstack-gbrain-sync.ts`, `bin/gstack-model-benchmark`, `scripts/preflight-agent-sdk.ts`, `test/helpers/e2e-helpers.ts` — added `import "../lib/conductor-env-shim";` at the top of each. One line each, side-effect-only.
+- `USING_GBRAIN_WITH_GSTACK.md` "three paths" → "four paths" header now that Path 4 (remote MCP) is documented as a first-class choice.
+- `USING_GBRAIN_WITH_GSTACK.md` environment variables table — added rows for `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GSTACK_OPENAI_API_KEY`, `GSTACK_ANTHROPIC_API_KEY` covering what reads each one and the GSTACK_-prefix fallback.
+- `CONTRIBUTING.md` "Conductor workspaces" — new paragraph documenting the `GSTACK_*` prefix injection pattern, the shim file, and the four entry points that already import it.
+
+#### For contributors
+
+- New TS entry points that hit Anthropic or OpenAI APIs (paid evals, `claude-agent-sdk`, gbrain embeddings, model benchmarks) should add `import "../lib/conductor-env-shim";` as the first import. Without it, the entry point ships broken inside Conductor even though it works in a bare shell. The contributor checklist in `CONTRIBUTING.md`'s "Conductor workspaces" block names the four entry points already wired up.
+
 ## [1.39.1.0] - 2026-05-15
 
 ## **Plan-mode reviews now enforce a blocking ExitPlanMode gate.**